Using the model

Follow the Getting started instructions. Only read on once you have confirmed that the model runs on your machine. Otherwise, see the Troubleshooting guide.

Input data files

The minimal input data required to run the model will have been downloaded automatically from Zenodo. If you require more data, such as additional stellar spectra or opacities, then these can also be easily obtained using the get_data script in the AGNI root directory. To see how to use this script, run it without arguments like so:

./src/get_data.sh

Opacities are contained within "spectral files". Use the table within res/spectral_files/reference.pdf to decide which spectral files are best for you.

For example, if you wanted to get the spectral file "Honeyside48" you would run:

./src/get_data.sh anyspec Honeyside 48

Tutorials

There are Jupyter notebooks containing tutorials in the tutorials/ directory of the repository.

General execution

The environment variable RAD_DIR must point to the SOCRATES installation directory. This is required for AGNI to find the SOCRATES libraries. The best way to do this is to add RAD_DIR=path/to/socrates/folder/ to your shell rc file (e.g. ~/.bashrc).

Then to use the model, simply run

./agni.jl [cfg]

where [cfg] is the path to the desired configuration file. If [cfg] is not passed, then the default configuration file will be used.

You should see the following output:

[ INFO  ] Using configuration 'Default'
[ INFO  ] Setting-up a new atmosphere struct
[ INFO  ] Loading thermodyamic data
[ INFO  ] Inserting stellar spectrum and Rayleigh coefficients
[ INFO  ] Allocating atmosphere with composition:
[ INFO  ]       1 H2O     1.00e+00 (EOS_AQUA)
[ INFO  ] Setting T(p): dry, sat
[ INFO  ] Solving with 'none'
[ INFO  ]     done
[ INFO  ] Total RT evalulations: 2
[ INFO  ] Writing results
[ INFO  ] Plotting results
[ INFO  ] Deallocating memory
[ INFO  ] Model runtime: 16.60 seconds

The line following "Allocating atmosphere with composition" is a table of gases, their volume mixing ratios, and flags. In this case there is only one gas.

Potential flags for each species are:

• EOS_[XX] - using the [XX] equation of state (e.g. ideal gas, AQUA)
• NO_OPACITY - no opacity data available, but can contribute to the thermodynamics
• NO_THERMO - no thermodynamic data available, so will be treated as a diatomic ideal gas
• COND - this gas is allowed to condense

Configuration

AGNI configuration files are formatted using TOML. There are examples in res/config/. The default configuration file contains comments explaining the purpose of each parameter, although some are explained in greater detail below. Take care to format the variables in the TOML file correctly. There are no 'default values'. Not all parameters are required in all cases, but the model will return an error naming any parameters which are both necessary and absent.

The configuration files are broken up into four sections (or "tables"), each containing a number of parameters. These tables of parameters are described below.

[planet]

General properties of the planet.

[files]

Input/output files and other paths.

[composition]

Atmospheric composition and chemistry.

[execution]

Parameters that tell the model what to do.

[plots]

Configure plotting routines all of these should be true or false.

Details on specific parameters

• composition.transparent configures the atmosphere to be transparent. This works by setting the pressure to be small, and turning off the gas opacity. With this provided, the rest of the parameters in [configuration] are redundant. With this enabled, make sure to use the appropriate solver in the [execution] table.

• execution.solution_type tells the model which state to solve for. The allowed values (integers) are...

  • 1 : zero flux divergence at fixed tmp_surf
  • 2 : zero flux divergence such that the conductive skin (CBL) conserves energy flux with fixed tmp_magma
  • 3 : the net flux (up minus down) at each layer is equal to flux_int

  See the Model description page for an explanation of these solution types.

• execution.solver tells the model which solver to use. Allowed solvers are...

  • [empty string] : no solving takes place, so the model just calculates fluxes using the initial state
  • newton : the Newton-Raphson algorithm is used
  • gauss : the Gauss-Newton algorithm is used
  • levenberg : the Levenberg–Marquardt algorithm is used
  • transparent : solver to be used when composition.transparent=true.

