+
-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.
diff --git a/docs/Explanations/interface.md b/docs/Explanations/interface.md
index a9022b51..c26fa25c 100644
--- a/docs/Explanations/interface.md
+++ b/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
diff --git a/docs/Explanations/overview.md b/docs/Explanations/overview.md
index be215d19..7ee326b2 100644
--- a/docs/Explanations/overview.md
+++ b/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$).
diff --git a/docs/Explanations/spectral_files.md b/docs/Explanations/spectral_files.md
index 4539e541..6da991f0 100644
--- a/docs/Explanations/spectral_files.md
+++ b/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.
diff --git a/docs/Explanations/spherical_harmonic.md b/docs/Explanations/spherical_harmonic.md
index d4ea78f0..1eefe8b9 100644
--- a/docs/Explanations/spherical_harmonic.md
+++ b/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
diff --git a/docs/Explanations/two_stream.md b/docs/Explanations/two_stream.md
index 8656a7d0..65c3357f 100644
--- a/docs/Explanations/two_stream.md
+++ b/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
diff --git a/docs/How-to/installation.md b/docs/How-to/installation.md
index 81c90edf..65cd679d 100644
--- a/docs/How-to/installation.md
+++ b/docs/How-to/installation.md
@@ -1,43 +1,122 @@
# Installation
+!!! tip "Installation within the PROTEUS framework"
+ If used within PROTEUS, SOCRATES is installed alongside other modules following the
+ [PROTEUS installation guide](https://proteus-framework.org/PROTEUS/How-to/installation.html).
+ It can also be installed within the atmosphere models
+ [AGNI](https://www.h-nicholls.space/AGNI/dev/howto/getting_started/) or
+ [JANUS](https://proteus-framework.org/JANUS), as outlined in [Installing via other frameworks](#installing-via-other-frameworks). Use the instructions below if you
+ would like a **standalone version of SOCRATES on your system**.
+
## Supported platforms
-* Linux x86_64 / AMD64: Ubuntu, Fedora, RedHat, CentOS, Arch, Debian.
-* MacOS ARM64 / Apple Silicon
+- **Linux (x86_64 / AMD64):** Ubuntu, Fedora, RedHat, CentOS, Arch, Debian
+- **macOS (ARM64 / Apple Silicon)**
+
+Older Intel-based Mac systems and Linux running on ARM64 architectures are not currently
+supported.
-Not supported by old Intel-based Apple systems, or by Linux running on ARM64 architectures.
+!!! info "Software requirements"
+ The following tools must be available on your system before installing SOCRATES:
-## Software requirements
-* gfortran
-* netcdf
-* netcdf-fortran
-* make
-* wget
-* curl
-* unzip
-* cmake
+ - gfortran
+ - netCDF
+ - netCDF-Fortran
+ - make
+ - cmake
+ - wget
+ - curl
+ - unzip
## Standalone install
-1. Clone SOCRATES from GitHub: `git clone https://github.com/FormingWorlds/SOCRATES.git`
-2. Change to the new folder: `cd SOCRATES`
-3. Configure your installation: `./configure`
-4. Compile the software: `./build_code`
+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
+ ```
+
+### Setting `RAD_DIR`
+
+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.
+
+To set this temporarily, for the current terminal session only:
+
+```bash
+export RAD_DIR=$(pwd)
+```
+
+To set this permanently:
+
+=== "Bash"
+ ```bash
+ echo "export RAD_DIR=$(pwd)" >> ~/.bashrc
+ source ~/.bashrc
+ ```
+
+=== "Zsh"
+ ```zsh
+ echo "export RAD_DIR=$(pwd)" >> ~/.zshrc
+ source ~/.zshrc
+ ```
+
+### Setting `FWL_DATA` (optional)
+
+`FWL_DATA` is the directory where PROTEUS shared data files, including spectral files, are
+stored. Choose a location with sufficient disk space.
+
+To set this temporarily:
+
+```bash
+export FWL_DATA=/path/to/fwl_data
+```
+
+To set this permanently:
+
+=== "Bash"
+ ```bash
+ echo 'export FWL_DATA=/path/to/fwl_data' >> ~/.bashrc
+ source ~/.bashrc
+ ```
-You must now record the location of SOCRATES' root directory (referred to as `RAD_DIR`) in your terminal/shell's environment.
+=== "Zsh"
+ ```zsh
+ echo 'export FWL_DATA=/path/to/fwl_data' >> ~/.zshrc
+ source ~/.zshrc
+ ```
-To do this temporarily, for the current terminal session only, run: `export RAD_DIR=$(pwd)`
+Spectral files will be downloaded into `$FWL_DATA/spectral_files/`.
-To set this permanently with a Bash shell, run: `echo $(pwd) >> ~/.bashrc`
+### Set up a Python environment (optional)
-With a Zsh shell, such as on MacOS, run: `echo $(pwd) >> ~/.zshrc`
+An easy way to work with SOCRATES is by accessing it via Python, which requires a Python
+installation with additional dependencies. If you have Conda installed, create a clean
+environment and install the required dependencies:
-## Other material
+```bash
+conda create -n socrates python=3.12 -y
+conda activate socrates
+pip install -r python/requirements.txt
+```
-This distribution of SOCRATES is most commonly used and installed within the [PROTEUS framework](https://proteus-framework.org/PROTEUS/), or within the atmosphere models [AGNI](https://www.h-nicholls.space/AGNI/) or [JANUS](https://proteus-framework.org/JANUS). You can find some relevant installation instructions there:
+## Installing via other frameworks
-- [Installation within PROTEUS framework](https://proteus-framework.org/PROTEUS/How-to/installation.html#7-install-socrates-radiative-transfer)
-- [Installation within AGNI](https://www.h-nicholls.space/AGNI/)
-- [Installation within JANUS](https://proteus-framework.org/JANUS/How-to/installation.html)
+This SOCRATES fork is most commonly used as a component of a larger framework rather than
+installed standalone. Installation instructions for these are available in their respective
+documentation:
-AGNI provides a script called `get_socrates.sh` for automatically performing this installation process.
+- [PROTEUS framework](https://proteus-framework.org/PROTEUS/): see [installing SOCRATES within PROTEUS](https://proteus-framework.org/PROTEUS/How-to/manual_installation.html#5-install-socrates-radiative-transfer)
+- [AGNI](https://www.h-nicholls.space/AGNI/) atmosphere model, which provides a `get_socrates.sh` script to automate this installation process
+- [JANUS](https://proteus-framework.org/JANUS) atmosphere model: see [installing SOCRATES within JANUS](https://proteus-framework.org/JANUS/How-to/installation.html)
\ No newline at end of file
diff --git a/docs/Reference/proteus_spectral_file_reference.md b/docs/Reference/proteus_spectral_file_reference.md
index 71862cca..84627577 100644
--- a/docs/Reference/proteus_spectral_file_reference.md
+++ b/docs/Reference/proteus_spectral_file_reference.md
@@ -9,7 +9,7 @@
Each spectral file is identified by a codename and a band count; several codenames are available at multiple resolutions. All files are in the standard SOCRATES spectral file format.
-Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN database](https://hitran.org/); **EXOMOL** — [ExoMol database](https://www.exomol.com/); **DACE** — [DACE opacity database](https://dace.unige.ch/opacityDatabase/).
+Spectroscopic data sources are abbreviated as follows: [**HITRAN**](https://hitran.org/), [**ExoMol**](https://www.exomol.com/), [**ExoAtom**](https://exomol.com/exoatom/), [**DACE**](https://dace.unige.ch/opacityDatabase/).
---
@@ -17,20 +17,20 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Codename | Bands | Absorbers | Source | Notes |
|---|---|---|---|---|
-| Legacy | 318 | CO₂, CH₄, O₂, N₂, H₂, He | HITRAN | Legacy file used in Lichtenberg et al. (2021) |
-| Oak | 318 | H₂O | HITRAN | Water-only file from HITRAN; intended for benchmarking |
-| Idwal | 318 | H₂O | HITRAN | Made redundant by Oak |
-| Balmora | 318 | H₂O | HITRAN | Made redundant by Oak |
-| Triangle | 318 | H₂O, H₂, CO₂ | HITRAN | Test file |
-| Mallard | 318 | H₂O, H₂, CO₂, CO, CH₄, O₂, N₂, He | HITRAN | HITRAN file with useful opacities |
-| Reach | 318 | H₂O, CO₂, O₃, N₂O, CO, CH₄, O₂, NO, SO₂, NO₂, NH₃, HNO₃, N₂, H₂, He, OCS | HITRAN | Same as Mallard but with more opacities |
-| Vivec | 318 | H₂O, CO₂, O₃, N₂O, CO, CH₄, O₂, NO, SO₂, NO₂, NH₃, HNO₃, N₂, H₂, He, OCS | HITRAN | Same as Reach, compiled on macOS |
-| Alduin | 432 | H₂O | EXOMOL | |
-| Kynesgrove | 318 | O₂ | DACE | Validation of DACE cross-section data against SOCRATES line-by-line calculations |
-| Frostflow | 16 / 48 / 256 / 4096 | H₂O | DACE | Multi-resolution; 4096 intended for benchmarking, 16 for debugging |
-| Dayspring | 16 / 48 / 256 / 4096 | H₂O, H₂, CO₂, CO, CH₄, N₂ | DACE | Multi-resolution; 4096 intended for benchmarking, 16 for debugging |
-| Honeyside | 16 / 48 / 256 / 4096 | H₂O, H₂, CO₂, CO, CH₄, N₂, NH₃, SO₂, N₂O, O₃, HCN, H₂S | DACE | Multi-resolution; 4096 intended for benchmarking, 16 for debugging |
-| Rocks | 64 / 128 / 256 | H₂, H₂O, O₂, SiO, SiO₂ | DACE | Rock vapours and key volatiles; 128-band file for JWST comparison |
+| Legacy | 318 | CO$_2$, CH$_4$, O$_2$, N$_2$, H$_2$, He | HITRAN | Legacy file used in Lichtenberg et al. (2021) |
+| Oak | 318 | H$_2$O | HITRAN | Water-only file from HITRAN; intended for benchmarking |
+| Idwal | 318 | H$_2$O | HITRAN | Made redundant by Oak |
+| Balmora | 318 | H$_2$O | HITRAN | Made redundant by Oak |
+| Triangle | 318 | H$_2$O, H$_2$, CO$_2$ | HITRAN | Test file |
+| Mallard | 318 | H$_2$O, H$_2$, CO$_2$, CO, CH$_4$, O$_2$, N$_2$, He | HITRAN | HITRAN file with useful opacities |
+| Reach | 318 | H$_2$O, CO$_2$, O$_3$, N$_2$O, CO, CH$_4$, O$_2$, NO, SO$_2$, NO$_2$, NH$_3$, HNO$_3$, N$_2$, H$_2$, He, OCS | HITRAN | Same as Mallard but with more opacities |
+| Vivec | 318 | H$_2$O, CO$_2$, O$_3$, N$_2$O, CO, CH$_4$, O$_2$, NO, SO$_2$, NO$_2$, NH$_3$, HNO$_3$, N$_2$, H$_2$, He, OCS | HITRAN | Same as Reach, compiled on macOS |
+| Alduin | 432 | H$_2$O | EXOMOL | |
+| Kynesgrove | 318 | O$_2$ | DACE | Validation of DACE cross-section data against SOCRATES line-by-line calculations |
+| Frostflow | 16 / 48 / 256 / 4096 | H$_2$O | DACE | Multi-resolution; 4096 intended for benchmarking, 16 for debugging |
+| Dayspring | 16 / 48 / 256 / 4096 | H$_2$O, H$_2$, CO$_2$, CO, CH$_4$, N$_2$ | DACE | Multi-resolution; 4096 intended for benchmarking, 16 for debugging |
+| Honeyside | 16 / 48 / 256 / 4096 | H$_2$O, H$_2$, CO$_2$, CO, CH$_4$, N$_2$, NH$_3$, SO$_2$, N$_2$O, O$_3$, HCN, H$_2$S | DACE | Multi-resolution; 4096 intended for benchmarking, 16 for debugging |
+| Rocks | 64 / 128 / 256 | H$_2$, H$_2$O, O$_2$, SiO, SiO$_2$ | DACE | Rock vapours and key volatiles; 128-band file for JWST comparison |
---
@@ -44,16 +44,16 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| 48 | ^ | ^ | ^ | ^ | ^ | ^ | Medium resolution |
| 16 | ^ | ^ | ^ | ^ | ^ | ^ | Low resolution; intended for debugging |
- **Absorbers:** H₂O, H₂, CO₂, CO, CH₄, N₂, NH₃, SO₂, N₂O, O₃, HCN, H₂S
- **Continua:** H₂O-H₂O, H₂-CH₄, H₂-H₂, H₂-N₂, N₂-N₂, N₂-H₂O, CO₂-CO₂, CO₂-H₂, CO₂-CH₄
+ **Absorbers:** H$_2$O, H$_2$, CO$_2$, CO, CH$_4$, N$_2$, NH$_3$, SO$_2$, N$_2$O, O$_3$, HCN, H$_2$S
+ **Continua:** H$_2$O-H$_2$O, H$_2$-CH$_4$, H$_2$-H$_2$, H$_2$-N$_2$, N$_2$-N$_2$, N$_2$-H$_2$O, CO$_2$-CO$_2$, CO$_2$-H$_2$, CO$_2$-CH$_4$
**Source:** DACE
??? info "Rocks"
| Bands | Absorbers | Continua | NaN-clean | SOCRATES | Date | Platform | Creator | Notes |
|---|---|---|---|---|---|---|---|---|
- | 256 | O₂, SiO, SiO₂ | O₂-O₂ | Yes | 2407.2 | 2025-05-15 | Linux Intel | Alex McGinty | — |
- | 128 | H₂, H₂O, O₂, SiO, SiO₂ | H₂O-H₂O, H₂-H₂, O₂-O₂ | Yes | 2407.02 | 2025-05-15 | Linux Intel | Alex McGinty | Rock vapours and key volatiles. High resolution file for comparison with JWST observations of rock-vapour atmospheres |
- | 64 | H₂, H₂O, O₂, SiO, SiO₂ | H₂O-H₂O, H₂-H₂, O₂-O₂ | Yes | 2407.02 | 2025-05-15 | Linux Intel | Alex McGinty | Rock vapours and key volatiles (low resolution) |
+ | 256 | O$_2$, SiO, SiO$_2$ | O$_2$-O$_2$ | Yes | 2407.2 | 2025-05-15 | Linux Intel | Alex McGinty | — |
+ | 128 | H$_2$, H$_2$O, O$_2$, SiO, SiO$_2$ | H$_2$O-H$_2$O, H$_2$-H$_2$, O$_2$-O$_2$ | Yes | 2407.02 | 2025-05-15 | Linux Intel | Alex McGinty | Rock vapours and key volatiles. High resolution file for comparison with JWST observations of rock-vapour atmospheres |
+ | 64 | H$_2$, H$_2$O, O$_2$, SiO, SiO$_2$ | H$_2$O-H$_2$O, H$_2$-H$_2$, O$_2$-O$_2$ | Yes | 2407.02 | 2025-05-15 | Linux Intel | Alex McGinty | Rock vapours and key volatiles (low resolution) |
**Source:** DACE
@@ -65,8 +65,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| 48 | ^ | ^ | ^ | ^ | ^ | ^ | Medium resolution |
| 16 | ^ | ^ | ^ | ^ | ^ | ^ | Low resolution; intended for debugging |
- **Absorbers:** H₂O, H₂, CO₂, CO, CH₄, N₂
- **Continua:** H₂O-H₂O, H₂-CH₄, H₂-H₂, H₂-N₂, N₂-N₂, N₂-H₂O, CO₂-CO₂, CO₂-H₂, CO₂-CH₄
+ **Absorbers:** H$_2$O, H$_2$, CO$_2$, CO, CH$_4$, N$_2$
+ **Continua:** H$_2$O-H$_2$O, H$_2$-CH$_4$, H$_2$-H$_2$, H$_2$-N$_2$, N$_2$-N$_2$, N$_2$-H$_2$O, CO$_2$-CO$_2$, CO$_2$-H$_2$, CO$_2$-CH$_4$
**Source:** DACE
??? info "Frostflow"
@@ -77,16 +77,16 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| 48 | ^ | ^ | ^ | ^ | ^ | ^ | Medium resolution |
| 16 | ^ | ^ | ^ | ^ | ^ | ^ | Low resolution; intended for debugging |
- **Absorbers:** H₂O
- **Continua:** H₂O
+ **Absorbers:** H$_2$O
+ **Continua:** H$_2$O
**Source:** DACE
??? info "Kynesgrove"
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | O₂ |
- | Continua | O₂-O₂ |
+ | Absorbers | O$_2$ |
+ | Continua | O$_2$-O$_2$ |
| Tolerance | 5.00E-04 |
| Source | DACE |
| NaN-clean | Yes |
@@ -100,8 +100,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O, CO₂, O₃, N₂O, CO, CH₄, O₂, NO, SO₂, NO₂, NH₃, HNO₃, N₂, H₂, He, OCS |
- | Continua | H₂O, CO₂, CH₄, O₂, N₂, H₂, He |
+ | Absorbers | H$_2$O, CO$_2$, O$_3$, N$_2$O, CO, CH$_4$, O$_2$, NO, SO$_2$, NO$_2$, NH$_3$, HNO$_3$, N$_2$, H$_2$, He, OCS |
+ | Continua | H$_2$O, CO$_2$, CH$_4$, O$_2$, N$_2$, H$_2$, He |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | Yes |
@@ -115,8 +115,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O, H₂, CO₂, CO, CH₄, O₂, N₂, He |
- | Continua | H₂O, CO₂, CH₄, O₂, N₂, H₂, He |
+ | Absorbers | H$_2$O, H$_2$, CO$_2$, CO, CH$_4$, O$_2$, N$_2$, He |
+ | Continua | H$_2$O, CO$_2$, CH$_4$, O$_2$, N$_2$, H$_2$, He |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | Yes |
@@ -130,8 +130,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 432 |
- | Absorbers | H₂O |
- | Continua | H₂O |
+ | Absorbers | H$_2$O |
+ | Continua | H$_2$O |
| Tolerance | 1.00E-02 |
| Source | EXOMOL |
| NaN-clean | Yes |
@@ -145,8 +145,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O |
- | Continua | H₂O |
+ | Absorbers | H$_2$O |
+ | Continua | H$_2$O |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | Yes |
@@ -160,7 +160,7 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | CO₂, CH₄, O₂, N₂, H₂, He |
+ | Absorbers | CO$_2$, CH$_4$, O$_2$, N$_2$, H$_2$, He |
| Continua | — |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
@@ -175,8 +175,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O, CO₂, O₃, N₂O, CO, CH₄, O₂, NO, SO₂, NO₂, NH₃, HNO₃, N₂, H₂, He, OCS |
- | Continua | H₂O, CO₂, CH₄, O₂, N₂, H₂, He |
+ | Absorbers | H$_2$O, CO$_2$, O$_3$, N$_2$O, CO, CH$_4$, O$_2$, NO, SO$_2$, NO$_2$, NH$_3$, HNO$_3$, N$_2$, H$_2$, He, OCS |
+ | Continua | H$_2$O, CO$_2$, CH$_4$, O$_2$, N$_2$, H$_2$, He |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | No |
@@ -190,8 +190,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O, H₂, CO₂ |
- | Continua | H₂O, H₂, CO₂ |
+ | Absorbers | H$_2$O, H$_2$, CO$_2$ |
+ | Continua | H$_2$O, H$_2$, CO$_2$ |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | Yes |
@@ -205,8 +205,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O |
- | Continua | H₂O |
+ | Absorbers | H$_2$O |
+ | Continua | H$_2$O |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | No |
@@ -220,8 +220,8 @@ Spectroscopic data sources are abbreviated as follows: **HITRAN** – [HITRAN da
| Field | Value |
|---|---|
| Bands | 318 |
- | Absorbers | H₂O |
- | Continua | H₂O |
+ | Absorbers | H$_2$O |
+ | Continua | H$_2$O |
| Tolerance | 1.00E-02 |
| Source | HITRAN |
| NaN-clean | No |
@@ -240,5 +240,5 @@ The appropriate spectral file depends on the atmospheric composition being model
- For **benchmarking or comparison with observations**, use a high- or very-high-resolution configuration (256–4096 bands).
- For **debugging**, use a low resolution spectral file with 16 bands.
- For **water-dominated atmospheres**, Frostflow or Oak are appropriate depending on the required resolution and data source.
-- For **mixed volatile atmospheres** (H₂O, CO₂, CH₄, H₂, N₂ and more), Honeyside is the most complete option.
-- For **rock-vapour atmospheres** (relevant to magma ocean planets), use the Rocks files which include SiO and SiO₂ opacity.
\ No newline at end of file
+- For **mixed volatile atmospheres** (H$_2$O, CO$_2$, CH$_4$, H$_2$, N$_2$ and more), Honeyside is the most complete option.
+- For **rock-vapour atmospheres** (relevant to magma ocean planets), use the Rocks files which include SiO and SiO$_2$ opacity.
\ No newline at end of file
diff --git a/docs/Reference/publications.md b/docs/Reference/publications.md
new file mode 100644
index 00000000..628400b9
--- /dev/null
+++ b/docs/Reference/publications.md
@@ -0,0 +1,28 @@
+# Publications
+
+SOCRATES was developed by the UK Meteorological Office as a radiative transfer code for Earth and planetary science, based on the following paper by Edwards and Slingo (1996):
+
+- Edwards, J. M., & Slingo, A. (1996). Studies with a flexible new radiation code. I: Choosing a configuration for a large‐scale model. *Quarterly Journal of the Royal Meteorological Society, 122*(531), 689-719. [https://doi.org/10.1002/qj.49712253107](https://doi.org/10.1002/qj.49712253107)
+
+The companion paper describing the fast two-stream flux/cooling-rate algorithms:
+
+- Edwards, J. M. (1996). Efficient calculation of infrared fluxes and cooling rates using the two-stream equations. *Journal of the Atmospheric Sciences, 53*(14), 1921-1932. [https://doi.org/10.1175/1520-0469(1996)053%3C1921:ECOIFA%3E2.0.CO;2](https://doi.org/10.1175/1520-0469(1996)053%3C1921:ECOIFA%3E2.0.CO;2)
+
+A major update was published in 2024:
+
+- Manners, J. (2024, January). A fast and flexible scheme for photolysis and radiative heating of the whole atmosphere. In _AIP Conference Proceedings_ (Vol. 2988, No. 1, p. 030002). AIP Publishing LLC. [https://doi.org/10.1063/5.0185476](https://doi.org/10.1063/5.0185476)
+
+## Adaptation and application
+
+SOCRATES has since been adapted and validated for hot-Jupiter and brown dwarf atmospheres:
+
+- Amundsen, D. S., Baraffe, I., Tremblin, P., Manners, J., Hayek, W., Mayne, N. J., & Acreman, D. M. (2014). Accuracy tests of radiation schemes used in hot Jupiter global circulation models. *Astronomy & Astrophysics, 564*, A59. [https://doi.org/10.1051/0004-6361/201323169](https://doi.org/10.1051/0004-6361/201323169)
+- Amundsen, D. S., Tremblin, P., Manners, J., Baraffe, I., & Mayne, N. J. (2017). Treatment of overlapping gaseous absorption with the correlated-k method in hot Jupiter and brown dwarf atmosphere models. *Astronomy & Astrophysics, 598*, A97. [https://doi.org/10.1051/0004-6361/201629322](https://doi.org/10.1051/0004-6361/201629322)
+
+And for its use as the radiation scheme within terrestrial-planet GCMs (e.g. LFRic-atmosphere, used by SOCRATES-based tools like AGNI):
+
+- Sergeev, D. E., Mayne, N. J., Bendall, T., Boutle, I. A., Brown, A., Kavčič, I., Kent, J., Kohary, K., Manners, J., Melvin, T., Olivier, E., Ragta, L. K., Shipway, B., Wakelin, J., Wood, N., & Zerroukat, M. (2023). Simulations of idealised 3D atmospheric flows on terrestrial planets using LFRic-atmosphere. *Geoscientific Model Development, 16*(19), 5601-5626. [https://doi.org/10.5194/gmd-16-5601-2023](https://doi.org/10.5194/gmd-16-5601-2023)
+
+## Use in PROTEUS framework
+
+Finally, SOCRATES is used in all publications that make use of the PROTEUS framework, which can be found [here](https://proteus-framework.org/publications).
\ No newline at end of file
diff --git a/docs/Reference/spectral_file_reference.md b/docs/Reference/spectral_file_reference.md
index d627168c..dc0aef2b 100644
--- a/docs/Reference/spectral_file_reference.md
+++ b/docs/Reference/spectral_file_reference.md
@@ -39,11 +39,11 @@ Sections are identical to `sp_sw_ga3_0` except for changes to the spectral bands
The six bands are identical to `sp_sw_ga3_0` except that the combined bands 2 and 3 are now properly split into two true bands at 505 nm.
-**Solar spectrum:** "Lean 12" — a mean over 2000–2011 from the SPARC/SOLARIS group recommendation [^cite-Lean00], with associated updates to Rayleigh scattering coefficients.
+**Solar spectrum:** "Lean 12", a mean over 2000–2011 from the SPARC/SOLARIS group recommendation [^cite-Lean00], with associated updates to Rayleigh scattering coefficients.
**Gaseous absorption:** Newly derived for all gases using HITRAN 2012 [^cite-HITRAN] and the CAVIAR water vapour continuum. Absorption coefficients are scaled via a look-up table of 59 pressures × 5 temperatures, based on a mid-latitude summer profile. Total of **41 major gas k-terms**.
-Gases included: H₂O, O₃, CO₂, O₂, N₂O, CH₄, SO₂ (experimental), OCS (experimental).
+Gases included: H$_2$O, O$_3$, CO$_2$, O$_2$, N$_2$O, CH$_4$, SO$_2$ (experimental), OCS (experimental).
Ozone cross-sections from Serdyuchenko et al. [^cite-Serd14] and Gorshelev et al. [^cite-Gors14] for UV/visible; Brion–Daumont–Malicet for the far UV. In band 1, one k-term per 20 nm sub-interval (200–320 nm); in band 2, sub-intervals at 320–400 nm and 400–505 nm to allow the incoming solar flux to be supplied on finer wavelength bands for solar spectral variability experiments.
@@ -69,11 +69,11 @@ Sections are identical to `sp_lw_ga3_0` except for changes to gaseous absorption
Bands 3 and 5 are split bands (see [Spectral files: split bands](../Explanations/spectral_files.md#split-bands-block-14)).
-**Gaseous absorption:** Newly derived for all gases (except CO₂ in band 4) using HITRAN 2012 and CAVIAR. Total of **81 major gas k-terms**.
+**Gaseous absorption:** Newly derived for all gases (except CO$_2$ in band 4) using HITRAN 2012 and CAVIAR. Total of **81 major gas k-terms**.
-Greenhouse gases included: H₂O, CO₂, O₃, N₂O, CH₄, CFC-11, CFC-12, CFC-113, HCFC-22, HFC-134a, SO₂ (experimental), OCS (experimental).
+Greenhouse gases included: H$_2$O, CO$_2$, O$_3$, N$_2$O, CH$_4$, CFC-11, CFC-12, CFC-113, HCFC-22, HFC-134a, SO$_2$ (experimental), OCS (experimental).
-The improved representation of CO₂ in the window region (more minor gas k-terms in bands 5 and 6) provides a better forcing response to increases in CO₂ (tested up to ×32 present-day). The new method of hybrid scattering may be used with this spectral file: 27 of the major gas k-terms (where their nominal optical depth is less than 10 in a mid-latitude summer atmosphere) use the full scattering solver; the remaining 54 (optical depth > 10) use a cheaper non-scattering solver.
+The improved representation of CO$_2$ in the window region (more minor gas k-terms in bands 5 and 6) provides a better forcing response to increases in CO$_2$ (tested up to ×32 present-day). The new method of hybrid scattering may be used with this spectral file: 27 of the major gas k-terms (where their nominal optical depth is less than 10 in a mid-latitude summer atmosphere) use the full scattering solver; the remaining 54 (optical depth > 10) use a cheaper non-scattering solver.
**Thermal emission:** Planck function fitted by a quartic polynomial over 160–330 K. This increases the lower bound of the fit from 150 K used with `sp_lw_ga3_0` and slightly improves the fit over the important temperature range for the Earth's atmosphere.
@@ -85,13 +85,13 @@ The improved representation of CO₂ in the window region (more minor gas k-term
Sections are identical to `spec3a_sw_hadgem1_5o_rlfx` except for changes to the solar spectrum (including Rayleigh coefficients), gaseous absorption, aerosols, and ice crystals.
-**Spectral bands:** Identical to `sp_sw_ga7` except bands 2 and 3 are not true spectral bands — they share the combined range 320–690 nm and only the sum of fluxes in these two bands is physically meaningful.
+**Spectral bands:** Identical to `sp_sw_ga7` except bands 2 and 3 are not true spectral bands, they share the combined range 320–690 nm and only the sum of fluxes in these two bands is physically meaningful.
-**Solar spectrum:** Lean (2000, updated) [^cite-Lean00] — based on satellite observations at wavelengths shorter than 735 nm with the Kurucz spectrum [^cite-Kurucz95] at longer wavelengths, meaned over the last two solar cycles (1983–2004).
+**Solar spectrum:** Lean (2000, updated) [^cite-Lean00], based on satellite observations at wavelengths shorter than 735 nm with the Kurucz spectrum [^cite-Kurucz95] at longer wavelengths, meaned over the last two solar cycles (1983–2004).
-**Gaseous absorption:** Revised O₃ k-terms in bands 1–3 for improved ozone heating rate calculations and to better incorporate solar variability [^cite-Zhong08]. The UV band is divided into six narrow sub-bands, each with a single ozone k-term.
+**Gaseous absorption:** Revised O$_3$ k-terms in bands 1–3 for improved ozone heating rate calculations and to better incorporate solar variability [^cite-Zhong08]. The UV band is divided into six narrow sub-bands, each with a single ozone k-term.
-Gases included: H₂O, O₃, CO₂, O₂.
+Gases included: H$_2$O, O$_3$, CO$_2$, O$_2$.
**Aerosols:** Addition of four aerosol species: fresh and aged OCFF (organic carbon fossil fuel), delta aerosol, and nitrate aerosol. The optical properties of the six divisions of mineral dust have been revised using refractive indices from Balkanski et al. [^cite-Balk07], making mineral dust less absorbing in the SW and more absorbing in the LW.
@@ -105,9 +105,9 @@ Used for climate configurations where a more accurate treatment of the stratosph
**Spectral bands:** Identical to `sp_lw_ga7` (nine bands; bands 3 and 5 split).
-**Gaseous absorption:** New k-terms for CO₂ (band 4) and O₃ (band 6) [^cite-ZhongH00], increasing the total number of k-terms by 14 relative to `spec3a_lw_hadgem1_5C` to allow a more accurate treatment of stratospheric absorption.
+**Gaseous absorption:** New k-terms for CO$_2$ (band 4) and O$_3$ (band 6) [^cite-ZhongH00], increasing the total number of k-terms by 14 relative to `spec3a_lw_hadgem1_5C` to allow a more accurate treatment of stratospheric absorption.
-Greenhouse gases: H₂O, CO₂, O₃, N₂O, CH₄, CFC-11, CFC-12, CFC-113, HCFC-22, HFC-134a.
+Greenhouse gases: H$_2$O, CO$_2$, O$_3$, N$_2$O, CH$_4$, CFC-11, CFC-12, CFC-113, HCFC-22, HFC-134a.
**Thermal emission:** Quartic fit over 150–330 K. The previous fit (180–330 K in `spec3a_lw_hadgem1_5C`) could give negative emission at very cold temperatures sometimes seen at the top of the model.
@@ -117,7 +117,7 @@ Greenhouse gases: H₂O, CO₂, O₃, N₂O, CH₄, CFC-11, CFC-12, CFC-113, HCF
### `sp_lw_ga3_1`
-Used for forecast configurations where speed of computation and a more accurate treatment of the troposphere are required. Sections are identical to `spec3a_lw_hadgem1_5C` except for changes to aerosols and ice crystals — the same additions as `sp_sw_ga3_0` — with the extra CO₂ and O₃ k-terms of `sp_lw_ga3_0` not included.
+Used for forecast configurations where speed of computation and a more accurate treatment of the troposphere are required. Sections are identical to `spec3a_lw_hadgem1_5C` except for changes to aerosols and ice crystals, the same additions as `sp_sw_ga3_0`, with the extra CO$_2$ and O$_3$ k-terms of `sp_lw_ga3_0` not included.
---
@@ -151,7 +151,7 @@ Used in the HadGEM2-A model and the global forecast model from PS20. All section
**Solar spectrum:** Kurucz (1995) [^cite-Kurucz95].
-**Gaseous absorption:** H₂O (with CKD 2.4 continuum [^cite-CKD]), O₃, CO₂, O₂. Foreign continuum combined with line data and fitted as one entity; self-broadened continuum represented explicitly. Spectroscopic data from HITRAN 2000 [^cite-HITRAN] with published corrections, augmented by theoretical weak lines.
+**Gaseous absorption:** H$_2$O (with CKD 2.4 continuum [^cite-CKD]), O$_3$, CO$_2$, O$_2$. Foreign continuum combined with line data and fitted as one entity; self-broadened continuum represented explicitly. Spectroscopic data from HITRAN 2000 [^cite-HITRAN] with published corrections, augmented by theoretical weak lines.
**Aerosols:** Five standard climatological aerosols [^cite-Cusack98], plus two sulphate modes (Aitken and accumulation), two black carbon modes (fresh and aged), two sea-salt modes (film and jet), two biomass smoke modes (fresh and aged), and six mineral dust size bins.
@@ -167,7 +167,7 @@ Used in the HadGEM2-A model and the global forecast model from PS20. All section
**Thermal emission:** Quartic fit over 180–330 K.
-**Gaseous absorption:** H₂O, O₃, CO₂, N₂O, CH₄, CFC-11, CFC-12, CFC-113, HCFC-22, HFC-125, HFC-134a. Spectroscopic data from HITRAN 92 for most gases; CKD 2.4 continuum for water vapour [^cite-CKD]. Halocarbon cross-sections from K. Shine (pers. comm.).
+**Gaseous absorption:** H$_2$O, O$_3$, CO$_2$, N$_2$O, CH$_4$, CFC-11, CFC-12, CFC-113, HCFC-22, HFC-125, HFC-134a. Spectroscopic data from HITRAN 92 for most gases; CKD 2.4 continuum for water vapour [^cite-CKD]. Halocarbon cross-sections from K. Shine (pers. comm.).
**Cloud droplets and ice crystals:** As per `spec3a_sw_hadgem1_3`. Only type 1 droplet data initially available for LW; types 4 and 5 (Padé fits) now recommended.
diff --git a/docs/Tutorials/first_run.md b/docs/Tutorials/first_run.md
new file mode 100644
index 00000000..7889d16b
--- /dev/null
+++ b/docs/Tutorials/first_run.md
@@ -0,0 +1,309 @@
+# First SOCRATES run
+
+This tutorial walks through computing thermal (longwave) radiative fluxes through a simple
+single-column water-vapour atmosphere. By the end you will have:
+
+- downloaded a PROTEUS spectral file,
+- prepared it for use with SOCRATES,
+- assembled a minimal set of atmospheric input files,
+- run SOCRATES, and
+- understood the output.
+
+**Prerequisites:** SOCRATES installed with `RAD_DIR` set and the `FWL_DATA` environment variable set (see [Installation](../How-to/installation.md)). Make sure you also have a [working Python environment](../How-to/installation.md#set-up-a-python-environment-optional) with the necessary dependencies.
+
+!!! note "Spectral file used in this tutorial"
+ We use **Frostflow-256**, a water-vapour-only file with 256 spectral bands from the
+ DACE opacity database. For quick debugging runs, a 16-band version is available on
+ [Zenodo](https://zenodo.org/records/15799743). For production work, the [4096-band version](https://zenodo.org/records/15799776) provides the highest resolution.
+
+---
+
+## 1. Download the spectral file
+
+PROTEUS spectral files are hosted on Zenodo. Each spectral file and band count is a
+separate record. Download Frostflow at 256 bands
+(Zenodo record [10.5281/zenodo.15799754](https://doi.org/10.5281/zenodo.15799754)):
+
+```bash
+mkdir -p $FWL_DATA/spectral_files/Frostflow/256
+
+wget "https://zenodo.org/records/15799754/files/Frostflow.sf?download=1" -O $FWL_DATA/spectral_files/Frostflow/256/Frostflow.sf
+wget "https://zenodo.org/records/15799754/files/Frostflow.sf_k?download=1" -O $FWL_DATA/spectral_files/Frostflow/256/Frostflow.sf_k
+```
+
+---
+
+## 2. Create a working directory
+
+```bash
+mkdir -p socrates_tutorial/out
+cd socrates_tutorial
+```
+
+---
+
+## 3. Prepare the spectral file
+
+The downloaded spectral file needs a thermal source function (Block 6) added before it
+can be used for longwave calculations. Copy it into your working directory first, then
+modify the local copy, leaving the original in `$FWL_DATA` untouched. While in `socrates_tutorial`:
+
+```bash
+cp $FWL_DATA/spectral_files/Frostflow/256/Frostflow.sf Frostflow.sf
+cp $FWL_DATA/spectral_files/Frostflow/256/Frostflow.sf_k Frostflow.sf_k
+```
+
+Source the SOCRATES environment to put `prep_spec` on your path:
+
+```bash
+source $RAD_DIR/set_rad_env
+```
+
+Now add Block 6 (thermal source function, tabulated over 100–4000 K at 250 temperature
+points). This uses the `prep_spec` utility interactively:
+
+```bash
+printf "%s\n" \
+ "Frostflow.sf" \
+ "a" \
+ "6" \
+ "n" \
+ "T" \
+ "100 4000" \
+ "250" \
+ "-1" \
+ | prep_spec
+```
+
+What each input does:
+
+| Input | Prompt | Meaning |
+|-------|--------|---------|
+| `$HOME/socrates_tutorial/Frostflow.sf` | File name | Full path to the local copy |
+| `a` | Append or new? | Append to existing file |
+| `6` | Block type | Block 6: thermal source function |
+| `n` | Filter required? | No |
+| `T` | Table or polynomial? | Tabulate |
+| `100 4000` | Temperature range (K) | Covers cold stratospheres to magma ocean surfaces |
+| `250` | Number of temperature points | Standard resolution |
+| `-1` | Next block | Write file and exit |
+
+Set a shell variable pointing to the prepared spectral file:
+
+```bash
+SPECTRUM=Frostflow.sf
+N_BANDS=256
+```
+
+---
+
+## 4. Prepare the atmospheric input files
+
+SOCRATES reads the atmospheric state from a set of netCDF files that share a common
+**basename** and differ only by their suffix. Here we use the basename `atm`.
+
+The atmosphere is divided into N homogeneous layers, bounded by N+1 levels. Layer
+mid-point values go into most files; level-edge temperatures go into `.tl`.
+
+We will set up a 10-layer hot steam atmosphere, the kind of conditions relevant to a
+post-magma-ocean planet.
+
+### 4.1 Install dependencies
+
+If you have not yet installed the necessary Python dependencies:
+
+```bash
+pip install -r "$RAD_DIR/python/requirements.txt"
+```
+
+### 4.2 Write the input script
+
+Save the following as `make_inputs.py` in `socrates_tutorial/`:
+
+```python
+import sys
+import os
+import numpy as np
+import f90nml
+
+# Import netCDF helpers from SOCRATES
+sys.path.insert(0, os.path.join(os.environ['RAD_DIR'], 'python'))
+from nctools import ncout_surf, ncout2d, ncout3d
+
+BASENAME = "out/atm"
+
+# --- Atmosphere structure ---
+N_LAYERS = 10
+p_surf = 1.0e7 # Pa (100 bar)
+p_top = 1.0e2 # Pa (1 mbar)
+p_mid = np.logspace(np.log10(p_surf), np.log10(p_top), N_LAYERS)
+
+T_surf = 1500.0 # K
+T_top = 200.0 # K
+t_mid = np.linspace(T_surf, T_top, N_LAYERS)
+
+# Level-edge values (N+1)
+p_lev = np.concatenate([[p_surf * 1.05],
+ 0.5 * (p_mid[:-1] + p_mid[1:]),
+ [p_top * 0.95]])
+t_lev = np.interp(p_lev, p_mid[::-1], t_mid[::-1])[::-1]
+
+# H2O mass mixing ratio: pure steam
+h2o = np.ones(N_LAYERS)
+
+# --- Write input files ---
+ncout3d(f"{BASENAME}.t", 0, 0, p_mid, t_mid, 't', longname="Temperature", units='K')
+ncout3d(f"{BASENAME}.tl", 0, 0, p_lev, t_lev, 'tl', longname="Temperature", units='K')
+ncout3d(f"{BASENAME}.p", 0, 0, p_mid, p_mid, 'p', longname="Pressure", units='Pa')
+ncout3d(f"{BASENAME}.q", 0, 0, p_mid, h2o, 'q', longname="q", units='kg/kg')
+
+ncout2d(f"{BASENAME}.tstar", 0, 0, T_surf, 'tstar', longname="Surface Temperature", units='K')
+ncout2d(f"{BASENAME}.pstar", 0, 0, p_surf, 'pstar', longname="Surface Pressure", units='Pa')
+ncout_surf(f"{BASENAME}.surf", 0, 0, 1, 0.0)
+
+# Planetary namelist — SOCRATES uses Earth defaults without this
+nml = {
+ 'socrates_constants': {
+ 'planet_radius': 6.371e6, # m
+ 'grav_acc': 9.81, # m s-2
+ 'mol_weight_air': 0.018, # kg mol-1 (pure H2O)
+ 'r_gas_dry': 462.0, # J kg-1 K-1
+ 'cp_air_dry': 1996.0, # J kg-1 K-1
+ }
+}
+f90nml.write(nml, f"{BASENAME}.nml")
+
+print("Input files written:")
+for f in sorted(os.listdir("out")):
+ if f.startswith("atm."):
+ print(f" out/{f}")
+```
+
+Run it:
+
+```bash
+python make_inputs.py
+```
+
+You should see eight files under `out/`: `out/atm.nml`, `out/atm.p`, `out/atm.pstar`, `out/atm.q`, `out/atm.surf`,
+`out/atm.t`, `out/atm.tl`, `out/atm.tstar`.
+
+---
+
+## 5. Run SOCRATES
+
+Run the longwave calculation, writing all output to the `out/` subdirectory:
+
+```bash
+Cl_run_cdf \
+ -B out/atm \
+ -s $SPECTRUM \
+ -R 1 $N_BANDS \
+ -ch $N_BANDS \
+ -I \
+ -g 2 \
+ -C 5 \
+ -u \
+ -N out/atm.nml
+```
+
+| Option | Meaning |
+|--------|---------|
+| `-B out/atm` | Basename: output files written to `out/` with prefix `atm` |
+| `-s $SPECTRUM` | Path to the prepared spectral file |
+| `-R 1 $N_BANDS` | Use spectral bands 1 to N_BANDS |
+| `-ch $N_BANDS` | Number of channels (must match `-R`) |
+| `-I` | Solve for thermal (longwave) source |
+| `-g 2` | Correlated-k gas overlap |
+| `-C 5` | Cloud scheme 5 (clear-sky — no cloud input files needed) |
+| `-u` | Write upward flux output files |
+| `-N out/atm.nml` | Namelist file with planetary parameters |
+
+Additionally, you can use the `-o` flag for verbose output.
+
+!!! tip "Adjust options"
+ The command shown above can be adjusted if preferred. use `man CL_run_cdf` for all options and information.
+
+---
+
+## 6. Inspect the output
+
+SOCRATES writes one netCDF output file per flux quantity under `out/`. These are netCDF files, although their file extensions are different. Each file also contains the wavelengths of each spectral band, and the pressure grid used.
+
+| File | Contents |
+|------|----------|
+| `out/atm.uflx` | Upward flux (W m$^{-2}$) |
+| `out/atm.dflx` | Diffuse downward flux (W m$^{-2}$) |
+| `out/atm.vflx` | Total downward flux (W m$^{-2}$) |
+| `out/atm.nflx` | Net downward flux (W m$^{-2}$) |
+| `out/atm.hrts` | Heating rates (K day$^{-1}$) |
+
+Read and plot the upward flux profile by pasting the following code in `plot.py`:
+
+```python
+import netCDF4 as nc
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Open the NetCDF file
+ds = nc.Dataset("out/atm.uflx")
+
+# Read the spectral upward-longwave fluxes at each layer
+spec_flux = ds.variables["uflx"][:, :, 0, 0]
+
+# Sum over all spectral bands to get bolometric flux
+bolo_flux = np.sum(spec_flux, axis=0)
+
+# Read pressure grid
+pres = ds.variables["plev"][:]
+
+# close the file
+ds.close()
+
+# Make the plot of flux versus pressure (i.e. height)
+plt.figure(dpi=300)
+plt.plot(bolo_flux, pres / 1e5, "b-o")
+plt.gca().invert_yaxis()
+plt.yscale("log")
+plt.xlabel(r"Upward flux (W m$^{-2}$)")
+plt.ylabel("Pressure (bar)")
+plt.title(r"Upward bolometric longwave flux, Frostflow-256, pure H$_2$O")
+plt.tight_layout()
+plt.savefig("out/flux_profile.pdf", bbox_inches="tight")
+
+# Print the outgoing longwave radiation flux
+olr = bolo_flux[0]
+print(f"OLR: {olr:.1f} W/m^2")
+
+plt.show()
+```
+
+Then:
+
+```bash
+python plot.py
+```
+
+The upward flux at the top of atmosphere is the **outgoing longwave radiation (OLR)**,
+the rate at which the atmosphere thermally emits radiation energy to space.
+
+Alternatively, you can use the `ncdump` command to view the content of netCDF files in the terminal directly. For example, to view header information from the upward flux file, run:
+
+```bash
+ncdump -h out/atm.uflx
+```
+
+---
+
+## 7. Next steps
+
+- **Add more gases.** Supply `.co2`, `.n2` etc. files and use a multi-gas spectral file
+ such as Dayspring or Honeyside.
+- **Add a stellar source.** Run with `-S` instead of `-I`, supplying `.stoa`, `.szen`,
+ and `.sazim` input files.
+- **Change planetary parameters.** Edit `atm.nml` to set the correct gravity, radius,
+ and molecular weight for your target planet.
+- **Increase resolution.** The 4096-band Frostflow provides higher-resolution results.
+
+For information on all available spectral files and their absorbers, see
+[PROTEUS spectral files](../Reference/proteus_spectral_file_reference.md).
\ No newline at end of file
diff --git a/docs/getting_started.md b/docs/getting_started.md
index e69de29b..9b908bd7 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -0,0 +1,75 @@
+---
+hide:
+ - navigation
+---
+
+Suite Of Community RAdiative Transfer codes based on Edwards and Slingo
+Suite Of Community RAdiative Transfer codes based on Edwards and Slingo
+ +
+
+
+
- 
- Schematic of PROTEUS components and corresponding modules.
-
Schematic of PROTEUS components and corresponding modules.
+