Update documentation

.gitignore

@@ -52,4 +52,7 @@ __pycache__
 bin/
 
 # documentation site
-site/
+site/
+
+# tutorial directory
+socrates_tutorial/

README.md

@@ -1,40 +1,15 @@
 
 # Socrates - Suite Of Community RAdiative Transfer codes based on Edwards and Slingo
 
-## Contributing Guidelines
+<a href="https://github.com/FormingWorlds/SOCRATES/actions/workflows/docs.yaml"><img alt="Documentation" src="https://github.com/FormingWorlds/SOCRATES/actions/workflows/docs.yaml/badge.svg"></a>
+<a href="https://github.com/FormingWorlds/SOCRATES/blob/main/LICENCE"><img alt="License: BSD-3-Clause" src="https://img.shields.io/badge/License-BSD--3--Clause-blue.svg"></a>
 
-Welcome!
+SOCRATES is a high-performance radiative transfer code for computing fluxes, heating rates, and radiances in planetary atmospheres. Its primary development and maintenance is lead by the UK Met Office. This fork of SOCRATES is applied as the radiative transfer core of the [PROTEUS framework](https://proteus-framework.org/PROTEUS/), called by the radiative-convective atmosphere model [AGNI](https://www.h-nicholls.space/AGNI/).
 
-The following links are here to help set clear expectations for everyone
-contributing to this project. By working together under a shared understanding,
-we can continuously improve the project while creating a friendly, inclusive
-space for all contributors.
+## Documentation
 
-### Contributors Licence Agreement
-
-Please see the
-[Momentum Contributors Licence Agreement](https://github.com/MetOffice/Momentum/blob/main/CLA.md)
-
-Agreement of the CLA can be shown by adding yourself to the CONTRIBUTORS file
-alongside this one, and is a requirement for contributing to this project.
-
-### Code of Conduct
-
-Please be aware of and follow the
-[Momentum Code of Coduct](https://github.com/MetOffice/Momentum/blob/main/docs/CODE_OF_CONDUCT.md)
-
-### Working Practices
-
-This project is managed as part of the Simulation Systems group of repositories.
-
-Please follow the Simulation Systems
-[Working Practices.](https://metoffice.github.io/simulation-systems/index.html)
-
-Questions are encouraged in the Simulation Systems
-[Discussions.](https://github.com/MetOffice/simulation-systems/discussions)
-
-Please be aware of and follow the Simulation Systems
-[AI Policy.](https://metoffice.github.io/simulation-systems/FurtherDetails/ai.html)
+Please visit the [documentation website](https://proteus-framework.org/SOCRATES/) for installation instructions, a tutorial, reference information and a model overview. Additionally, the latest documentation PDFs built by GitHub Actions are available from the
+[Build docs PDFs workflow artifacts](https://github.com/FormingWorlds/SOCRATES/actions/workflows/build-docs-pdf.yaml).
 
 ## What's included?
 
@@ -58,50 +33,54 @@ See the CONTENTS in each directory under examples/ for instructions.
 `idl/` and `python/` contain scripts to generate atmospheric profiles etc
 in netCDF format to be used as input for the radiation code (l_run_cdf).
 
-`docs/` contain the user guide and technical guide for the Socrates code.
+`docs/` contain documentation, as well as the user guide and technical guide for the Socrates code.
 
-The latest PDFs built by GitHub Actions are available from the
-[Build docs PDFs workflow artifacts](https://github.com/FormingWorlds/SOCRATES/actions/workflows/build-docs-pdf.yaml).
-
-## Compiling the source code within the Met Office
-
-For users within the Met Office simply run the command:
-
-`./build_code`
-
-to compile the entire suite. To setup your path to the executables
-and man pages you should then source the following file:
+## Standalone install
 
-`. ./set_rad_env`
+1. Clone SOCRATES from GitHub:
+   ```bash
+   git clone https://github.com/FormingWorlds/SOCRATES.git
+   ```
+2. Change into the new directory:
+   ```bash
+   cd SOCRATES
+   ```
+3. Configure the installation:
+   ```bash
+   ./configure
+   ```
+4. Compile the code:
+   ```bash
+   ./build_code
+   ```
 
-Individual programs can also be compiled using the build_code script
-(build_code will take as an argument the target to pass to the makefile).
+### Setting `RAD_DIR`
 
-For example, to build the routines that don't require netCDF:
+SOCRATES needs the location of its root directory, referred to as `RAD_DIR`, available as
+an environment variable. Run the following commands from inside the SOCRATES directory.
 
-`./build_code cdl`
+To set this temporarily, for the current terminal session only:
 
-To build just the two-stream/radiance code (netCDF version):
+```bash
+export RAD_DIR=$(pwd)
+```
 
-`./build_code l_run_cdf`
+To set this permanently:
 
-## Compiling the source code externally
+**Bash**:
+```bash
+echo "export RAD_DIR=$(pwd)" >> ~/.bashrc
+source ~/.bashrc
+```
 
-For external users it should only be necessary to edit the file
-make/Mk_cmd to allow compilation of the code on your system. FORTCOMP
-and LINK can be changed to your local Fortran compiler. To use the netCDF
-routines you must also change INCCDF_PATH and LIBCDF_PATH to point to
-your local netCDF installation.
+**Zsh**:
 
-The following commands can then be run to build the suite and setup
-your path to the executables and man pages:
+```bash
+echo "export RAD_DIR=$(pwd)" >> ~/.zshrc
+source ~/.zshrc
+```
 
-`./build_code`\
-`. ./set_rad_env`
-
-See previous section for building individual routines.
-
-## Compilation of scripts in sbin
+### Compilation of scripts in sbin
 
 There are a small number of utilities in sbin/ which are written
 in C and require compilation. A Makefile has been provided:
@@ -111,39 +90,39 @@ in C and require compilation. A Makefile has been provided:
 
 ## Running the code
 
-Once you have set your path to the man pages (see section 2/3) you can
-find up-to-date instructions for running the following routines:
+Set up your path to the executables and man pages:
+
+```
+source $RAD_DIR/set_rad_env
+```
 
-Two-stream and spherical harmonics radiance codes using netCDF or
-text CDL input files:
+Then find up-to-date instructions for running the following routines:
 
-`man Cl_run_cdf`\
-`man Cl_run_cdl`
+1. Two-stream and spherical harmonics radiance codes using netCDF or text CDL input files:
 
-A Mie scattering code for determining optical properties of aerosol
-and cloud particles:
+   `man Cl_run_cdf`\
+   `man Cl_run_cdl`
 
-`man Cscatter`
+2. A Mie scattering code for determining optical properties of aerosol and cloud particles:
 
-A correlated-k code for the calculation of gaseous absorption
-coefficients for the spectral files either directly from HITRAN
-.par or .xsc databases or line-by-line absorption coefficients in
-a netCDF input file:
+   `man Cscatter`
 
-`man Ccorr_k`
+3. A correlated-k code for the calculation of gaseous absorption coefficients for the spectral files either directly from HITRAN .par or .xsc databases or line-by-line absorption coefficients in a netCDF input file:
 
-Auxillary routines for format conversion, interpolation etc:
+   `man Ccorr_k`
 
-`man Ccdf2cdl`\
-`man Ccdl2cdf`\
-`man Cinterp`
+4. Auxillary routines for format conversion, interpolation etc:
+
+   `man Ccdf2cdl`\
+   `man Ccdl2cdf`\
+   `man Cinterp`
 
 These scripts are a command line interface to interactive routines in
 the bin/ directory. These routines may be run directly if desired (eg.
 l_run_cdf).
 
-It is very useful to study the examples/ directory for common usage
-of the code.
+It is useful to study the examples/ directory for common usage
+of the code, or follow the python-based [tutorial](https://proteus-framework.org/SOCRATES/Tutorials/first_run.html) on the documentation website.
 
 ## Tested compilers
 
@@ -176,7 +155,5 @@ This has to be done manually and will require editing a lot of files. The easies
 You should also make sure to avoid the 'lazy' way to extend FORTRAN arrays where remaining values are filled in bulk, because the `generate_wrappers.jl` script will not be able to parse the FORTRAN source code.
 
 ## References
-* [1]  https://code.metoffice.gov.uk/trac/socrates
-* [2]  https://doi.org/10.1002/qj.49712253107
-* [3]  https://doi.org/10.1051/0004-6361/201323169
-* [4]  https://doi.org/10.5194/gmd-16-5601-2023
+
+All references can be found in the [bibliography](https://proteus-framework.org/SOCRATES/Reference/publications.html) on the documentation website. 

docs/Explanations/interface.md

@@ -1,7 +1,7 @@
 # Interface to the calling model
 
-!!! note
-    This overview is adapted from the technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright. 
+!!! info "Based on technical guide"
+    This overview is based on the SOCRATES technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright. 
 
 ## Overview
 

docs/Explanations/overview.md

@@ -1,6 +1,6 @@
 # Physical model description
 
-!!! note
+!!! info "Based on technical guide"
     This overview is based on the SOCRATES technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright. 
 
 ## What is SOCRATES?
@@ -19,7 +19,7 @@ SOCRATES provides two complementary approaches to solving the radiative transfer
 
 #### [Two-stream radiation code](two_stream.md)
 
-The two-stream code is the primary solver for computing broad-band radiative fluxes and heating rates efficiently. It represents the angular dependence of the radiation field with just two streams — an upward and a downward diffuse flux — together with a direct solar beam in the shortwave. The key steps are:
+The two-stream code is the primary solver for computing broad-band radiative fluxes and heating rates efficiently. It represents the angular dependence of the radiation field with just two streams, an upward and a downward diffuse flux, together with a direct solar beam in the shortwave. The key steps are:
 
 1. The spectrum is divided into **bands**, each further subdivided into quasi-monochromatic regions using a k-distribution method.
 2. Within each region, layer **transmission and reflection coefficients** are derived from the single-scattering properties (optical depth $\tau$, single-scattering albedo $\omega$, asymmetry parameter $g$).

docs/Explanations/spectral_files.md

@@ -1,7 +1,7 @@
 # Spectral files
 
-!!! note
-    This overview is based on the technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright. 
+!!! info "Based on technical guide"
+    This overview is based on the SOCRATES technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright.
 
 ## Overview
 
@@ -24,16 +24,16 @@ The spectral file serves as the single source of truth for all spectrally depend
 
 Because parametrisations that require spectrally dependent data can only be selected if such data are present in the spectral file, **the choice of spectral file determines which physical parametrisations are available** at runtime. Spectral files should therefore be selected with care to match the intended configuration.
 
-!!! warning
+!!! warning "Modifying spectral files"
     Generating or modifying spectral files requires detailed knowledge of radiative transfer. Standard files are provided for common configurations; users should not modify these unless they have the necessary expertise.
 
 ---
 
 ## Spectral bands
 
-The spectral region is divided into bands within which all radiative quantities — except gaseous absorption coefficients — are treated as frequency-independent. The total flux is the sum of partial fluxes over bands (see [Two-stream radiation code](two_stream.md#spectral-integration)).
+The spectral region is divided into bands within which all radiative quantities (except gaseous absorption coefficients) are treated as frequency-independent. The total flux is the sum of partial fluxes over bands (see [Two-stream radiation code](two_stream.md#spectral-integration)).
 
-In some shortwave spectral files, certain bands share the same wavelength limits. These are **not true spectral bands** — they represent a computational splitting for efficiency, and only the sum of fluxes across such paired bands is physically meaningful. The excluded sub-ranges are specified in block 14 (see below).
+In some shortwave spectral files, certain bands share the same wavelength limits. These are **not true spectral bands**: they represent a computational splitting for efficiency, and only the sum of fluxes across such paired bands is physically meaningful. The excluded sub-ranges are specified in block 14 (see below).
 
 ---
 
@@ -44,19 +44,19 @@ The spectral file is organised into numbered **blocks**, each corresponding to a
 | Block | Contents | Notes |
 |---|---|---|
 | 0 | Number and identities of gaseous and aerosol species | Gases indexed by type number from `gas_list_pcf`; aerosols from `rad_pcf` |
-| 1 | Spectral band limits (wavelengths in metres) | Some bands may share limits — see split bands below |
+| 1 | Spectral band limits (wavelengths in metres) | Some bands may share limits, see split bands below |
 | 2 | Fraction of solar spectrum in each band | Shortwave only |
 | 3 | Rayleigh scattering coefficients | Shortwave only |
 | 4 | List of gaseous absorbers active in each band | First gas listed must be the primary absorber |
 | 5 | k-distribution fits to gaseous transmissions | Includes scaling functions or look-up tables |
 | 6 | Polynomial fit to the Planck function in each band | Longwave only |
-| 7 | *(Obsolete — not present in current files)* | — |
+| 7 | *(Obsolete, not present in current files)* | — |
 | 8 | List of continuum absorbers in each band | Primarily self- and foreign-broadened water vapour continua |
 | 9 | Continuum absorption coefficients | — |
 | 10 | Single-scattering parametrisations for cloud droplets | May contain multiple types; valid size range recorded |
 | 11 | Aerosol optical properties | Selection varies by file; hygroscopic aerosols include humidity dependence via look-up table |
 | 12 | Single-scattering parametrisations for ice crystals | May contain multiple types; valid size range recorded |
-| 13 | Heuristic Doppler broadening adjustments | Longwave only; obsolescent — will move to block 5 |
+| 13 | Heuristic Doppler broadening adjustments | Longwave only; obsolescent, will move to block 5 |
 | 14 | Band exclusions (split bands) | Defines sub-ranges excluded from a band's limits |
 | 15 | Monochromatic aerosol absorption/scattering coefficients | At specific wavelengths, for aerosol optical depth diagnostics |
 
@@ -65,13 +65,13 @@ The spectral file is organised into numbered **blocks**, each corresponding to a
 Gaseous absorption data are stored as **k-distribution** fits. For each active gas in each band, absorption coefficients are either:
 
 - **Scaled** from a reference value using a pressure- and temperature-dependent scaling function (two functional forms are supported; see [Two-stream radiation code](two_stream.md#gaseous-absorption)), or
-- **Interpolated** directly from a look-up table of coefficients at a grid of pressures and temperatures — now the preferred approach.
+- **Interpolated** directly from a look-up table of coefficients at a grid of pressures and temperatures, now the preferred approach.
 
 The first gas listed in block 4 for each band is the **primary absorber**; minor gases may be treated via the equivalent extinction approximation rather than full random overlap.
 
 ### Cloud and ice parametrisations (blocks 10 and 12)
 
-Blocks 10 and 12 may contain data for **multiple types** of droplet or ice crystal parametrisation within a single file. The term *type* is deliberately flexible — different types may represent:
+Blocks 10 and 12 may contain data for **multiple types** of droplet or ice crystal parametrisation within a single file. The term *type* is deliberately flexible; different types may represent:
 
 - Different assumed size distributions
 - Different spectral averaging methods (thin or thick averaging)
@@ -105,7 +105,7 @@ Two utility programs handle format conversion between namelist and text formats:
 
 ## Generating and modifying spectral files
 
-Spectral files are generated using the **pre-processing suite** of the offline Edwards–Slingo radiation code. Generation requires expertise in radiative transfer — most users will use standard provided files and should not modify them.
+Spectral files are generated using the **pre-processing suite** of the offline Edwards–Slingo radiation code. Generation requires expertise in radiative transfer.
 
 When a new requirement arises (e.g. adding a new absorbing gas, updating continuum data, or incorporating a new aerosol type), users should contact the radiation group rather than modifying files independently. Aerosol optical property data in particular are generated in consultation with aerosol modelling specialists.
 

docs/Explanations/spherical_harmonic.md

@@ -1,7 +1,7 @@
 # Spherical harmonic radiance code
 
-!!! note
-    This overview is based on the technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide).  It is under Crown Copyright. 
+!!! info "Based on technical guide"
+    This overview is based on the SOCRATES technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright.
 
 ## Overview
 
@@ -119,7 +119,7 @@ $$I_{i,lm}(\tau_i) = I_{i+1,lm}(0), \quad 1 \leq i \leq N, \quad \forall\, l, m$
 
 ### Upper boundary
 
-At the top of the atmosphere, the downward radiance is specified as $I(n) = I^{(0)}(n)$ for $n \in \Omega^-$. Since the full boundary condition cannot be imposed in a truncated system, **Marshak's conditions** [^cite-Marshak] are used — the inner product of the residual with odd-parity harmonics is set to zero:
+At the top of the atmosphere, the downward radiance is specified as $I(n) = I^{(0)}(n)$ for $n \in \Omega^-$. Since the full boundary condition cannot be imposed in a truncated system, **Marshak's conditions** [^cite-Marshak] are used; the inner product of the residual with odd-parity harmonics is set to zero:
 
 $$\sum_l \kappa_{ll'm} (I_{lm} - I^{(0)}_{lm}) = 0$$
 
@@ -233,7 +233,7 @@ This introduces errors of $O(\sqrt{\varepsilon})$ only in a neighbourhood of the
 
 ## Fast solution of the linear equations
 
-A more efficient algorithm for the core linear system — not yet fully implemented — reduces the dominant operation count from $O(18N^3 L)$ (banded solver with partial pivoting) to $O(6N^3 L)$.
+A more efficient algorithm for the core linear system, not yet fully implemented, reduces the dominant operation count from $O(18N^3 L)$ (banded solver with partial pivoting) to $O(6N^3 L)$.
 
 ### Block structure
 

docs/Explanations/two_stream.md

@@ -1,7 +1,7 @@
 # Two-stream radiation code
 
-!!! note
-    This overview is adapted from the technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen  (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide).  It is under Crown Copyright. 
+!!! info "Based on technical guide"
+    This overview is based on the SOCRATES technical guide by James Manners, John M. Edwards, Peter Hill & Jean-Claude Thelen (Met Office, 2017), which can be found [here](../Reference/documentation_pdfs.md#technical-guide). It is under Crown Copyright.
 
 ## Overview