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

Solver flags

During each step of the iteration, AGNI will flag the solver status to indicate what was done and if any problems arose. These flags are separated by a hyphen (-).

Potential solver flags are:

• Cs or Cf - chemistry and condensation schemes either (s)ucceeded or (f)ailed
• Gg - radiative transfer performed with double-grey scheme
• M or Mr - convective fluxes are being modulated for stability
• C2 or C4 or F2 or F4- a central or forward finite-difference scheme was used (at 2nd or 4th order)
• Ls - a linesearch method was applied
• P - step was forcibly extrapolated because the solver is not making good progress
• U - the atmosphere has become gravitationally unbound

Grids of models parallelised with multiple processes

The code is not explicitly parallelised. However, there is functionality to run a grid of models using by the script located at misc/grid/worker.jl. This script operates a single worker (of potentially many). All parameter configuration should be done by editing the worker.jl file directly.

For example, to run worker ID=1 and allocate two workers to the whole grid:

julia --project=. misc/grid/worker.jl 1 2

By allocating multiple workers and running them simultaneously using the manager script, which is located at misc/grid/manager.jl, we can parallelise the simulations. The number of workers is defined by the number of threads with which the manager script is run.

For example, run this manager script with four threads (and thus have four workers):

julia -t4 misc/grid/manager.jl

The manager script can also be executed on a HPC cluster by using the Slurm workload manager - assuming it is available on your server. You should then define the number of workers (and the allotted time) inside slurm.sh by setting cpus-per-task=XX.

For example:

sbatch --export=ALL misc/grid/slurm.sh

Once finished, combine the results of these workers by using the consolidate.jl script. This will generate consolidated_* files (2 CSV, 1 NetCDF) in the root folder of the grid.

For example, assuming that the grid root is located at the path out/:

julia misc/grid/consolidate.jl out/

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. There are three main ways to set the composition: partial pressures (p_dict), mixing ratios (vmr_dict or vmr_file), or by metallicities (metallicities).

[execution]

Parameters that tell the model what to do.

[physics]

Parameters that describe how the model should treat the physics.

[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, tmp : apply an isothermal stratosphere at temperature tmp
  • iso, tmp : set the whole atmosphere to be isothermal at temperature tmp
  • csv, pth : set the temperature profile using the CSV file at the file path pth
  • sat, gas : apply Clausius-Clapeyron saturation curve for the gas gas
  • ncdf, pth : load profile from the NetCDF file located at pth
  • loglin, tmp : log-linear profile between tmp_surf at the bottom and tmp 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. Provide tmp="Teq" to have AGNI automatically substitute-in the planet's radiative equilibrium temperature here.

• physics.chemistry enables a calculation of equilibrium thermochemistry in the atmosphere. This is handled externally by FastChem, so you must set the environment variable FC_DIR to point to the FastChem directory. More information on the chemistry is available on the Equilibrium chemistry page.

• physics.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.