Implement documentation website

.github/workflows/docs.yaml

@@ -0,0 +1,73 @@
+name: Documentation website
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+permissions:
+  actions: read
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Find latest successful docs PDF build
+        id: latest-pdf-run
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data } = await github.rest.actions.listWorkflowRuns({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: "build-docs-pdf.yaml",
+              branch: "main",
+              status: "completed",
+              per_page: 50,
+            });
+
+            const latest = data.workflow_runs.find((run) => run.conclusion === "success");
+
+            if (!latest) {
+              core.setFailed("No successful build-docs-pdf.yaml runs found on branch main.");
+              return;
+            }
+            core.info(`Using build-docs-pdf run ${latest.id} from ${latest.created_at} on branch main.`);
+            core.setOutput("run_id", String(latest.id));
+      - name: Download docs PDFs from latest successful build
+        uses: actions/download-artifact@v5
+        with:
+          name: docs-pdf
+          path: docs
+          run-id: ${{ steps.latest-pdf-run.outputs.run_id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Place docs PDFs in MkDocs assets
+        run: |
+          set -euo pipefail
+          mkdir -p docs/assets/pdfs
+          USERGUIDE_PDF="$(find docs -type f -name 'socrates_userguide.pdf' | head -n 1)"
+          TECHGUIDE_PDF="$(find docs -type f -name 'socrates_techguide.pdf' | head -n 1)"
+          if [ -z "${USERGUIDE_PDF}" ] || [ -z "${TECHGUIDE_PDF}" ]; then
+            echo "Could not locate expected docs PDFs after artifact download."
+            exit 1
+          fi
+          cp "${USERGUIDE_PDF}" docs/assets/pdfs/socrates_userguide.pdf
+          cp "${TECHGUIDE_PDF}" docs/assets/pdfs/socrates_techguide.pdf
+      - run: pip install zensical markdown-include pymdown-extensions mkdocstrings mkdocstrings-python
+      - run: zensical build --clean 
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -44,3 +44,6 @@ __pycache__
 *.pyc
 .pytest_cache
 bin/
+
+# documentation site
+site/

CONTRIBUTORS.md

@@ -6,4 +6,5 @@
 | mo-jmanners | James Manners | Met Office | 2025-12-18 |
 | t00sa       | Sam Clarke-Green | Met Office | 2026-03-02 |
 | Pierre-siddall | Pierre Siddall | Met Office | 2026-03-16 |
-| nichollsh | Harrison Nicholls | University of Cambridge | 2026-03-24 |
+| nichollsh | Harrison Nicholls | University of Cambridge | 2026-03-19 |
+| stuitje | Karen Stuitje | University of Groningen | 2026-04-11 | 

docs/Community/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+contact@formingworlds.space.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docs/Community/contact.md

@@ -0,0 +1,9 @@
+# Contact
+
+We encourage you to reach out! Choose the most appropriate channel below.
+
+| Channel | Use for |
+|---------|---------|
+| [GitHub Discussions](https://github.com/orgs/FormingWorlds/discussions) | Questions, installation help, feature suggestions |
+| [GitHub Issues](https://github.com/FormingWorlds/SOCRATES/issues) | Bug reports, specific feature requests |
+| [proteus_dev@formingworlds.space](mailto:proteus_dev@formingworlds.space) | General enquiries |

docs/Explanations/interface.md

@@ -0,0 +1,86 @@
+# 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. 
+
+## Overview
+
+The SOCRATES interface is designed to present a **clear and logical structure** to the input and output fields required by the radiation code. All variables passed to the core routine are wrapped into well-defined Fortran derived types.
+
+---
+
+## Input and output types
+
+All arguments to the core routine `radiance_calc` are contained within **eight derived types**:
+
+| Type | Intent | Description |
+|---|---|---|
+| `control` | `IN` | Control options, initially read via a namelist |
+| `dimen` | `IN` | Array dimension sizes |
+| `spectrum` | `IN` | Spectral discretisation and optical properties read from the spectral file |
+| `atm` | `IN` | Grid discretisation and atmospheric profiles of thermodynamic quantities and gas amounts |
+| `cld` | `IN` | Cloud fields: fractions, mixing ratios, and sub-grid structure |
+| `aer` | `IN` | Aerosol fields: mixing ratios for CLASSIC aerosols, optical properties for GLOMAP-MODE aerosols |
+| `bound` | `IN` | Boundary conditions at top-of-atmosphere and surface: input fluxes, albedo/emissivity |
+| `radout` | `OUT` | All output variables: fluxes and other diagnostics |
+
+The first seven types are `INTENT(IN)` and `radout` is `INTENT(OUT)`. All variables required or produced by the code are contained within these types. Modules are used only to pass parameters, constants, and type definitions.
+
+---
+
+## Call structure
+
+The recommended structure for a calling model (such as the Unified Model) is:
+
+```fortran
+CALL read_control   ! Sets up control (elements that are not time-step dependent)
+CALL read_spectrum  ! Sets up spectrum by reading from a standard spectral file
+
+! --- Begin loop over time-steps / calls to radiation ---
+
+    CALL set_control  ! Sets control options for this call
+
+    ! --- Begin loop over OpenMP segments ---
+
+        CALL set_dimen   ! Sets dimen for this segment
+        CALL set_atm     ! CALL allocate_atm(atm, dimen), set atm
+        CALL set_cld     ! CALL allocate_cld(cld, dimen), set cld
+        CALL set_aer     ! CALL allocate_aer(aer, dimen), set aer
+        CALL set_bound   ! CALL allocate_bound(bound, dimen), set bound
+
+        CALL radiance_calc(control, dimen, spectrum, atm, cld, aer, bound, radout)
+        ! --> CALL allocate_out(radout, dimen), calculate radout
+        ! --> Assign required variables from radout onto the full model grid
+
+        DEALLOCATE(atm, cld, aer, bound, radout)
+
+    ! <-- End loop over OpenMP segments ---
+
+! <-- End loop over time-steps / calls to radiation ---
+```
+
+This structure is repeated separately for the SW and LW radiation calls.
+
+---
+
+## Core routines
+
+The core radiation code provides the following routines and modules:
+
+**`read_spectrum`**
+: A standard routine to read in spectral files, which can then be used interchangeably between models.
+
+**Type definition modules** (`def_spectrum`, `def_control`, `def_dimen`, `def_atm`, `def_cld`, `def_aer`, `def_bound`, `def_out`)
+: Type definitions including associated `allocate` and `deallocate` routines, and netCDF read/write routines in future.
+
+**`radiance_calc` and called routines**
+: The core radiation code itself.
+
+---
+
+## Routines provided by the calling model
+
+The calling model provides routines to set the input variables:
+
+**`set_control`, `set_dimen`, `set_atm`, `set_cld`, `set_aer`, `set_bound`**
+: These routines USE the type-definition modules from the core code.

docs/Explanations/overview.md

@@ -0,0 +1,73 @@
+# Physical model description
+
+!!! note
+    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?
+
+SOCRATES (Suite Of Community RAdiative Transfer codes based on Edwards and Slingo) is a flexible radiative transfer code developed at the Met Office. It computes **radiative fluxes and heating rates** throughout an atmospheric column, and is designed to serve a wide range of applications; from weather prediction to climate modelling and exoplanet atmosphere research.
+
+The code is structured around two core radiation solvers, supported by spectral files that encode the frequency discretisation and optical property data, and a well-defined interface to any calling model.
+
+---
+
+## Structure of the physical model
+
+### Radiation solvers
+
+SOCRATES provides two complementary approaches to solving the radiative transfer equation:
+
+#### [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:
+
+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$).
+3. A **two-stream approximation** (Eddington, PIFM, discrete ordinates, or hemispheric mean) is selected to close the system.
+4. **$\delta$-rescaling** corrects for strong forward scattering.
+5. The resulting linear system is solved by an efficient recurrence based on Gaussian elimination.
+
+The code handles gaseous absorption (including overlapping gases and continua), aerosols, Rayleigh scattering, water droplets, and ice crystals. Cloud overlap is treated via random, maximum-random, or exponential-random schemes, with the Monte Carlo Independent Column Approximation (McICA) available for sub-grid cloud variability.
+
+#### [Spherical harmonic radiance code](spherical_harmonic.md)
+
+The spherical harmonic code solves for the full angular radiance field by expanding $I(\mathbf{x}, n)$ in spherical harmonics $Y_l^m(n)$. This provides greater angular resolution than the two-stream approach, at higher computational cost, and is suited to applications requiring accurate radiances (e.g. remote sensing simulations). Key features include:
+
+- A **complementary function** built from eigensolutions of a symmetric tridiagonal system, with careful numerical stabilisation for conservative scattering and large optical depths.
+- **Particular integrals** for thermal emission (linear and quadratic Planckian variation) and the direct solar beam, with regularisation for small optical depths.
+- **Marshak boundary conditions** at the top of atmosphere, and a full **BRDF surface boundary condition**, including an ocean surface model with Fresnel reflection, Snell's law refraction, and particulate/absorption parametrisations.
+- The **TMS source function technique** [^cite-NT88] to accelerate convergence by separating single and multiple scattering.
+- A fast block-recurrence linear solver that reduces the dominant operation count from $O(18N^3 L)$ to $O(6N^3 L)$.
+
+### [Spectral files](spectral_files.md)
+
+Both solvers rely on **spectral files**: external, user-supplied files that define the frequency discretisation and store all spectrally dependent optical property data. This includes:
+
+- Band limits and solar fractions
+- k-distribution fits for gaseous absorption
+- Rayleigh scattering coefficients
+- Planck function polynomial fits
+- Parametrisations for cloud droplets, ice crystals, and aerosols
+
+The separation of spectral data from the radiation code itself makes SOCRATES highly flexible: a spectral file generated for one version of the code remains compatible with future versions, and new gases, aerosols, or parametrisations can be added without modifying the solver.
+
+### [Interface to the calling model](interface.md)
+
+SOCRATES is designed to be embedded in any atmospheric model through a clean, well-defined interface. All inputs and outputs are wrapped into eight structured types, `control`, `dimen`, `spectrum`, `atm`, `cld`, `aer`, `bound`, and `radout`, passed to the core routine `radiance_calc`. This design keeps the radiation code self-contained and straightforward to couple to new models.
+
+---
+
+## Choosing a solver
+
+| | Two-stream | Spherical harmonic |
+|---|---|---|
+| **Primary output** | Fluxes, heating rates | Radiances |
+| **Angular resolution** | Low (2 streams) | High (up to order $L$) |
+| **Computational cost** | Low | High |
+| **Typical use** | GCMs, NWP, climate runs | Remote sensing, offline studies |
+| **Cloud treatment** | Single column or McICA | Single column |
+| **Surface BRDF** | Albedo ($\alpha_s$, $\alpha_d$) | Full BRDF expansion |
+
+For most atmospheric modelling applications the **two-stream code** is the appropriate choice. The **spherical harmonic code** is used where accurate radiance fields are needed.
+
+[^cite-NT88]: T. Nakajima and M. Tanaka, *Algorithms for radiative intensity calculations in moderately thick atmospheres using a truncation approximation*, J. Quant. Spectrosc. Radiat. Transfer, 40:51–69, 1988.