README.md

# Scripts for simulating wide-field-of-view satellite measurements of top-of-atmosphere radiation fields

## Overview
These scripts form the basis of the analysis in "Sampling the diurnal and annual cycles of the Earth’s energy
imbalance with constellations of satellite-borne radiometers" by Hocking et al. (2024).

The code implements an idealised framework for satellite observations of top-of-atmosphere radiation.
Individual satellite orbits can be selected by choosing appropriate inclination, altitude and right ascension of the ascending node.
The footprint of the satellite determines the wide-field-of-view measurement at each measurement time.
The measurement time series are then processed to compute global annual means.

## Prerequisites
The python scripts rely on the libraries used in the environment file `./environment.yml`.
As input data, the scripts expect hourly TOA fluxes from the Clouds and Earth's Radiant Energy System (CERES) SYN1deg data product.
These files should be placed in `./Data/` according to the format in `./experiment/config.py`.
The processing also requires an installation of the Climate Data Operators (CDO) tool set, version 2.3.0 or later.

## Language
Python

## File description
```
.
├── README.md                                This document
├── environment.yml                          Python environment specifications
├── bin_satm_to_toagrid.py                   Process satellite measurements by binning them on a chosen grid
├── earth.py                                 Main script containing Earth class, for framework of the radiation fluxes
├── measure_file_to_nc_sgp4sat.py            Measure radiation from input file and save measurements to output file
├── process_satm_to_gridweights.py           Process satellite measurements to determine gridded distribution
├── satellite.py                             Main script containing satellite classes, for framework of measurement of Earth instances
├── smooth_file_with_satellite_footprint.py  Compute the convolution of the input file with the satellite footprint
├── split_CERES_files.py                     Convenience script for preparing input data files
├── unitsconstants.py                        Collection of units and constants
├── ceres_reference                          Directory with scripts to create CERES reference files, which are used in the processing of satellite measurements
├── diurnalcycle                             Directory with script to restructure input file in terms of local solar time, instead of e.g. GMT
└── experiment                               Directory with scripts to compute the measurements for a set of satellites.
```


## Pipeline
First, prepare the computing environment and the necessery input files according to the prerequisites.

In `ceres_reference`:
- Execute `make_ceres_ref_files.py`.

In `experiment`:
- Execute `main.py`.
- Execute `merge_day_to_year.py`.
- Execute `make_singlesat_annualmean.py`.
- Execute `make_combo_annualmean.py`.
- Execute `make_combo_annualmean_fillpoles.py`.

The output will be created in `experiment/fullperiodoutput`, `experiment/fullperiodoutput_filledpoles` and `experiment/singlesat_output`.

## Citation
Hocking et al. (2024) Sampling the diurnal and annual cycles of the Earth’s energy imbalance with constellations of satellite-borne radiometers. Software version 1.0.0. Bolin Centre Code Repository. 

## References
Hocking et al. (2024) Sampling the diurnal and annual cycles of the Earth’s energy imbalance with constellations of satellite-borne radiometers

## Comments
Any additional useful comments. This can e.g. be roles of persons involved in creating the source code.

## Authors
Thomas Hocking
Thorsten Mauritsen
Linda Megner

## Contact information
Thomas Hocking

Department of Meteorology, Stockholm University, Stockholm, Sweden

thomas.hocking [at] misu.su.se

## Publisher
Bolin Centre Code Repository

## Version
1.0.0

## Project URL
Main URL of the source code project (filled in by database staff).

## DOI
DOI of a particular version of the source code that shall be citable (filled in by database staff).

## License
Distributed under the GNU General Public License v3.0. See LICENSE text for more information.

## Publication date
Date when the version having the indicated DOI was made public (filled in by database staff).