diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index d11cecf7..c53eda75 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.6","generation_timestamp":"2024-10-30T12:44:47","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.6","generation_timestamp":"2024-10-30T13:13:16","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/examples/index.html b/dev/examples/index.html index 0bb3f625..e995a1e7 100644 --- a/dev/examples/index.html +++ b/dev/examples/index.html @@ -3,4 +3,4 @@

We can also plot the outgoing emission spectrum and normalised longwave contribution function (CF). The spectrum clearly demonstrates complex water absorption features, and exceeds blackbody emission at shorter wavelengths due to Rayleigh scattering. The CF quantifies how much each pressure level contributes to the outgoing emission spectrum at a given wavelength – this is then plotted versus wavelength and pressure.


- + diff --git a/dev/index.html b/dev/index.html index 8ff36a54..19227449 100644 --- a/dev/index.html +++ b/dev/index.html @@ -2,4 +2,4 @@ Home · AGNI
GitHub

A radiative-convective model for lava planet atmospheres -

A numerical model for the atmospheres of hot rocky (exo)planets. AGNI's primary purpose is to simulate the evolving atmospheres of magma ocean planets, while ensuring that radiative-convective equilibrium is sufficiently maintained.

Follow Getting started for information on installing the code and obtaining results.

Contact: harrison[dot]nicholls[at]physics.ox.ac.uk

GitHub: https://github.com/nichollsh/AGNI

Pronounced: ag-nee. Named after the fire deity of Hinduism.

This software is available under the GPLv3. Copyright (C) 2024 Harrison Nicholls.

+

A numerical model for the atmospheres of hot rocky (exo)planets. AGNI's primary purpose is to simulate the evolving atmospheres of magma ocean planets, while ensuring that radiative-convective equilibrium is sufficiently maintained.

Follow Getting started for information on installing the code and obtaining results.

Contact: harrison[dot]nicholls[at]physics.ox.ac.uk

GitHub: https://github.com/nichollsh/AGNI

Pronounced: ag-nee. Named after the fire deity of Hinduism.

This software is available under the GPLv3. Copyright (C) 2024 Harrison Nicholls.

diff --git a/dev/manual/index.html b/dev/manual/index.html index 87899b32..7cd2fe88 100644 --- a/dev/manual/index.html +++ b/dev/manual/index.html @@ -1,2 +1,2 @@ -Development · AGNI
GitHub

Development manual

Contributing

If you are interested in contributing to the model, please contact the developers using the information on the main page.

Coding style

  • Indentation uses 4 spaces, no tabs.
  • Function names should be lowercase, with words separated by underscores .
  • Lines should aim to have a length of no more than 92 characters.
  • All functions should have docstrings, ideally with Arguments and Returns listed.
  • More comments are always better, even if they seem redundant.
  • Use type hinting where possible.
  • Print statements should be made through the logger where possible.
  • The core package code should not contain global variables, except in the phys module.

Code reference

To be completed.

+Development · AGNI
GitHub

Development manual

Contributing

If you are interested in contributing to the model, please contact the developers using the information on the main page.

Coding style

  • Indentation uses 4 spaces, no tabs.
  • Function names should be lowercase, with words separated by underscores .
  • Lines should aim to have a length of no more than 92 characters.
  • All functions should have docstrings, ideally with Arguments and Returns listed.
  • More comments are always better, even if they seem redundant.
  • Use type hinting where possible.
  • Print statements should be made through the logger where possible.
  • The core package code should not contain global variables, except in the phys module.

Code reference

To be completed.

diff --git a/dev/model/index.html b/dev/model/index.html index a7904824..0ef6583b 100644 --- a/dev/model/index.html +++ b/dev/model/index.html @@ -26,4 +26,4 @@ ... \\ T_N \\ T_s -\end{pmatrix}\]

where $T_s$ is the surface temperature. Cell-edge temperatures in the bulk atmosphere are interpolated using the PCHIP algorithm, which avoids Runge's phenomenon and overshooting. The bottom- and top-most cell edge temperatures are extrapolated by estimation of $dT/d \log p$. Cell properties (heat capacity, gravity, density, average molecular weight, etc.) are consistently updated at each evaluation of $\bm{r}$. Condensation/rainout are also handled at each evaluation of $\bm{r}$ in order to avoid supersaturation.

