Doc updates. Vscode config. Readme updates

nichollsh · May 28, 2024 · 5211cf3 · 5211cf3
1 parent 314b454
commit 5211cf3
Show file tree

Hide file tree

Showing 9 changed files with 68 additions and 60 deletions.
diff --git 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
@@ -0,0 +1,4 @@
+{
+    "julia.environmentPath": "${workspaceFolder}/",
+    "editor.tabSize": 4
+}
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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