• execution.initial_state describes the initial temperature profile applied to the atmosphere. This is a list of strings which are applied in the given order, which allows the user to describe a specific state as required. The descriptors are listed below, some of which take a single argument that needs to immediately follow the descriptor in the list order.

  • dry : integrate the dry adiabatic lapse rate from the surface upwards
  • str, arg : apply an isothermal stratosphere at arg kelvin
  • iso, arg : set the whole atmosphere to be isothermal at arg kelvin
  • csv, arg : set the temperature profile using the CSV file at the file path arg
  • sat, arg : apply Clausius-Clapeyron saturation curve for the gas arg
  • ncdf, arg : load profile from the NetCDF file located at arg
  • loglin, arg : log-linear profile between tmp_surf at the bottom and arg at the top
  • ana : use the Guillot (2010) analytical temperature solution

  For example, setting initial_state = ["dry", "sat", "H2O", "str", "180"] will set T(p) to follow the dry adiabat from the surface, the water condensation curve above that, and then to be isothermal at 180 K until the top of the model.

• composition.chemistry describes the type of chemistry to implement within the model. This is handled externally by FastChem, so you must set the environment variable FC_DIR to point to the FastChem directory. The allowed values (integers) are...

  • 0 : Disabled
  • 1 : Equilibrium, gas phase only
  • 2 : Equilibrium, with condensation (condensates retained)
  • 3 : Equilibrium, with condensation (condensates rained out)

  More information on the chemistry is available on the Equilibrium chemistry page

• execution.overlap_method tells SOCRATES which algorithm to use to combine gas opacities. The spectral files contain k-tables for pure gases, and combining these coefficients can be done in several ways. See Amundsen+2017 for a nice comparison of overlap methods. Allowed options are...

  • "ee" : equivalent extinction (fastest)
  • "rorr" : random overlap, with resorting and re-binning
  • "ro" : random overlap (most accurate, slowest)

Accessing AGNI from Python

It is possible to interact with AGNI from Python. This is best done with the juliacall package from PythonCall.jl.

Coupling with Python is done via juliacall within the modular PROTEUS framework, which couples AGNI self-consistently to models of planetary interior evolution and volatile outgassing. You can see this implemented in agni.py within the PROTEUS source code.

A skeleton example is given below:

# Import juliacall
from juliacall import Main as jl

# Import AGNI
jl.seval("using Pkg")
jl.Pkg.activate(AGNI_ROOT_DIR)  # <---- set AGNI_ROOT_DIR to your installation path
jl.seval("import AGNI")
jl.AGNI.setup_logging("out.log", 1)

# Setup atmosphere
atmos = jl.AGNI.atmosphere.Atmos_t()
jl.AGNI.atmosphere.setup_b(atmos, ...)   # <--- complete function arguments as per docstring in `AGNI.atmosphere.setup!()`

# Allocate atmosphere
jl.AGNI.atmosphere.allocate_b(atmos, STAR_SPECTRUM_FILE)   # <-- provide path to spectrum

# Solve T(p)
jl.AGNI.solver.solve_energy_b(atmos)

# Write results to a file
jl.AGNI.save.write_ncdf(atmos, "out.nc")

Line-by-line radiative transfer

Performed using the Reference Forward Model. You must provide a HITRAN-formatted .par file, setting the path via files.rfm_parfile. This parfile can contain absorption from multiple species, and can be obtained from hitran.org. Alternatively, get the parfiles stored on Zenodo using: ./src/get_data.sh parfiles.

Then, you must also set the variables execution.rfm_wn_min and execution.rfm_wn_max. These two parameters specify the wavenumber [cm-1] range over which to perform the LbL calculations. The wavenumber resolution is set to 1 cm-1.

Results are saved to the NetCDF file, alongside all the usual data, as rfm_wn and rfm_fl arrays.