The model converges when the cost function $c(\bm{x}) = \sqrt{\sum_i |r_i|}$ satisfies the condition

\[c(\bm{x}) < c_a + c_r \cdot \underset{i}{\max} \text{ } |F_i|\]

which represents a state where the fluxes are sufficiently conserved.

Iterative steps

The model solves for $\bm{x}$ iteratively, starting from some initial guess. The initial guess should be any reasonable temperature profile which is not significantly cooler than the expected solution. The flowchart below broadly outlines the solution process.

The Jacobian matrix $\bm{J}$ represents the directional gradient of the residuals with respect to the solution vector. It is a square matrix with elements set according to

\[J_{uv} = \frac{\partial r_u}{\partial x_v}\]

AGNI estimates $\bm{J}$ using finite-differences, requiring $N+1$ evalulations of $\bm{r}$ in order to fill the matrix. This corresponds to $2(N+1)+1$ objective function calculations under a 2nd order central-difference scheme. Each level $v$ with temperature $x_v$ is perturbed by an amount $\pm \varepsilon x_v$ in order to fill a single column of $\bm{J}$. As such, it can be expensive to construct a full Jacobian, especially when it is discarded at the end of each iteration. To reduce the total number of calculations AGNI retains some of the columns in $\bm{J}$ between model iterations. This assumes that the second derivative of the residuals is small. A column $v$ is retained only when

\[\max |r_i| \lt 0.7 \text{ for } i \in \{v-1, v, v+1\}\]

and when $c(\bm{x})/10$ does not satisfy the convergence criteria.

With a Jacobian constructed, we can calculate an update $\bm{d}$ to the solution vector $\bm{x} \rightarrow \bm{x} + \bm{d}$. This is primarily done via the Newton-Raphson method

\[\bm{d} = -\bm{J}^{-1} \bm{r}\]

but can alternatively be performed via the Gauss-Newton and Levenberg–Marquardt methods.

It is possible for the model to become stuck in a local minimum, leading to very small values of $|\bm{d}|$. This is identified when $c(\bm{x})$ has seen little change over the last few iterations. When this occurs, the model is 'nudged' by scaling the update via

\[\bm{d} \rightarrow 3 \bm{d}\]

In many cases $\bm{d}$ is too large, leading to instabilities. This is due to the non-convexity of the solution space, and the somewhat discontinuous nature of the physics involved (particularly in its temperature derivatives). When $|\bm{d}|>d_{\text{max}}$, the update is crudely scaled via

\[\bm{d} \rightarrow d_{\text{max}} \hat{\bm{d}}\]

The update may also be scaled by a linesearch

\[\bm{d} \rightarrow \alpha \bm{d}\]

on $\alpha$. This is applied if the full step $\bm{d}$ would increase the cost by an unacceptable amount. If the model is close to convergence then a golden-section search method is used to determine the optimal $\alpha$, otherwise a backtracking method is used. This means that the model is (mostly) able to avoid oscillating around a solution. All three of these scalings to $\bm{d}$ preserve its direction.

Other features

AGNI can calculate emission spectra, provided with T(p) and the volume mixing ratios of the gases. This is performed using the same RT as the RCE calculations, so is limited in resolution by the choice of correlated-k bands. Similarly, the longwave contribution function can also be calculated.

Julia and Fortran

AGNI is primarily written in Julia, while SOCRATES itself is written in Fortran. Julia was chosen because it allows the SOCRATES binaries to be included in the precompiled code, which significantly improves performance.

+\end{pmatrix}\]

where $T_s$ is the surface temperature. Cell-edge temperatures in the bulk atmosphere are interpolated using the PCHIP algorithm, which avoids Runge's phenomenon and overshooting. The bottom- and top-most cell edge temperatures are extrapolated by estimation of $dT/d \log p$. Cell properties (heat capacity, gravity, density, average molecular weight, etc.) are consistently updated at each evaluation of $\bm{r}$. Condensation/rainout are also handled at each evaluation of $\bm{r}$ in order to avoid supersaturation.

