Python front-end: Conventions for user facing code

[RobertPincus]

Points for discussion about how user-facing code should operate, assuming that we've worked through the encapsulation of optical properties, sources, and boundary conditions in #31. We assume that the pyRTE-RRTMGP consumes and produces xarray.Datasets.

_Interpreting data _

Gas optics calculations require temperature, pressure, and gas concentrations. Our initial design, consistent with the Fortran front-end, requires temperature and pressure in layers and at their edges (levels) and concentrations in layers; there is one more level than layer. These decisions could be open for discussion.

Arrays should by default be identifiable by name ("temperature," "co2_vmr", or whatever we decide) or CF standard name[1] ("air_temperature", "mole_fraction_of_carbon_dioxide_in_air"), noting that two arrays with different vertical coordinates (layer and level) are required for temperature and pressure.

Users should be able to provide an explicit map between the structure of their dataset and something interpretable by pyRTE-RRTMGP. Does that look like an optional dictionary? Do we expect/show people how to use .pipe()?

The underlying Fortran code assumes MKS (meter/kilogram/second) units. Having the Python code do unit conversion is a low priority but checking any available units as part of input sanitizing is sensible.

Simplifying interactions

There should be a single user-facing rte.solve() function that determines which kernels to call based on the set of optical properties and sources+boundary conditions provided.

By default flux calculations should return broadband (spectrally-integrated) fluxes up and down. The first implementations have returned two numpy array but these should be combined into a single xarray dataset with units and attributes set by the CF conventions. For example

fluxes = rte.solve(optical_props, sources, bcs)
print (fluxes.flux_dn, fluxes.flux_up)

Shortwave problems could also return fluxes.flux_dir to represent the direct beam; this output could be optional to save memory.

Longwave problems could also optionally return the Jacobian of upward flux with respect to surface temperature, though this likely isn't useful in Python contexts.

Users may also want to reduce the spectrally-detailed calculations in some specific way. The Fortran front-end allows this by having a class with built-in reduction methods. The same spirit in Python (I guess) would be to accept a callable the produces the output to be returned. Would an alternative be to return spectrally-detailed information if requested so users can write .pipe()s?

[1] CF is the Climate and Forecast conventions. The standard name table is published online.