.. _config_file: 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/`` for the home directory of . .. 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 :class:`~pytmosph3r.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 :class:`~pytmosph3r.model.model.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 :class:`~pytmosph3r.chemistry.chemistry.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 :class:`~pytmosph3r.transmission.Transmission` for the (optional) parameters that can be passed over to the transmission module, and :class:`~pytmosph3r.emission.Emission` for the emission mode. A :class:`~pytmosph3r.lightcurve.Lightcurve` mode and a :class:`~pytmosph3r.phasecurve.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 :class:`~pytmosph3r.grid.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 :class:`~pytmosph3r.rays.Observer` for more details. A section ``[Opacity]`` configures the contributions (Rayleigh, CIA) to consider. Its parameters are described in :class:`~pytmosph3r.opacity.Opacity`. A section ``[Star]`` may be used to define the star of the model. See :class:`~pytmosph3r.star.Star` for its parameters. A section ``[Planet]`` may be used to (re)define the planet of the model. See :class:`~pytmosph3r.planet.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 --------------------------- .. argparse:: :ref: pytmosph3r.parser.pytmosph3r_parser :prog: pytmosph3r