The model converges when the cost function $c(\bm{x}) = \sqrt{\sum_i |r_i|}$ satisfies the condition

\[c(\bm{x}) < c_a + c_r \cdot \underset{i}{\max} \text{ } |F_i|\]

which represents a state where the fluxes are sufficiently conserved.

Iterative steps

The model solves for $\bm{x}$ iteratively, starting from some initial guess. The initial guess should be any reasonable temperature profile which is not significantly cooler than the expected solution. The flowchart below broadly outlines the solution process.

The Jacobian matrix $\bm{J}$ represents the directional gradient of the residuals with respect to the solution vector. It is a square matrix with elements set according to

\[J_{uv} = \frac{\partial r_u}{\partial x_v}\]

AGNI estimates $\bm{J}$ using finite-differences, requiring $N+1$ evalulations of $\bm{r}$ in order to fill the matrix. This corresponds to $2(N+1)+1$ objective function calculations under a 2nd order central-difference scheme. Each level $v$ with temperature $x_v$ is perturbed by an amount $\pm \varepsilon x_v$ in order to fill a single column of $\bm{J}$. As such, it can be expensive to construct a full Jacobian, especially when it is discarded at the end of each iteration. To reduce the total number of calculations AGNI retains some of the columns in $\bm{J}$ between model iterations. This assumes that the second derivative of the residuals is small. A column $v$ is retained only when

\[\max |r_i| \lt 0.7 \text{ for } i \in \{v-1, v, v+1\}\]

and when $c(\bm{x})/10$ does not satisfy the convergence criteria.

With a Jacobian constructed, we can calculate an update $\bm{d}$ to the solution vector $\bm{x} \rightarrow \bm{x} + \bm{d}$. This is primarily done via the Newton-Raphson method

\[\bm{d} = -\bm{J}^{-1} \bm{r}\]

but can alternatively be performed via the Gauss-Newton and Levenberg–Marquardt methods.

It is possible for the model to become stuck in a local minimum, leading to very small values of $|\bm{d}|$. This is identified when $c(\bm{x})$ has seen little change over the last few iterations. When this occurs, the model is 'nudged' by scaling the update via

\[\bm{d} \rightarrow 3 \bm{d}\]

In many cases $\bm{d}$ is too large, leading to instabilities. This is due to the non-convexity of the solution space, and the somewhat discontinuous nature of the physics involved (particularly in its temperature derivatives). When $|\bm{d}|>d_{\text{max}}$, the update is crudely scaled via

\[\bm{d} \rightarrow d_{\text{max}} \hat{\bm{d}}\]

The update may also be scaled by a linesearch

\[\bm{d} \rightarrow \alpha \bm{d}\]

on $\alpha$. This is applied if the full step $\bm{d}$ would increase the cost by an unacceptable amount. If the model is close to convergence then a golden-section search method is used to determine the optimal $\alpha$, otherwise a backtracking method is used. This means that the model is (mostly) able to avoid oscillating around a solution. All three of these scalings to $\bm{d}$ preserve its direction.

Other features

AGNI can calculate emission spectra, provided with T(p) and the volume mixing ratios of the gases. This is performed using the same RT as the RCE calculations, so is limited in resolution by the choice of correlated-k bands. Similarly, the longwave contribution function can also be calculated.

Julia and Fortran

AGNI is primarily written in Julia, while SOCRATES itself is written in Fortran. Julia was chosen because it allows the SOCRATES binaries to be included in the precompiled code, which significantly improves performance.

diff --git a/dev/setup/index.html b/dev/setup/index.html index d9f752c4..03086893 100644 --- a/dev/setup/index.html +++ b/dev/setup/index.html @@ -1,2 +1,2 @@ -Getting started · AGNI
GitHub

Getting started

This page outlines requirements and installation steps for the code. Currently, GNU/Linux and MacOS (including ARM) are supported.

