From 5211cf364bf8444c2c1a9848692cebaaaea251cd Mon Sep 17 00:00:00 2001 From: Harrison Nicholls Date: Tue, 28 May 2024 09:33:15 +0100 Subject: [PATCH] Doc updates. Vscode config. Readme updates --- .gitignore | 1 - .vscode/settings.json | 4 ++++ README.md | 43 +++------------------------------------- docs/make.jl | 13 ++++++------ docs/src/index.md | 2 +- docs/src/manual/index.md | 7 +++++++ docs/src/model.md | 12 +++++------ docs/src/setup.md | 39 ++++++++++++++++++++++++++++++++++++ docs/src/usage.md | 7 +++---- 9 files changed, 68 insertions(+), 60 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 docs/src/manual/index.md create mode 100644 docs/src/setup.md diff --git a/.gitignore b/.gitignore index e2c8fb5e..a07d39c5 100644 --- a/.gitignore +++ b/.gitignore @@ -32,7 +32,6 @@ socstar.dat # Misc files .DS_Store -.vscode __pycache__ debug/ nogit_* diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..566a43aa --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "julia.environmentPath": "${workspaceFolder}/", + "editor.tabSize": 4 +} \ No newline at end of file diff --git a/README.md b/README.md index 3524cc6f..b8d27e3e 100644 --- a/README.md +++ b/README.md @@ -17,49 +17,12 @@ Consult the [AGNI Wiki](https://nichollsh.github.io/AGNI/) on GitHub for informa * `test/` - Package tests * `socrates/` - Directory containing SOCRATES and associated files (subject to the license therein) * `.github/` - GitHub workflows +* `.vscode/` - Visual Studio Code configuration * `agni.jl` - AGNI executable * `demo_steamrun.jl`- Script to demonstrate the pure-steam runaway greenhouse effect -## Requirements -* Julia (NB: install only from julialang.org - do not use your system package manager) -* gfortran (NB: do not use ifort or aocc) -* netcdf-fortran -* make -* OpenMP - -## Supported platforms -* MacOS (ARM and x86-64) -* GNU/Linux (x86-64) - -## Installation instructions -- `$ export LD_LIBRARY_PATH=""` -- `$ cd socrates` -- `$ ./configure` -- `$ ./build_code` -- `$ source set_rad_env` -- `$ julia` -- `julia> ]` -- `(@v1.10) pkg> activate ../` -- `(AGNI) pkg> instantiate` -- Press backspace -- `julia> cd("julia/src")` -- `julia> include("generate_wrappers.jl")` -- `julia> exit()` -- `$ cd julia/lib` -- `$ make` -- `$ cd ../../..` -You will end up in the root directory of the repository. -You should run the tests next. - -## Testing the code -- `$ julia` -- `julia> ]` -- `(@v1.10) pkg> activate .` -- `(AGNI) pkg> test` - -## Running the code -To run the program, execute `./agni.jl [cfg_path]`. If `[cfg_path]` is not provided, then the default configuration file will be used. -To demo the steam runaway greenhouse effect, execute `./demo_steamrun.jl`. +## Installation and usage +See the Getting Started page on the AGNI wiki for information on installing and using the model. ## Contributors * Harrison Nicholls diff --git a/docs/make.jl b/docs/make.jl index 43cf6a44..4abeee10 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -11,13 +11,12 @@ makedocs( sitename="AGNI", format=format, pages = [ - "Introduction" => ["index.md"], - "Model" => ["model.md"], - "Usage" => ["usage.md"], - "Examples" => ["examples/index.md"], - # "Subsection" => [ - # ... - # ] + "index.md", + "model.md", + "setup.md" , + "usage.md", + "examples/index.md", + "manual/index.md" ] ) diff --git a/docs/src/index.md b/docs/src/index.md index 898be3a0..87cde1c8 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -5,7 +5,7 @@ AGNI is a computer code for modelling the atmospheres of hot terrestrial (exo)pl The model itself is currently proprietary. I will be made available under the BSD 3-Clause Clear License once published in a journal. Do not publish with the model before such a time; it is undergoing active development. -See the other wiki pages for information on installing the code, running the code, and obtaining results. The content of this wiki is outlined on the right hand side of this web page. +See the other wiki pages for information on installing the code, running the code, and obtaining results. The content of this wiki is outlined on the left hand side of this web page. Pronounced: _ag-nee_. Named after the fire deity of Hinduism. diff --git a/docs/src/manual/index.md b/docs/src/manual/index.md new file mode 100644 index 00000000..85a5ca54 --- /dev/null +++ b/docs/src/manual/index.md @@ -0,0 +1,7 @@ +# Manual + +This page documents functions and data structures within the code. + +## Index +```@index +``` diff --git a/docs/src/model.md b/docs/src/model.md index 8b3a172f..ebdcaff0 100644 --- a/docs/src/model.md +++ b/docs/src/model.md @@ -1,6 +1,4 @@ -# Model overview - -## Overview +# Overview AGNI models a planetary atmosphere by treating it as a single column (1D) and splitting it up into levels of finite thickness. These levels are defined in pressure-space, and are arranged logarithmically between the surface and the top of the atmosphere. Quantities such as pressure and temperature are calculated at level-centres and level-edges, while energy fluxes are calculated only at the edges, and thermodynamic properties (e.g. heat capacity) are calculated only at their centres. ## Radiative transfer @@ -33,11 +31,11 @@ Depending on the system you wish to model, it is necessary to tell AGNI what kin ## Obtaining a solution AGNI is designed for modelling planetary atmospheres with high surface pressures and temperatures. This means that the radiative timescale differs by several orders of magnitude across the column, which makes obtaining a solution difficult. The model contains a suite of methods for obtaining a solution. -### A) Time-stepping -AGNI implements a multistep Adams-Bashforth integrator to integrate the heating rates at each level over time. This is very robust to the initial conditions provided, but is not able to obtain an energy-conserving solution very quickly. Various optimisations can be used, such as allowing each level to evolve on its own timescale, which provides unphysical intermediate solutions but a physical final state. Time-stepping methods such as these are used in other radiative-convective models (with their own enhancements) such as HELIOS and Exo_k. +### A) Solving a non-linear system +To obtain a temperature structure solution that conserves energy more precisely than a time-stepping method, it is possible to construct the model as a system of non-linear equations $\vec{r}(\vec{x})$. This algorithm obtains the roots of the nonlinear system formed by the flux divergence $r_i$ at each level $i$, with cell-centre temperatures used as the independent variables $x_i$. Finite-difference methods are used to estimate the jacobian matrix in this case. Similar methods have been used in a handful of planetary radiative-convective models (e.g. ATMO), but is more commonly used by the stellar physics community. Currently implemented solvers: Newton-Raphson, Gauss-Newton, and Levenberg-Marquardt. Optionally, the code uses a golden-section linesearch algorithm to determine the optimal step length. -### B) Solving a non-linear system -To obtain a temperature structure solution that conserves energy more strictly than the time-stepping method, it is possible to construct the model as a system of non-linear equations $\vec{r}(\vec{x})$. This algorithm obtains the roots of the nonlinear system formed by the flux divergence at each level $r$, with cell-centre temperatures used as the independent variables $x$. Finite-difference methods are used to estimate the jacobian matrix in this case. This method has been used in a handful of planetary radiative-convective models (e.g. ATMO), but is more commonly used by the stellar physics community. Currently implemented solvers: Newton-Raphson, Gauss-Newton, and Levenberg-Marquardt. +### B) Time-stepping +AGNI also implements a multistep Adams-Bashforth integrator to integrate the heating rates at each level over time. This is very robust to the initial conditions provided, but is not able to obtain an energy-conserving solution very quickly. Each level to evolves on its own timescale, which provides unphysical intermediate solutions but a physical final state. Time-stepping methods such as these are used in other radiative-convective models (with their own enhancements) such as HELIOS and Exo_k. This method is not the primary solver within AGNI, so it in "maintainence mode" rather than active development. ## 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 the contribution function can also be calculated. diff --git a/docs/src/setup.md b/docs/src/setup.md new file mode 100644 index 00000000..583f7967 --- /dev/null +++ b/docs/src/setup.md @@ -0,0 +1,39 @@ +# Getting started +This page outlines requirements and installation steps for the code. + +## Requirements +* Julia (NB: install only from julialang.org - do not use your system package manager) +* gfortran (NB: do not use ifort or aocc) +* netcdf-fortran +* make +* OpenMP + +## Supported platforms +* MacOS (ARM and x86-64) +* GNU/Linux (x86-64) + +## Installation +- `$ export LD_LIBRARY_PATH=""` +- `$ cd socrates` +- `$ ./configure` +- `$ ./build_code` +- `$ source set_rad_env` +- `$ julia` +- `julia> ]` +- `(@v1.10) pkg> activate ../` +- `(AGNI) pkg> instantiate` +- Press backspace +- `julia> cd("julia/src")` +- `julia> include("generate_wrappers.jl")` +- `julia> exit()` +- `$ cd julia/lib` +- `$ make` +- `$ cd ../../..` +You will end up in the root directory of the repository. +You should run the tests next. + +## Testing +- `$ julia` +- `julia> ]` +- `(@v1.10) pkg> activate .` +- `(AGNI) pkg> test` diff --git a/docs/src/usage.md b/docs/src/usage.md index 9e6bc4fc..2099985c 100644 --- a/docs/src/usage.md +++ b/docs/src/usage.md @@ -1,8 +1,7 @@ -# Usage +# Running the model +First, follow the [Getting started](@ref) instructions . Only read-on once you have confirmed that the code is working. -First, follow the instructions in the README file. Only read-on once you have confirmed that the code is working. - -## Running the model +## Execution To run the model, simply execute `./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. ## Configuration