Command line & configuration file

Pytmosph3R can be run from the command-line using a configuration file. The command is pytmosph3r and the associated options include:

• -v : generate all useful outputs (see Outputs)

• -i/-o : Input configuration file, output directory

• -h : Help!

For a longer documentation of the command-line parameters, see Command-line arguments. The sections of the configuration file are explained below.

Note

Other commands relative to the usage of Pytmosph3R exist, all starting with pytmosph3r-, such as pytmosph3r-plot which can be used to plot various types of data (see Plots), or tools to convert netCDF to HDF5, etc.

Configuration file

Examples of configuration files may be found in the folder examples/ of the repository. For example, a simple isothermal case, which doesn’t require an input data file, can be run from the command line with:

pytmosph3r -i examples/isothermal.cfg

The configuration file lists multiple categories that we explain here. A global section lists the global parameters of Pytmosph3R. There is only one for the moment:

[Global]
relative_dir = .

relative_dir is used to shorten the other paths set in the configuration file. By default it is the installation directory of Pytmosph3R. You can set it as a relative path from the installation directory of Pytmosph3R, or as a global path. For example, if you set it to .., it will be set to the parent directory of Pytmosph3R. Set it to /home/<user> for the home directory of <user>.

Note

Relative paths follow the installation directory of Pytmosph3R! Use pip install -e . to “install” the code in the development directory.

Exo_k

The parameters concerning exo_k are stored in a section delimited by [Exo_k]:

[Exo_k]
xsec_path = /relative/path/to/xsec/
cia_path = /relative/path/to/cia/
convert = True

• xsec_path (doc) is the path to the cross-section data files (can be relative to relative_dir).

• cia_path (doc) is the path to the collision-induced absorption data files (can be relative to relative_dir).

• convert (doc) tells Exo_k to force the code to use SI units.

Model

Parameters concerning the overall model go into the section [Model]:

[Model]
type = diagfi
filename = examples/diagfi_synchronous_earth.nc
n_vertical = 95
interp = linear

• type may be either diagfi, hdf5, simple or the path to your own model (to customize the loading of your own model, see note below). The simple case takes no input file. The first two are based on a input file, either a diagfi.nc file generated from the LMDZ GCM, or an HDF5 file generated by Pytmosph3R itself. See model for more information on each model type.

• filename (only for “diagfi” or “hdf5” models) is the path to the file containing the necessary data for running Pytmosph3R (can be relative to relative_dir).

The other parameters are described in Model.

Note

To run without an input data file, use the ‘simple’ model type.

Note

You can create your own input class by setting type = path/to/model.py! Copy the diagfimodel.py for example, or inherit from it, and change it at will!

Atmosphere

The input atmosphere is configured in [Atmosphere]:

[Atmosphere]
    max_pressure = 1e6
    min_pressure = 1e-5
    temperature = 2500
    transparent_gases = O2, N2
    [[chemistry]]
        type = parmentier2018 # or 'fastchem', 'interpolation' or /path/to/chemistry.py
        gases = H2O
    [[gas_mix_ratio]] # Volume Mixing Ratio
        H2O = 5e-4
        N2 = 1e-5
        O2 = 2e-5
        CO2 = background
    [[aerosols]] # if you have clouds
        [[[H2O]]]
            mmr = 1.e-5 # Mass Mixing Ratio (in kg/kg)
            reff = 1.e-5 # Effective radius (in meters)
            condensate_density = 940 # in kg/m^3

• max_pressure (in Pa) may be used in conjunction with min_pressure to define a simple 1D pressure vertical profile between these bounds. If you’re using an input file, it is ignored.

• min_pressure may also be used (without max_pressure) to define the upper atmosphere bound of the input model when using an input file. It will truncate the atmosphere to that minimum pressure. If your lowest input pressure is not 0 and you would like a min_pressure lower than your input model, please add an extra level in your input model with a pressure of 0. As an example, if min_pressure = .0001 and your minimum pressure is 1 Pa, the top pressure in the model stays at 1 Pa. If your minimum pressure is 0, it will be replaced with .0001.

• temperature may also be used to override the temperature from the input file. It must be a scalar value to create an isothermal case.

• transparent_gases is the list of transparent gases which are considered without molecular absorption.

• chemistry (optional) is a chemistry module that computes volume mixing ratios using the atmospheric input model. ‘type’ specifies which module to use (among ‘parmentier2018’, ‘fastchem’ or a path to a python file containing a module that inherits from Chemistry). The rest (‘gases’ for example) are arguments of the module.

• gas_mix_ratio lists the gases to put in the atmosphere and their volume mixing ratios. If a gas was already present in the atmosphere in the input file, it is overridden by this value. The term background is used by Exo_k to fill the atmosphere with a background gas so that the total sum of all volume mixing ratios is equal to 1.

• aerosols lists the aerosols to put in the atmosphere and their physical characteristics. If a value for an aerosol was already present in the atmosphere in the input file, it is overridden by this parameter.

Radiative Transfer

Parameters for the radiative transfer are given in sections specific to each mode. For example [Transmission] is used for generating transmission spectra. You could set a number of light rays using:

[Transmission]
    [[rays]]
        n_radial = 100
        n_angular = 20

• rays (only in transmission mode) defines the number of points on the polar grid discretizing the plane of the sky, by which the rays go through orthogonally, centered around the center of the planet.

A simple example of emission parameters would be:

[Emission]
    n_phases = 20
    planet_to_star_flux_ratio = True

• n_phases sets the number of phases to consider during the phase curve (it also activates the phase curve mode, incidentally).

• planet_to_star_flux_ratio changes the output spectrum from a planet flux only to a planet-to-star flux ratio.

See Transmission for the (optional) parameters that can be passed over to the transmission module, and Emission for the emission mode.

A Lightcurve mode and a Phasecurve mode and are also available.

You can generate transmission and emission spectra, plus light- and phase-curves in one run. Keep in mind it will also take more time to compute!

Other sections

A section [Grid] may be used to define a new input grid of the atmosphere (for example when one does not have a input file with some relevant data). Its parameters are described in Grid.

You can set the position of the observer in the [Observer] section, defined by a latitude and a longitude on the unit sphere, given in degrees. See Observer for more details.

A section [Opacity] configures the contributions (Rayleigh, CIA) to consider. Its parameters are described in Opacity.

A section [Star] may be used to define the star of the model. See Star for its parameters.

A section [Planet] may be used to (re)define the planet of the model. See Planet for its parameters.

Note

Keep in mind the structure of the configuration file follows automatically the structure of each object. The configuration file is converted to a global dictionary and each of its keys is then recursively transformed into the objects constituting the model of Pytmosph3R. Indeed, in python, attributes of an instance of a class are also the keys of the dictionary associated to the object.

Command-line arguments