Requirements

  • gfortran
  • NetCDF library for FORTRAN
  • make
  • curl
Warning

Do not install Julia using your system package manager. Install only from julialang.org

Installation

Follow the steps below in order to setup the code.

  1. Install Julia: curl -fsSL https://install.julialang.org | sh
  2. Download AGNI: git clone https://github.com/nichollsh/AGNI.git
  3. Change directory: cd AGNI
  4. Setup SOCRATES by doing either ONE of the following...
    • Follow the instructions on the SOCRATES GitHub page
    • Run source get_socrates.sh
  5. julia -e 'using Pkg; Pkg.activate("."); Pkg.build()'

AGNI is now installed as a package into a Julia environment in the AGNI directory. This will also have downloaded some basic input data. You should run the tests next.

Tip

The src/get_socrates.sh script automatically adds the radiation code to your environment with the variable RAD_DIR, which points to the SOCRATES installation. This variable must be set whenever AGNI is being used.

Testing

Now try running the tests in your terminal.

julia ./test/runtests.jl

This will print information on whether tests passed or failed.

Using the code

See Running the model for information on using the code. See Troubleshooting for troubleshooting advice.

+Getting started · AGNI
GitHub

Getting started

This page outlines requirements and installation steps for the code. Currently, GNU/Linux and MacOS (including ARM) are supported.

Requirements

  • gfortran
  • NetCDF library for FORTRAN
  • make
  • curl
Warning

Do not install Julia using your system package manager. Install only from julialang.org

Installation

Follow the steps below in order to setup the code.

  1. Install Julia: curl -fsSL https://install.julialang.org | sh
  2. Download AGNI: git clone https://github.com/nichollsh/AGNI.git
  3. Change directory: cd AGNI
  4. Setup SOCRATES by doing either ONE of the following...
    • Follow the instructions on the SOCRATES GitHub page
    • Run source get_socrates.sh
  5. julia -e 'using Pkg; Pkg.activate("."); Pkg.build()'

AGNI is now installed as a package into a Julia environment in the AGNI directory. This will also have downloaded some basic input data. You should run the tests next.

Tip

The src/get_socrates.sh script automatically adds the radiation code to your environment with the variable RAD_DIR, which points to the SOCRATES installation. This variable must be set whenever AGNI is being used.

Testing

Now try running the tests in your terminal.

julia ./test/runtests.jl

This will print information on whether tests passed or failed.

Using the code

See Running the model for information on using the code. See Troubleshooting for troubleshooting advice.

diff --git a/dev/troubleshooting/index.html b/dev/troubleshooting/index.html index 4aafbb66..2e0b4256 100644 --- a/dev/troubleshooting/index.html +++ b/dev/troubleshooting/index.html @@ -1,3 +1,3 @@ Troubleshooting · AGNI
GitHub

Troubleshooting

This page may be useful if you are having problems. However, I would suggest that you also double check the Getting started instructions.

Julia errors on start, potentially referencing the CURL library

It is important that the shell environment variable LD_LIBRARY_PATH is not set when running AGNI. This will cause Julia to use the wrong libraries, which will causes problems. You can unset this variable or reset using either of the following commands

unset LD_LIBRARY_PATH
-export LD_LIBRARY_PATH=""

If this does not help, it's possible that you are using a Julia distribution provided by your system package manager. It's important that you only use Julia distributed from the official website.

Cannot find SOCRATES

Check the installation instructions. Have you set RAD_DIR? Try running l_run_cdf in the terminal; if this fails, then SOCRATES has not compiled or you haven't added it to your PATH.

Spectral file does not exist

Check the path in the configuration file. Download additional spectral files using the get_data script in the AGNI root directory. For example, for additional pure-steam spectral files you would run

./src/get_data.sh steam

Finally...

If you are still stuck, or feel that there is a problem with the code, then you can contact the authors using the information on the main page.

+export LD_LIBRARY_PATH=""

If this does not help, it's possible that you are using a Julia distribution provided by your system package manager. It's important that you only use Julia distributed from the official website.

Cannot find SOCRATES

Check the installation instructions. Have you set RAD_DIR? Try running l_run_cdf in the terminal; if this fails, then SOCRATES has not compiled or you haven't added it to your PATH.

Spectral file does not exist

Check the path in the configuration file. Download additional spectral files using the get_data script in the AGNI root directory. For example, for additional pure-steam spectral files you would run

./src/get_data.sh steam

Finally...

If you are still stuck, or feel that there is a problem with the code, then you can contact the authors using the information on the main page.

diff --git a/dev/usage/index.html b/dev/usage/index.html index da2158f5..731b6740 100644 --- a/dev/usage/index.html +++ b/dev/usage/index.html @@ -1,2 +1,2 @@ -Running the model · AGNI
GitHub

Running the model

First, follow the Getting started instructions. Only read-on once you have confirmed that the code is working.

Input data files

The minimal input data required to run the model will have been downloaded automatically. 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:

./get_data.sh

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, and can be done by running source path/to/socrates/set_rad_env in your terminal.

Then to use the model, simply run ./agni.jl [cfg] where [cfg] is the path to the required configuration file. If [cfg] is not passed, then the default configuration will be used.

To calculate equilibrium chemistry self-consistently with the climate, FastChem is coupled to AGNI. For AGNI to find FastChem, the environment variable FC_DIR must point to the FastChem installation directory.

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.

Broadly, the configuration files are broken up into four sections:

  • [planet] - general characteristics of the planet
  • [files] - input/output files and other paths
  • [composition] - atmospheric composition and chemistry
  • [execution] - what the model should do
  • [plots] - which plots should be produced

Some parameters:

  • files.input_sf is the file path to the "spectral file" containing opacity data. Several spectral files are packged with AGNI, but you can find more online via the Open Science Framework.

  • 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, with tmp_surf set such that the conductive skin (CBL) conserves energy flux
    • 3 : the net flux (up minus down) at each layer is equal to flux_int

  • execution.solvers tells the model which solvers to use. This is a list of strings, so multiple solvers can be applied sequentially. An empty string is always appended to the end of this list. 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

  • 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

    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.chem_type 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)

Outputs

Results are optionally plotted and animated, and data will be saved as NetCDF or CSV files.

Python

It is possible to interact with the model using Python. This is best done with the juliacall package from PythonCall.jl, and is implemented this way in the PROTEUS framework.

+Running the model · AGNI
GitHub

Running the model

First, follow the Getting started instructions. Only read-on once you have confirmed that the code is working.

Input data files

The minimal input data required to run the model will have been downloaded automatically. 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:

./get_data.sh

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, and can be done by running source path/to/socrates/set_rad_env in your terminal.

Then to use the model, simply run ./agni.jl [cfg] where [cfg] is the path to the required configuration file. If [cfg] is not passed, then the default configuration will be used.

To calculate equilibrium chemistry self-consistently with the climate, FastChem is coupled to AGNI. For AGNI to find FastChem, the environment variable FC_DIR must point to the FastChem installation directory.

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.

Broadly, the configuration files are broken up into four sections:

  • [planet] - general characteristics of the planet
  • [files] - input/output files and other paths
  • [composition] - atmospheric composition and chemistry
  • [execution] - what the model should do
  • [plots] - which plots should be produced

Some parameters:

  • files.input_sf is the file path to the "spectral file" containing opacity data. Several spectral files are packged with AGNI, but you can find more online via the Open Science Framework.

  • 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, with tmp_surf set such that the conductive skin (CBL) conserves energy flux
    • 3 : the net flux (up minus down) at each layer is equal to flux_int

  • execution.solvers tells the model which solvers to use. This is a list of strings, so multiple solvers can be applied sequentially. An empty string is always appended to the end of this list. 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

  • 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

    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.chem_type 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)

Outputs

Results are optionally plotted and animated, and data will be saved as NetCDF or CSV files.

Python

It is possible to interact with the model using Python. This is best done with the juliacall package from PythonCall.jl, and is implemented this way in the PROTEUS framework.