' >> t.c && \
+echo 'int main(){printf("It seems to work!\n");}' >> t.c && \
+gcc t.c && ./a.out && rm -f t.c a.out
+```
+
+If that fails, your current compiler is not suitable for the quadruple-precision build.
+
+## 2. Install SUNDIALS with quadruple precision
+
+For quadruple precision, SPIDER uses a modified SUNDIALS build rather than PETSc’s default downloaded copy. The documented workflow is: clone the modified SUNDIALS repository, configure it with CMake, and set `SUNDIALS_PRECISION=quadruple`.
+
+!!! warning "Check that CMake is available"
+ Make sure that CMake is available:
+ ```bash
+ cmake --version
+ ```
+ If it is not installed, follow the instructions [here](https://cmake.org/download/), or run:
+
+ === "MacPorts"
+
+ ```bash
+ sudo port install cmake
+ ```
+
+ === "Homebrew"
+
+ ```bash
+ brew install cmake
+ ```
+
+ === "Ubuntu / Debian"
+
+ ```bash
+ sudo apt-get install cmake
+ ```
+
+```bash
+cd /somewhere/to/install
+mkdir -p sundials-quad
+cd sundials-quad
+
+git clone https://bitbucket.org/psanan/sundials-quad src
+mkdir install build
+cd build
+cmake ../src
+ccmake .
+```
+
+In `ccmake`, set values similar to:
+
+!!! note "Using the ccmake interface"
+ When using the `ccmake` interface, make sure you type "c" to configure once you have entered these values, then "g" to generate and exit.
+
+```
+CMAKE_C_COMPILER: gcc
+CMAKE_INSTALL_PREFIX: ../install
+EXAMPLES_INSTALL_PATH: ../install/examples
+SUNDIALS_PRECISION: quadruple
+```
+
+Then build and install:
+
+```
+make && make install
+```
+
+!!! note "C compiler"
+ Use the same C compiler here that you will use for PETSc.
+
+## 3. Install PETSc with quadruple precision
+
+Install the pinned snapshot if interested in reproducing previous results. Otherwise, install PETSc 3.19.
+
+=== "Pinned SPIDER-documented commit"
+
+ ```bash
+ cd /somewhere/to/install
+ git clone https://gitlab.com/petsc/petsc -b main petsc-quad
+ cd petsc-quad
+ git checkout 63b725033a15f75ded7183cf5f88ec748e60783b
+ ```
+
+=== "PETSc 3.19"
+
+ ```bash
+ cd /somewhere/to/install
+ git clone https://gitlab.com/petsc/petsc petsc-3.19
+ cd petsc-3.19
+ git checkout v3.19.6
+ ```
+
+Configure it against the SUNDIALS installation you just built:
+
+```bash
+./configure \
+ --with-debugging=0 \
+ --with-fc=0 \
+ --with-cxx=0 \
+ --with-cc=gcc \
+ --with-precision=__float128 \
+ --with-sundials=1 \
+ --with-sundials-dir=/somewhere/to/install/sundials-quad/install \
+ --download-mpich \
+ --download-f2cblaslapack \
+ --COPTFLAGS="-g -O3" \
+ --CXXOPTFLAGS="-g -O3"
+```
+
+Then follow PETSc’s terminal instructions to complete the build, and export the environment it reports:
+
+```bash
+export PETSC_DIR=/somewhere/to/install/petsc-quad
+export PETSC_ARCH=arch-xxx-yyy
+```
+
+## 4. Build SPIDER against the quadruple-precision PETSc
+
+Once `PETSC_DIR` and `PETSC_ARCH` point to your quadruple-precision PETSc build, build SPIDER normally:
+
+```bash
+cd /somewhere/to/install
+git clone https://github.com/FormingWorlds/SPIDER.git
+cd SPIDER
+
+make clean
+make -j
+```
+
+Then test your installation by following the steps in the [testing guide](test.md).
\ No newline at end of file
diff --git a/docs/How-to/test.md b/docs/How-to/test.md
new file mode 100644
index 00000000..106740a4
--- /dev/null
+++ b/docs/How-to/test.md
@@ -0,0 +1,134 @@
+# Testing SPIDER
+
+This guide explains how to validate your SPIDER installation using the test suite.
+
+!!! info "Prerequisites"
+ - SPIDER is compiled and the `spider` executable exists in the project root.
+ - PETSc is installed.
+ - Python 3.12 is available (preferably in a Conda environment).
+
+## 1. Install SciATH
+
+Get SciATH (Scientific Application Test Harness), which is a Python module:
+
+```bash
+cd /somewhere/to/install
+git clone https://github.com/sciath/sciath -b dev
+```
+
+Add the module to your Python path:
+
+```bash
+export PYTHONPATH=$PYTHONPATH:/path/to/sciath
+```
+
+## 2. Set `PETSC_DIR` and `PETSC_ARCH`
+
+`PETSC_DIR` and `PETSC_ARCH` are not automatically set after installing SPIDER. Set them manually:
+
+```bash
+export PETSC_DIR=/somewhere/to/install/petsc
+export PETSC_ARCH=arch-xxx-yyy
+```
+
+!!! info "What to set for `PETSC_DIR` and `PETSC_ARCH?`"
+ The SPIDER installer automatically reports the `PETSC_ARCH` and `PETSC_DIR` that PETSc was built against. To see what you need to set for these variables, run the installer again:
+ ```bash
+ ./tools/get_spider.sh
+ ```
+
+## 3. Test
+
+From the SPIDER root directory, test SPIDER's basic functionality:
+
+```bash
+make test
+```
+
+This command:
+
+1. Creates a `test_dir/` output directory.
+2. Runs the test harness on the suite defined in `tests/tests.yml`.
+3. Reports the location of the test output and a test report by SciATH.
+
+All test outputs are collected in `test_dir/`. After tests complete, you can find:
+
+```
+test_dir/
+ - pth.conf # Configuration file for test harness
+ - blackbody50_output/ # Output from standard test
+ - external_mesh_roundtrip_output/ # External mesh validation
+ - non_aw_mesh_output/ # Non-AW mesh validation
+ - plot_test_output/ # Plotting test output
+ - sciath_test_report.txt # SciATH test report
+```
+
+## What the test suite validates
+
+The test suite (defined in `tests/tests.yml`) runs several checks:
+
+| Test | Purpose |
+|------|---------|
+| `blackbody50` | Core interior dynamics on a Earth-like blackbody planet. Final state is compared against known outputs. Check `tests/opts/blackbody50.opt` for exact configuration.|
+| `plot_test` | Validates the Python plotting script (`py/plot_spider_lite.py`) runs without error. |
+| `external_mesh_roundtrip` | Verifies SPIDER accepts external mesh files and produces correct results. |
+| `non_aw_mesh` | Confirms SPIDER works with non-Adams-Williamson density profiles. |
+
+For setup details and file format requirements, see [External Mesh Input](external_mesh_input.md).
+
+Each test runs one or more commands and compares output against expected values with specified tolerances.
+
+## Common test issues
+
+### SciATH not found
+
+```
+Error: sciath module not found
+```
+
+**Solution:**
+Ensure SciATH is cloned and added to `PYTHONPATH`:
+
+```bash
+export PYTHONPATH=$PYTHONPATH:/path/to/sciath
+make test
+```
+
+### Tolerance mismatches
+
+If a test fails with a tolerance error (e.g., relative tolerance exceeded), it usually indicates:
+
+- A code change that alters output slightly (check your recent commits).
+- Different compiler flags or PETSc version (some tests have tight tolerances). Note that by default, PETSc version 3.19.0 is installed, and newer versions might lead to tolerance errors.
+- Differences in floating-point rounding between systems.
+
+Most tests have `rtol: 1e-5` (relative tolerance) and `atol: 1e-5` (absolute tolerance). See `tests/tests.yml` for specific thresholds.
+
+### Plot test fails
+
+The `plot_test` checks that the Python plotting script runs without error. If it fails, plot the test output manually and see what is going wrong:
+
+```bash
+python py/plot_spider_lite.py -d test_dir/blackbody50_output/sandbox/output
+```
+
+This generates a file called `interior.pdf` into a `plots/` directory.
+
+If need, install missing dependencies:
+
+```bash
+pip install -r py/requirements.txt
+```
+
+## Comparing against expected output
+
+After a test run completes, you can manually compare your output against known good results. A quick way to check everything worked well, is by comparing plots. If you have VS Code's `code` installed:
+
+```bash
+code test_dir/plot_test_output/sandbox/plots/interior.pdf
+code tests/expected_output/blackbody50-interior.png
+```
+
+or open the files manually.
+
+Expected files are in `tests/expected_output/`. Small differences due to compiler or system differences are usually acceptable if they are within the specified tolerances.
\ No newline at end of file
diff --git a/docs/Tutorials/first_run.md b/docs/Tutorials/first_run.md
new file mode 100644
index 00000000..8d7b074a
--- /dev/null
+++ b/docs/Tutorials/first_run.md
@@ -0,0 +1,57 @@
+# Tutorial: first SPIDER run
+
+This page walks you through a minimal SPIDER run, from compile to quick visualization.
+
+!!! info "Prerequisites"
+ - You have installed PETSc and SPIDER by going through the [installation guide](../How-to/installation.md).
+ - You have a working C compiler.
+ - Preferably: you are in a Conda environment with python version 3.12.
+
+## 1. Run a known example
+
+Use one of the provided options files:
+
+```bash
+./spider -options_file tests/opts/blackbody50.opts
+```
+
+This writes model output to the default output directory (typically `output/`).
+
+!!! info "Runtime"
+ A first run on a laptop/workstation typically finishes in seconds to a few minutes, depending on CPU and PETSc settings.
+
+To quickly verify output structure:
+
+```bash
+ls output
+```
+You should see text files with radial profiles and time-series data.
+
+Expected signs of success:
+
+- `output` exists and is non-empty.
+- Multiple text files are produced (for example, interior profile and time-series outputs).
+- No PETSc crash/solver error is printed to terminal.
+
+## 2. Make a quick plot
+
+```bash
+python py/plot_spider_lite.py -h
+python py/plot_spider_lite.py -d output
+```
+
+The plotting script generates a basic figure of interior profiles from your run output inside the directory `plots/`.
+
+## 3. Next steps
+
+- Try a different options file in `tests/opts/`.
+- Compare your run output against files in `tests/expected_output/`.
+
+## Common first-run issues
+
+- `PETSC_DIR` or `PETSC_ARCH` not set:
+ Re-export them in your shell and rebuild.
+- `./spider` not found:
+ Build failed or you are not in the project root.
+- Plot script fails:
+ Install Python dependencies from `py/requirements.txt`.
\ No newline at end of file
diff --git a/docs/assets/schematic_round.png b/docs/assets/schematic_round.png
new file mode 100644
index 00000000..f5033381
Binary files /dev/null and b/docs/assets/schematic_round.png differ
diff --git a/docs/getting_started.md b/docs/getting_started.md
new file mode 100644
index 00000000..7004a181
--- /dev/null
+++ b/docs/getting_started.md
@@ -0,0 +1,60 @@
+# Getting started
+
+!!! note "Usage within the PROTEUS framework"
+ SPIDER is most commonly installed and used as integrated into the PROTEUS framework. Understand how to use PROTEUS [here](https://proteus-framework.org/PROTEUS).
+
+## Quick path
+
+Here is the quickest path to getting started:
+
+1. **Install SPIDER**
+ Follow the installation steps.
+ → [Installation guide](How-to/installation.md)
+
+2. **Test SPIDER**
+ Test the basic functionality of SPIDER.
+ → [Test guide](How-to/test.md)
+
+3. **Run your first model**
+ Follow a minimal example run and generate a quick plot.
+ → [First run tutorial](Tutorials/first_run.md)
+
+---
+
+## What do you want to do?
+
+
+
+- :material-download: **Install**
+
+ [Go to installation guide](How-to/installation.md)
+
+- :material-test-tube: **Test SPIDER**
+
+ [Go to testing guide](How-to/test.md)
+
+- :material-rocket-launch: **Run SPIDER**
+
+ [Go to tutorials](Tutorials/first_run.md)
+
+- :material-book-open-variant: **Understand the model**
+
+ [Go to model overview](Explanations/basic_thermodynamics.md)
+
+- :material-bookshelf: **Check SPIDER publications**
+
+ [Go to publications](Reference/publications.md)
+
+- :material-github: **Contribute / browse code**
+
+ [Go to source code](https://github.com/FormingWorlds/SPIDER)
+
+- :material-bug: **Raise an issue**
+
+ [Go to issues](https://github.com/FormingWorlds/SPIDER/issues)
+
+- :material-email: **Get in touch**
+
+ [Go to contact](Community/contact.md)
+
+
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index 7a025b5a..33a371ab 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,15 +18,7 @@
SPIDER is a 1-D parameterised interior dynamics code for rocky planets with molten and/or solid interiors and support for volatile cycling, redox reactions, and radiative transfer in the atmosphere.
!!! note
- This documentation describes the version of SPIDER as part of the [PROTEUS Framework](https://proteus-framework.org/proteus). For the original SPIDER code, see [djbower/SPIDER](https://github.com/djbower/spider).
-
-## Getting started
-
-- [Installation guide](How-to/installation.md)
-- [Publications](Reference/publications.md)
-- [Model overview](Explanations/model.md)
-- [Source code](https://github.com/FormingWorlds/SPIDER)
-- [Contact](Community/contact.md)
+ This documentation describes the version of SPIDER as part of the [PROTEUS Framework](https://proteus-framework.org/PROTEUS). For the original SPIDER code, see [djbower/SPIDER](https://github.com/djbower/spider).
If you plan to contribute to SPIDER, please read our [Code of Conduct](Community/CODE_OF_CONDUCT.md).
If you are running into problems, please do not hesitate to raise an [Issue](https://github.com/FormingWorlds/SPIDER/issues).
diff --git a/docs/proteus_framework.md b/docs/proteus_framework.md
new file mode 100644
index 00000000..d0f3c6a1
--- /dev/null
+++ b/docs/proteus_framework.md
@@ -0,0 +1,20 @@
+
+
+SPIDER is the interior evolution module of PROTEUS (/ˈproʊtiəs, PROH-tee-əs), a modular Python framework that simulates the coupled evolution of the atmospheres and interiors of rocky planets and exoplanets. A schematic of PROTEUS components and corresponding modules can be found below.
+
+
+You can find the documentation of each PROTEUS module in the sidebar.
+
+
+
+
+ 
+ Schematic of PROTEUS components and corresponding modules.
+
\ No newline at end of file
diff --git a/docs/refs.bib b/docs/refs.bib
index 06fa6b46..85dff414 100644
--- a/docs/refs.bib
+++ b/docs/refs.bib
@@ -20869,7 +20869,7 @@ @Book{DM62
title = {Non-Equilibrium Thermodynamics},
publisher = {North-Holland Publishing Company, Amsterdam},
year = {1962},
- author = {S. R. {De~Groot} and P. Mazur},
+ author = {S. R. De Groot and P. Mazur},
}
@Article{CGH00,
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 29aed185..83c5b8f0 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -1,40 +1,250 @@
-/* Preserve line breaks when docstrings render as plain paragraphs */
-.doc-contents p {
- white-space: pre-wrap;
+/* =========================================================
+ PROTEUS theme variables
+ ========================================================= */
+
+/* Be careful when changing these, as they affect multiple elements across the site. */
+
+[data-md-color-scheme="default"],
+[data-md-color-scheme="slate"] {
+ --md-primary-fg-color: #1c2b4b;
+ --md-primary-fg-color--light: #2a3d69;
+ --md-primary-fg-color--dark: #14203a;
+
+ --proteus-highlight-color: #ff6e40;
+ --proteus-highlight-bg-soft: rgba(255, 109, 64, 0.093);
+
+ --md-accent-fg-color: var(--proteus-highlight-color);
+
+ --md-typeset-a-color: #3b6193;
+}
+
+/* Softer slate background + more muted link color */
+[data-md-color-scheme="slate"] {
+ --md-default-bg-color: #0f172ad2;
+ --md-default-bg-color--light: #1e293b;
+ --md-default-bg-color--lighter: #334155;
+ --md-default-bg-color--lightest: #475569;
+
+ --md-typeset-a-color: #8fa8c9;
+}
+
+/* =========================================================
+ Header + tabs
+ ========================================================= */
+
+[data-md-color-scheme="default"] .md-header,
+[data-md-color-scheme="default"] .md-tabs,
+[data-md-color-scheme="slate"] .md-header,
+[data-md-color-scheme="slate"] .md-tabs {
+ background-color: var(--md-primary-fg-color);
+}
+
+[data-md-color-scheme="default"] .md-header *,
+[data-md-color-scheme="default"] .md-tabs *,
+[data-md-color-scheme="slate"] .md-header *,
+[data-md-color-scheme="slate"] .md-tabs * {
+ color: #fff !important;
+ fill: #fff !important;
+}
+
+/* =========================================================
+ Expanded search
+ ========================================================= */
+
+[data-md-color-scheme="default"] .md-search__form,
+[data-md-color-scheme="slate"] .md-search__form {
+ background-color: rgba(255, 255, 255, 0.12) !important;
+ border-radius: 0.2rem !important;
+ box-shadow: none !important;
+}
+
+[data-md-color-scheme="default"] .md-search__form:hover,
+[data-md-color-scheme="default"] .md-search__form:focus-within,
+[data-md-color-scheme="slate"] .md-search__form:hover,
+[data-md-color-scheme="slate"] .md-search__form:focus-within {
+ background-color: rgba(255, 255, 255, 0.16) !important;
+}
+
+[data-md-color-scheme="default"] .md-search__input,
+[data-md-color-scheme="slate"] .md-search__input {
+ color: #fff !important;
+ -webkit-text-fill-color: #fff !important;
+ caret-color: #fff !important;
+ background: transparent !important;
+ -webkit-appearance: none;
+ appearance: none;
+}
+
+[data-md-color-scheme="default"] .md-search__input::placeholder,
+[data-md-color-scheme="slate"] .md-search__input::placeholder {
+ color: rgba(255, 255, 255, 0.75) !important;
+ -webkit-text-fill-color: rgba(255, 255, 255, 0.75) !important;
+ opacity: 1 !important;
+}
+
+/* Hide browser-native search decorations */
+.md-search__input::-webkit-search-decoration,
+.md-search__input::-webkit-search-cancel-button,
+.md-search__input::-webkit-search-results-button,
+.md-search__input::-webkit-search-results-decoration {
+ -webkit-appearance: none;
+ appearance: none;
+ display: none;
+}
+
+/* Expanded search icons */
+[data-md-color-scheme="default"] .md-search__icon,
+[data-md-color-scheme="default"] .md-search__icon svg,
+[data-md-color-scheme="default"] .md-search__icon svg *,
+[data-md-color-scheme="default"] .md-search__label,
+[data-md-color-scheme="default"] .md-search__label svg,
+[data-md-color-scheme="default"] .md-search__label svg *,
+[data-md-color-scheme="slate"] .md-search__icon,
+[data-md-color-scheme="slate"] .md-search__icon svg,
+[data-md-color-scheme="slate"] .md-search__icon svg *,
+[data-md-color-scheme="slate"] .md-search__label,
+[data-md-color-scheme="slate"] .md-search__label svg,
+[data-md-color-scheme="slate"] .md-search__label svg * {
+ color: #fff !important;
+ fill: #fff !important;
+ stroke: #fff !important;
+ opacity: 1 !important;
+}
+
+/* =========================================================
+ Collapsed search trigger in header
+ ========================================================= */
+
+[data-md-color-scheme="default"] .md-search__button,
+[data-md-color-scheme="slate"] .md-search__button {
+ color: #fff !important;
+ background-color: rgba(255, 255, 255, 0.12) !important;
+ border-radius: 0.6rem !important;
}
-/* Wrap long identifiers instead of overflowing */
-.doc-contents,
-.doc-contents * {
- overflow-wrap: anywhere;
+[data-md-color-scheme="default"] .md-search__button:hover,
+[data-md-color-scheme="default"] .md-search__button:focus,
+[data-md-color-scheme="slate"] .md-search__button:hover,
+[data-md-color-scheme="slate"] .md-search__button:focus {
+ background-color: rgba(255, 255, 255, 0.16) !important;
}
-/* ---- Footnote/citation markers: render as inline [1] instead of superscript ---- */
-.md-typeset sup[id^="fnref"] {
- vertical-align: baseline !important;
- font-size: 1em !important;
- line-height: inherit !important;
+/* Collapsed magnifier */
+[data-md-color-scheme="default"] .md-search__button::before,
+[data-md-color-scheme="slate"] .md-search__button::before {
+ color: #fff !important;
+ -webkit-text-fill-color: #fff !important;
+ filter: brightness(0) invert(1) !important;
+ opacity: 1 !important;
}
-.md-typeset sup[id^="fnref"] > a.footnote-ref {
- text-decoration: none;
+/* If an inner SVG is used in some states */
+[data-md-color-scheme="default"] .md-search__button svg,
+[data-md-color-scheme="default"] .md-search__button svg *,
+[data-md-color-scheme="slate"] .md-search__button svg,
+[data-md-color-scheme="slate"] .md-search__button svg * {
+ fill: #fff !important;
+ stroke: #fff !important;
+ color: #fff !important;
}
-.md-typeset sup[id^="fnref"] > a.footnote-ref::before { content: "["; }
-.md-typeset sup[id^="fnref"] > a.footnote-ref::after { content: "]"; }
+/* Shortcut badge */
+[data-md-color-scheme="default"] .md-search__button kbd,
+[data-md-color-scheme="default"] .md-search__button .md-search__kbd,
+[data-md-color-scheme="slate"] .md-search__button kbd,
+[data-md-color-scheme="slate"] .md-search__button .md-search__kbd {
+ color: rgba(255, 255, 255, 0.9) !important;
+ background-color: rgba(255, 255, 255, 0.18) !important;
+ border: none !important;
+ box-shadow: none !important;
+}
+
+/* Badge drawn as pseudo-element in some versions */
+[data-md-color-scheme="default"] .md-search__button::after,
+[data-md-color-scheme="slate"] .md-search__button::after {
+ background-color: rgba(255, 255, 255, 0.12) !important;
+ border: none !important;
+ box-shadow: none !important;
+ color: rgba(255, 255, 255, 0.9) !important;
+}
+
+/* =========================================================
+ Top tabs
+ ========================================================= */
+
+/* All tab labels white by default */
+[data-md-color-scheme="default"] .md-tabs__link,
+[data-md-color-scheme="slate"] .md-tabs__link {
+ color: #fff !important;
+ opacity: 0.9 !important;
+ transition: color 0.15s ease, opacity 0.15s ease !important;
+}
-/* fallback (some versions/themes) */
-.md-typeset a.footnote-ref {
- vertical-align: baseline !important;
- font-size: 1em !important;
+/* Hover state */
+[data-md-color-scheme="default"] .md-tabs__link:hover,
+[data-md-color-scheme="slate"] .md-tabs__link:hover {
+ color: var(--proteus-highlight-color) !important;
+ opacity: 0.8 !important;
}
-/* reduce space under the page title */
-.md-typeset h1 {
- margin-bottom: 0.2rem; /* try 0, 0.2rem, 0.5rem */
+/* Active tab text only, no underline */
+[data-md-color-scheme="default"] .md-tabs__item--active,
+[data-md-color-scheme="default"] .md-tabs__link--active,
+[data-md-color-scheme="default"] .md-tabs__item--active .md-tabs__link,
+[data-md-color-scheme="slate"] .md-tabs__item--active,
+[data-md-color-scheme="slate"] .md-tabs__link--active,
+[data-md-color-scheme="slate"] .md-tabs__item--active .md-tabs__link {
+ color: var(--proteus-highlight-color) !important;
+ box-shadow: none !important;
+ border-bottom: none !important;
+ text-decoration: none !important;
+}
+
+/* Remove any underline/pseudo-element indicator */
+[data-md-color-scheme="default"] .md-tabs__item--active::after,
+[data-md-color-scheme="default"] .md-tabs__link--active::after,
+[data-md-color-scheme="default"] .md-tabs__item--active .md-tabs__link::after,
+[data-md-color-scheme="slate"] .md-tabs__item--active::after,
+[data-md-color-scheme="slate"] .md-tabs__link--active::after,
+[data-md-color-scheme="slate"] .md-tabs__item--active .md-tabs__link::after {
+ content: none !important;
+ display: none !important;
+ background: none !important;
+}
+
+/* =========================================================
+ Sidebar navigation
+ ========================================================= */
+
+/* Style only active leaf page links */
+[data-md-color-scheme="default"] .md-nav__item .md-nav__link--active:not(.md-nav__link--passed),
+[data-md-color-scheme="slate"] .md-nav__item .md-nav__link--active:not(.md-nav__link--passed) {
+ background-color: var(--proteus-highlight-bg-soft) !important;
+ border-radius: 1rem !important;
+ color: var(--proteus-highlight-color) !important;
+ padding-left: 1rem;
+ padding-right: 1rem;
+}
+
+/* =========================================================
+ Footer
+ ========================================================= */
+
+/* Remove underline from footer copyright link */
+.md-footer-copyright a,
+.md-footer-meta a {
+ text-decoration: none !important;
+}
+
+/* =========================================================
+ Make header title look clickable and add hover effect
+ ========================================================= */
+
+.md-header__title[data-md-component="header-title"] {
+ cursor: pointer;
+ transition: opacity 0.15s ease !important;
}
-/* optionally reduce any top margin on the first image */
-.md-typeset h1 + p img {
- margin-top: 0;
+.md-header__title[data-md-component="header-title"]:hover {
+ opacity: 0.7 !important;
}
diff --git a/docs/stylesheets/footnotes.css b/docs/stylesheets/footnotes.css
new file mode 100644
index 00000000..f3729cf1
--- /dev/null
+++ b/docs/stylesheets/footnotes.css
@@ -0,0 +1,29 @@
+/* ---- Footnote/citation markers: render as inline [1] instead of superscript ---- */
+.md-typeset sup[id^="fnref"] {
+ vertical-align: baseline !important;
+ font-size: 1em !important;
+ line-height: inherit !important;
+}
+
+.md-typeset sup[id^="fnref"] > a.footnote-ref {
+ text-decoration: none;
+}
+
+.md-typeset sup[id^="fnref"] > a.footnote-ref::before { content: "["; }
+.md-typeset sup[id^="fnref"] > a.footnote-ref::after { content: "]"; }
+
+/* fallback (some versions/themes) */
+.md-typeset a.footnote-ref {
+ vertical-align: baseline !important;
+ font-size: 1em !important;
+}
+
+/* reduce space under the page title */
+.md-typeset h1 {
+ margin-bottom: 0.2rem; /* try 0, 0.2rem, 0.5rem */
+}
+
+/* optionally reduce any top margin on the first image */
+.md-typeset h1 + p img {
+ margin-top: 0;
+}
diff --git a/mkdocs.yml b/mkdocs.yml
index ef219825..76435368 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -3,26 +3,50 @@ site_url: https://proteus-framework.org/SPIDER/
repo_url: https://github.com/FormingWorlds/SPIDER
repo_name: GitHub
+copyright: '© 2023-2026 Forming Worlds Lab'
+
nav:
- - Home: index.md
+ - Home:
+ - About: index.md
+ - Getting started: getting_started.md
+
- How-to guides:
- - Installation: How-to/installation.md
+ - Installation:
+ - Quick installation: How-to/installation.md
+ - Quadruple precision: How-to/quadruple_installation.md
+ - Testing: How-to/test.md
+ - External mesh input: How-to/external_mesh_input.md
+
+ - Tutorials:
+ - First run: Tutorials/first_run.md
- Explanations:
- - Model overview: Explanations/model.md
+ - Model overview:
+ - Thermodynamics: Explanations/basic_thermodynamics.md
+ - Mass conservation and energy transport: Explanations/transport.md
+ - Material properties: Explanations/material_properties.md
+ - Mass coordinates: Explanations/mass_coordinates.md
+ - Parameterised fluxes: Explanations/parameterised_fluxes.md
+ - Phase separation and thermal evolution (Abe 1993): Explanations/abe1993.md
+ - Internal heating: Explanations/internal_heating.md
+ - Atmosphere: Explanations/atmosphere.md
+ - Boundary conditions: Explanations/boundary_conditions.md
+ - Hybrid equation of state: Explanations/hybrid_eos.md
+ - Toy model and numerical schemes: Explanations/toy_model.md
- Reference:
- Publications: Reference/publications.md
- Community:
- Code of Conduct: Community/CODE_OF_CONDUCT.md
- - Developers: https://proteus-framework.org/people
- Contact: Community/contact.md
+ - Developers: https://proteus-framework.org/people
+ - Issues: https://github.com/FormingWorlds/SPIDER/issues
- Source code: https://github.com/FormingWorlds/SPIDER
- - Issues page: https://github.com/FormingWorlds/SPIDER/issues
- Other PROTEUS modules:
+ - PROTEUS submodules: proteus_framework.md
- 🔗 PROTEUS: https://proteus-framework.org/PROTEUS/
- 🔗 MORS: https://proteus-framework.org/MORS/
- 🔗 JANUS: https://proteus-framework.org/JANUS/
@@ -36,13 +60,17 @@ nav:
- 🔗 Atmodeller: https://atmodeller.readthedocs.io/en/latest/
- 🔗 FastChem: https://newstrangeworlds.github.io/FastChem/
- 🔗 PLATON: https://platon.readthedocs.io/en/latest/
+ - 🔗 SOCRATES: https://github.com/FormingWorlds/SOCRATES/
theme:
name: material
custom_dir: docs/overrides
features:
- - content.code.copy
- - navigation.expand
+ - navigation.tabs
+ - navigation.tabs.sticky
+ - navigation.expand
+ - content.code.copy
+ - content.tabs.link
# Default assets (used unless overridden per palette below)
favicon: assets/PROTEUS_black_on_white_logo_only.png
@@ -52,12 +80,12 @@ theme:
# Auto: follow system preference (and show a toggle)
- media: "(prefers-color-scheme: light)"
scheme: default
- primary: black
- accent: deep orange
+ primary: custom
+ accent: custom
favicon: assets/PROTEUS_black_on_white_logo_only.png
logo: assets/PROTEUS_white_on_black.png
toggle:
- icon: material/weather-night
+ icon: lucide/moon
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
@@ -67,11 +95,12 @@ theme:
favicon: assets/PROTEUS_white_on_black_logo_only.png
logo: assets/PROTEUS_white_on_black.png
toggle:
- icon: material/weather-sunny
+ icon: lucide/sun
name: Switch to light mode
extra_css:
- stylesheets/extra.css
+ - stylesheets/footnotes.css
markdown_extensions:
- admonition
@@ -81,12 +110,37 @@ markdown_extensions:
- pymdownx.extra
- pymdownx.arithmatex:
generic: true
+ - pymdownx.superfences
+ - pymdownx.tabbed:
+ alternate_style: true
+ - pymdownx.details
+ - md_in_html
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
- footnotes
extra_javascript:
- - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
- javascripts/header-links.js
+ - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+# footer:
+extra:
+ generator: false
+ social:
+ - icon: material/web
+ link: https://proteus-framework.org/
+ name: PROTEUS website
+ - icon: material/email
+ link: mailto:proteus_dev@formingworlds.space
+ name: Mail PROTEUS developers
+ - icon: fontawesome/brands/python
+ link: https://pypi.org/project/fwl-proteus/
+ name: PROTEUS on PyPI
+ - icon: fontawesome/brands/github
+ link: https://github.com/FormingWorlds/PROTEUS
+ name: PROTEUS on GitHub
+
plugins:
- search
- tags
diff --git a/py/citations.py b/py/citations.py
new file mode 100644
index 00000000..4928331a
--- /dev/null
+++ b/py/citations.py
@@ -0,0 +1,94 @@
+import re
+from pathlib import Path
+try:
+ import bibtexparser
+except ImportError as exc:
+ raise SystemExit(
+ "The 'bibtexparser' package is required to run py/citations.py. "
+ "Please install it (e.g., with 'pip install bibtexparser') and "
+ "ensure it is listed in py/requirements.txt."
+ ) from exc
+
+DOCS_DIR = Path("docs")
+BIB_FILE = DOCS_DIR / "refs.bib"
+
+CITE_PATTERN = re.compile(r"\[@([A-Za-z0-9:_-]+)([^\]]*)\]")
+
+def clean_tex(s):
+ if not s:
+ return ""
+ return (
+ s.replace("{", "")
+ .replace("}", "")
+ .replace("~", " ")
+ .replace("\\&", "&")
+ .strip()
+ )
+
+def format_authors(author_field):
+ if not author_field:
+ return ""
+ authors = [clean_tex(a.strip()) for a in author_field.split(" and ")]
+ return "; ".join(authors)
+
+def format_entry(entry):
+ authors = format_authors(entry.get("author", ""))
+ title = clean_tex(entry.get("title", "Untitled"))
+ year = clean_tex(entry.get("year", "n.d."))
+ journal = clean_tex(
+ entry.get("journal") or entry.get("booktitle") or entry.get("publisher") or ""
+ )
+ address = clean_tex(entry.get("address", ""))
+
+ parts = [authors, f"*{title}*", journal, address, year]
+ return ", ".join(p for p in parts if p) + "."
+
+def main():
+ with open(BIB_FILE, "r", encoding="utf-8") as f:
+ bib_db = bibtexparser.load(f)
+
+ bib_map = {e["ID"]: format_entry(e) for e in bib_db.entries if "ID" in e}
+
+ for md_file in DOCS_DIR.rglob("*.md"):
+ text = md_file.read_text(encoding="utf-8")
+
+ # Skip files that do not contain raw citation syntax.
+ if not CITE_PATTERN.search(text):
+ print(f"Skipped {md_file} (no [@...] citations found)")
+ continue
+
+ used = {}
+
+ def repl(match):
+ key = match.group(1)
+ suffix = match.group(2).strip()
+ used[key] = bib_map.get(key, f"Missing bibliography entry for {key}.")
+ if suffix:
+ return f"[^cite-{key}], {suffix}"
+ return f"[^cite-{key}]"
+
+ new_text = CITE_PATTERN.sub(repl, text)
+
+ if used:
+ footnotes = "\n".join(
+ f"[^cite-{key}]: {value}" for key, value in used.items()
+ )
+
+ # Remove an existing \bibliography line if present
+ new_text = re.sub(r"(?m)^\s*\\bibliography\s*$\n?", "", new_text)
+
+ # Remove any old generated cite footnotes before appending fresh ones
+ new_text = re.sub(
+ r"(?m)^\[\^cite-[A-Za-z0-9:_-]+\]:\s.*(?:\n(?!\[\^cite-).*)*",
+ "",
+ new_text
+ ).rstrip()
+
+ new_text += "\n\n" + footnotes + "\n"
+
+ md_file.write_text(new_text, encoding="utf-8")
+ print(f"Processed {md_file}")
+
+
+if __name__ == "__main__":
+ main()
\ No newline at end of file
diff --git a/py/plot_spider_lite.py b/py/plot_spider_lite.py
index 602f3d0f..859896bb 100755
--- a/py/plot_spider_lite.py
+++ b/py/plot_spider_lite.py
@@ -445,7 +445,7 @@ def set_xaxis_from_kwargs(ax, myjson_o=None, **kwargs):
ax.set_xlim(np.min(xticks), np.max(xticks))
ax.invert_xaxis()
ax.xaxis.set_major_locator(ticker.FixedLocator(xticks))
- ax.set_xlabel("Melt fraction (\%)")
+ ax.set_xlabel(r"Melt fraction (%)")
# ====================================================================
@@ -482,7 +482,11 @@ def figure_interior(indir="output", time=None):
labels = ("{:.2e}".format(time) for time in myjson_o.time_l)
axs[1][1].legend(handles, labels, ncol=2, title="Time (yrs)")
- fig.savefig("interior.pdf")
+ # create output directory if it does not exist
+ os.makedirs("plots", exist_ok=True)
+
+ # save figure in plots directory
+ fig.savefig(os.path.join("plots", "interior.pdf"))
# ===================================================================
diff --git a/rhs.c b/rhs.c
index b20e7b16..4907c030 100644
--- a/rhs.c
+++ b/rhs.c
@@ -20,6 +20,7 @@ PetscErrorCode RHSFunction(TS ts,PetscReal t,Vec sol_in,Vec rhs,void *ptr)
Solution *S = &E->solution;
PetscScalar *arr_dSdt_s, *arr_rhs_b;
const PetscScalar *arr_Etot, *arr_capacitance_s, *arr_temp_s, *arr_cp_s, *arr_Htot_s, *arr_xi_s;
+ PetscScalar dSdt_s0;
PetscMPIInt rank,size;
DM da_s = E->da_s, da_b=E->da_b;
PetscInt i,v,ihi_s,ilo_s,w_s,numpts_b;
@@ -60,7 +61,7 @@ PetscErrorCode RHSFunction(TS ts,PetscReal t,Vec sol_in,Vec rhs,void *ptr)
arr_dSdt_s[0] = ( arr_Etot[1] - arr_Etot[0] ) / arr_capacitance_s[0];
arr_dSdt_s[0] += arr_Htot_s[0] / arr_temp_s[0];
- /* dSdt at staggered nodes and d/dt(dS/dr) at internal basic nodes */
+ /* dSdt at staggered nodes and d/dt(dS/dxi) at internal basic nodes */
for(i=ilo_s+1; idtsurfdt already contains contribution of dTsurf/dT */
/* By chain rule, just need dT/dt */
- A->dtsurfdt *= arr_dSdt_s[0] * arr_temp_s[0] / arr_cp_s[0];
+ A->dtsurfdt *= dSdt_s0 * arr_temp_s[0] / arr_cp_s[0];
/* add effect of gradient to above 0.5*d/dt (dS/dxi)? */
ierr = DMDAVecRestoreArrayRead(da_s,M->xi_s,&arr_xi_s);CHKERRQ(ierr);
@@ -92,7 +96,7 @@ PetscErrorCode RHSFunction(TS ts,PetscReal t,Vec sol_in,Vec rhs,void *ptr)
/* apply cmb boundary condition to rhs */
ierr = set_cmb_entropy_gradient_update( E, rhs_b );CHKERRQ(ierr);
- /* must be here since must be after dS/dt computation
+ /* must be here since must be after dS/dt computation
only relevant for 2 phases. Perhaps need to tidy up similar
functionality, like output of rheological front, etc. */
if( P->n_phases == 2 ){
@@ -106,7 +110,7 @@ PetscErrorCode RHSFunction(TS ts,PetscReal t,Vec sol_in,Vec rhs,void *ptr)
ierr = VecCopy(rhs_b,subVecs[E->solutionSlots[SPIDER_SOLUTION_FIELD_DSDXI_B]]);CHKERRQ(ierr);
/* S0 */
- ierr = VecSetValue(subVecs[E->solutionSlots[SPIDER_SOLUTION_FIELD_S0]],0,arr_dSdt_s[0],INSERT_VALUES);CHKERRQ(ierr);
+ ierr = VecSetValue(subVecs[E->solutionSlots[SPIDER_SOLUTION_FIELD_S0]],0,dSdt_s0,INSERT_VALUES);CHKERRQ(ierr);
/* volatiles and reactions */
@@ -138,4 +142,4 @@ PetscErrorCode RHSFunction(TS ts,PetscReal t,Vec sol_in,Vec rhs,void *ptr)
ierr = VecDestroy(&rhs_b);CHKERRQ(ierr);
PetscFunctionReturn(0);
-}
+}
\ No newline at end of file
diff --git a/tests/tests.yml b/tests/tests.yml
index 91e5ee93..a9fea195 100644
--- a/tests/tests.yml
+++ b/tests/tests.yml
@@ -19,8 +19,8 @@ tests:
-
name: plot_test
commands:
- - HERE/../spider -options_file HERE/opts/blackbody50.opts -nstepsmacro 2
- - HERE/../py/plot_spider_lite.py
+ - HERE/../spider -options_file HERE/opts/blackbody50.opts -nstepsmacro 15
+ - HERE/../py/plot_spider_lite.py --times 0,100,200,300,400,500,600,700,800,900,1000,1100,1200,1300,1400,1500
type: exit_code
-
name: external_mesh_roundtrip
diff --git a/tools/get_petsc.sh b/tools/get_petsc.sh
new file mode 100755
index 00000000..fd9adffd
--- /dev/null
+++ b/tools/get_petsc.sh
@@ -0,0 +1,433 @@
+#!/usr/bin/env bash
+# =============================================================================
+# get_petsc.sh — Download, configure, and compile PETSc for SPIDER
+# =============================================================================
+#
+# Downloads PETSc 3.19.0 from OSF and builds it with sundials2 support.
+# SPIDER is a pure C code, so C++ and Fortran compilers are disabled.
+#
+# This script is intended to live inside the SPIDER repository:
+#
+# SPIDER/
+# ├── tools/
+# │ └── get_petsc.sh
+# ├── Makefile
+# └── ...
+#
+# Default install locations:
+# - Standalone clone: /SPIDER/petsc/
+# - Nested clone: /PROTEUS/petsc/
+#
+# An optional first argument may be supplied to choose a different PETSc path.
+# The argument is interpreted as the final PETSc directory itself:
+#
+# ./tools/get_petsc.sh
+# ./tools/get_petsc.sh /path/to/petsc
+#
+# Logs:
+# Full build logs are written to:
+# /logs/get_petsc-YYYYmmdd-HHMMSS.log
+#
+# Supported platforms:
+# - macOS 10.15 (Catalina) and later, Intel and Apple Silicon
+# - Linux (Ubuntu, Debian, Fedora/RHEL, HPC clusters)
+#
+# Prerequisites:
+# macOS: brew install gcc open-mpi
+# xcode-select --install
+# Ubuntu: sudo apt install build-essential libopenmpi-dev unzip curl
+# Fedora: sudo dnf install gcc openmpi openmpi-devel lapack lapack-devel \
+# lapack-static f2c f2c-libs unzip curl
+#
+# Environment after completion:
+# PETSC_DIR =
+# PETSC_ARCH = arch-{linux,darwin}-c-opt
+#
+# =============================================================================
+
+set -euo pipefail
+
+# -----------------------------------------------------------------------------
+# Console stream setup
+# -----------------------------------------------------------------------------
+if tty -s 2>/dev/null && [[ -w /dev/tty ]]; then
+ exec 3>/dev/tty
+ exec 4>/dev/tty
+else
+ exec 3>&1
+ exec 4>&2
+fi
+
+console() {
+ printf '%s\n' "$*" >&3
+}
+
+announce() {
+ printf '%s\n' "$*" >&3
+ printf '%s\n' "$*"
+}
+
+# -----------------------------------------------------------------------------
+# Portable path helpers
+# -----------------------------------------------------------------------------
+portable_realpath() {
+ if command -v realpath >/dev/null 2>&1; then
+ realpath "$1"
+ else
+ python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+ fi
+}
+
+# -----------------------------------------------------------------------------
+# Repository layout helper
+# -----------------------------------------------------------------------------
+default_petsc_path_for_repo() {
+ local repo_root="$1"
+ local parent_root
+
+ parent_root="$(dirname "$repo_root")"
+
+ # If this checkout lives at PROTEUS/SPIDER, prefer PROTEUS/petsc so that
+ # PETSc is shared with the wider PROTEUS tree.
+ if [[ "$(basename "$repo_root")" == "SPIDER" ]] && [[ "$(basename "$parent_root")" == "PROTEUS" ]]; then
+ printf '%s/petsc\n' "$parent_root"
+ else
+ printf '%s/petsc\n' "$repo_root"
+ fi
+}
+
+# -----------------------------------------------------------------------------
+# Safety guard for destructive operations
+# -----------------------------------------------------------------------------
+safe_to_remove_dir() {
+ local target="$1"
+ local resolved
+
+ [[ -n "$target" ]] || return 1
+ resolved="$(portable_realpath "$target")"
+
+ case "$resolved" in
+ /|/home|/root|"${HOME}"|.)
+ return 1
+ ;;
+ esac
+
+ # This installer should only ever remove a PETSc directory
+ [[ "$(basename "$resolved")" == "petsc" ]] || return 1
+
+ return 0
+}
+
+# -----------------------------------------------------------------------------
+# Error handling: report which step failed on any non-zero exit
+# -----------------------------------------------------------------------------
+current_step="initialising"
+url="https://osf.io/download/p5vxq/"
+logfile=""
+
+on_error() {
+ local rc=$?
+
+ console ""
+ console "========================================"
+ console " ERROR: PETSc installation failed"
+ console ""
+ console " Step that failed: $current_step"
+ console " Command: $BASH_COMMAND"
+ console " Exit code: $rc"
+ if [[ -n "${logfile:-}" ]]; then
+ console " Log file: $logfile"
+ fi
+ console ""
+ console " Troubleshooting:"
+
+ case "$current_step" in
+ *"required tools"*)
+ console " - Install the missing prerequisite and re-run the script"
+ console " - On minimal HPC/login nodes, load any needed modules first"
+ ;;
+ *"Preparing PETSc directory"*)
+ console " - The target directory may have been rejected by the safety guard"
+ console " - Check that the install path is correct and ends in 'petsc'"
+ console " - Refused paths include '/', '$HOME', '.', and very short paths"
+ ;;
+ *"Download"*)
+ console " - Check your internet connection"
+ console " - Verify the OSF URL is accessible: $url"
+ console " - Try downloading manually: curl -fLsS \"$url\" -o petsc.zip"
+ ;;
+ *"Decompress"*)
+ console " - The downloaded archive may be corrupted"
+ console " - Delete the PETSc directory and re-run this script"
+ ;;
+ *"Configure"*)
+ console " - Check PETSc configure output in the log file"
+ console " - On macOS: ensure Xcode CLI tools are installed (xcode-select --install)"
+ console " - Verify MPI is installed (mpicc --version)"
+ ;;
+ *"Build"*)
+ console " - Check PETSc build output in the log file"
+ console " - Ensure your C compiler is working (mpicc --version)"
+ console " - On macOS: verify SDKROOT is set (xcrun --show-sdk-path)"
+ ;;
+ *"Test"*)
+ console " - PETSc built but tests failed"
+ console " - Check the test output in the log file"
+ console " - On macOS: check /etc/hosts for localhost entry"
+ ;;
+ *)
+ console " - Review the log file for the failing command"
+ ;;
+ esac
+
+ console "========================================"
+}
+trap on_error ERR
+
+# -----------------------------------------------------------------------------
+# 1. Detect platform and set PETSC_ARCH
+# -----------------------------------------------------------------------------
+current_step="Detecting platform"
+
+if [[ "$OSTYPE" == "linux"* ]]; then
+ export PETSC_ARCH=arch-linux-c-opt
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+ export PETSC_ARCH=arch-darwin-c-opt
+else
+ echo "ERROR: Unsupported OS type '$OSTYPE'. Only Linux and macOS are supported." >&2
+ exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# 2. Verify required tools are available
+# -----------------------------------------------------------------------------
+current_step="Verifying required tools"
+
+for cmd in curl unzip make; do
+ if ! command -v "$cmd" >/dev/null 2>&1; then
+ echo "ERROR: Required command '$cmd' not found in PATH." >&2
+ echo "Install it first and re-run this script." >&2
+ exit 1
+ fi
+done
+
+# realpath is optional, but python3 is required as the fallback
+if ! command -v realpath >/dev/null 2>&1 && ! command -v python3 >/dev/null 2>&1; then
+ echo "ERROR: Neither 'realpath' nor 'python3' was found in PATH." >&2
+ echo "Install one of them so the script can resolve paths correctly." >&2
+ exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# 3. Determine SPIDER repo root and target PETSc directory
+# -----------------------------------------------------------------------------
+current_step="Setting up working directory"
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(dirname "$script_dir")"
+
+# Optional argument is the final PETSc directory itself.
+if [[ $# -ge 1 ]]; then
+ mkdir -p "$1"
+ workpath="$(portable_realpath "$1")"
+else
+ workpath="$(default_petsc_path_for_repo "$repo_root")"
+fi
+
+export PETSC_DIR="$workpath"
+
+# -----------------------------------------------------------------------------
+# 4. Set up logging
+# -----------------------------------------------------------------------------
+current_step="Setting up logging"
+
+log_dir="$(dirname "$workpath")/logs"
+mkdir -p "$log_dir"
+timestamp="$(date +%Y%m%d-%H%M%S)"
+logfile="$log_dir/get_petsc-$timestamp.log"
+
+exec >>"$logfile" 2>&1
+
+announce "Logging PETSc build to: $logfile"
+announce "PETSC_DIR = $PETSC_DIR"
+announce "PETSC_ARCH = $PETSC_ARCH"
+
+# -----------------------------------------------------------------------------
+# 5. Prepare PETSc directory
+# -----------------------------------------------------------------------------
+current_step="Preparing PETSc directory"
+
+if [[ -e "$workpath" ]]; then
+ if ! safe_to_remove_dir "$workpath"; then
+ echo "ERROR: Refusing to remove unsafe path: $workpath" >&2
+ exit 1
+ fi
+ rm -rf "$workpath"
+fi
+mkdir -p "$workpath"
+
+# -----------------------------------------------------------------------------
+# 6. Download PETSc 3.19.0 from OSF
+# -----------------------------------------------------------------------------
+current_step="Downloading PETSc archive from OSF"
+
+zipfile="$workpath/petsc.zip"
+announce ""
+announce "Downloading PETSc archive from OSF..."
+announce " $url -> $zipfile"
+curl -fLsS "$url" -o "$zipfile"
+
+current_step="Decompressing PETSc archive"
+announce "Decompressing..."
+unzip -qq "$zipfile" -d "$workpath"
+rm -f "$zipfile"
+
+# -----------------------------------------------------------------------------
+# 7. Determine platform-specific configure flags
+# -----------------------------------------------------------------------------
+current_step="Determining platform-specific flags"
+
+mpi_flag="--download-mpich"
+blas_flag="--download-f2cblaslapack"
+ldflags=""
+cflags=""
+
+# ---- Linux special cases ----------------------------------------------------
+if [[ "$OSTYPE" == "linux"* ]]; then
+ host="$(hostname -f 2>/dev/null || hostname)"
+
+ if [[ "$host" == *"snellius"* ]]; then
+ announce " Detected Snellius cluster — using system MPI"
+ mpi_flag=""
+ elif [[ "$host" == *"hpc.rug.nl" ]]; then
+ announce " Detected Habrok cluster"
+ elif [[ -f "/etc/fedora-release" || -f "/etc/redhat-release" ]]; then
+ announce " Detected Fedora/RHEL"
+ if command -v mpicc >/dev/null 2>&1; then
+ announce " Found system MPI ($(command -v mpicc)) — skipping mpich download"
+ mpi_flag=""
+ else
+ announce " mpicc not in PATH — will download MPICH"
+ fi
+ blas_flag=""
+ cflags="-fPIC -Wno-error=format-security -Wno-lto-type-mismatch -Wno-stringop-overflow"
+ elif command -v mpicc >/dev/null 2>&1; then
+ announce " Found system MPI ($(command -v mpicc)) — skipping mpich download"
+ mpi_flag=""
+ fi
+fi
+
+# ---- macOS ------------------------------------------------------------------
+if [[ "$OSTYPE" == "darwin"* ]]; then
+ if ! command -v xcrun >/dev/null 2>&1; then
+ echo "ERROR: xcrun not found. Install Xcode Command Line Tools:" >&2
+ echo " xcode-select --install" >&2
+ exit 1
+ fi
+
+ export SDKROOT
+ SDKROOT="$(xcrun --show-sdk-path)"
+ announce " SDKROOT = $SDKROOT"
+
+ if command -v mpicc >/dev/null 2>&1; then
+ announce " Found system MPI ($(command -v mpicc)) — skipping mpich download"
+ mpi_flag=""
+ else
+ announce "WARNING: mpicc not found. Install MPI via Homebrew:"
+ announce " brew install open-mpi"
+ announce "Falling back to --download-mpich"
+ fi
+
+ # macOS provides Accelerate framework with BLAS/LAPACK
+ blas_flag=""
+
+ if [[ "$(uname -m)" == "arm64" ]]; then
+ default_brew_prefix="/opt/homebrew"
+ else
+ default_brew_prefix="/usr/local"
+ fi
+ brew_prefix="$(brew --prefix 2>/dev/null || echo "$default_brew_prefix")"
+ ldflags="-L${brew_prefix}/lib -Wl,-w"
+fi
+
+if [[ -z "$mpi_flag" ]] && ! command -v mpirun >/dev/null 2>&1; then
+ echo "ERROR: MPI not found and --download-mpich was disabled." >&2
+ echo "Install MPI first (e.g. 'brew install open-mpi' or 'apt install libopenmpi-dev')." >&2
+ exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# 8. Configure PETSc
+# -----------------------------------------------------------------------------
+current_step="Configuring PETSc (./configure)"
+
+announce ""
+announce "Configuring PETSc..."
+announce " MPI: ${mpi_flag:-system}"
+announce " BLAS: ${blas_flag:-system}"
+announce " CFLAGS: ${cflags:-}"
+announce " LDFLAGS: ${ldflags:-}"
+
+olddir="$(pwd)"
+cd "$workpath"
+
+configure_args=(
+ --with-debugging=0
+ --with-fc=0
+ --with-cxx=0
+ --download-sundials2
+ "--COPTFLAGS=-g -O3"
+)
+
+if [[ -n "$mpi_flag" ]]; then
+ configure_args+=("$mpi_flag")
+fi
+if [[ -n "$blas_flag" ]]; then
+ configure_args+=("$blas_flag")
+fi
+if [[ -n "$cflags" ]]; then
+ configure_args+=("CFLAGS=$cflags")
+fi
+if [[ -n "$ldflags" ]]; then
+ configure_args+=("LDFLAGS=$ldflags")
+fi
+
+./configure "${configure_args[@]}"
+
+# -----------------------------------------------------------------------------
+# 9. Build PETSc
+# -----------------------------------------------------------------------------
+current_step="Building PETSc (make all)"
+
+ncpu=4
+announce ""
+announce "Building PETSc with $ncpu CPUs..."
+make PETSC_DIR="$PETSC_DIR" PETSC_ARCH="$PETSC_ARCH" -j "$ncpu" all
+
+# -----------------------------------------------------------------------------
+# 10. Run PETSc self-tests
+# -----------------------------------------------------------------------------
+current_step="Testing PETSc (make check)"
+
+announce ""
+announce "Testing PETSc..."
+make PETSC_DIR="$PETSC_DIR" PETSC_ARCH="$PETSC_ARCH" check
+
+# -----------------------------------------------------------------------------
+# 11. Done
+# -----------------------------------------------------------------------------
+cd "$olddir"
+
+announce ""
+announce "========================================"
+announce " PETSc installation complete."
+announce ""
+announce " PETSC_DIR = $PETSC_DIR"
+announce " PETSC_ARCH = $PETSC_ARCH"
+announce " Log file: $logfile"
+announce ""
+announce " Add these to your shell config if you"
+announce " need to rebuild SPIDER manually:"
+announce " export PETSC_DIR=$PETSC_DIR"
+announce " export PETSC_ARCH=$PETSC_ARCH"
+announce "========================================"
\ No newline at end of file
diff --git a/tools/get_spider.sh b/tools/get_spider.sh
new file mode 100755
index 00000000..c4a0f5f6
--- /dev/null
+++ b/tools/get_spider.sh
@@ -0,0 +1,358 @@
+#!/usr/bin/env bash
+# =============================================================================
+# get_spider.sh — Build SPIDER from an already-cloned checkout
+# =============================================================================
+#
+# Builds the SPIDER interior evolution model against a local PETSc
+# installation. PETSc is installed automatically first if it is missing.
+#
+# SPIDER is a pure C code that uses PETSc for numerics and sundials2 for
+# ODE integration. The Makefile includes PETSc's build rules, so PETSC_DIR
+# and PETSC_ARCH must be set correctly.
+#
+# Supported platforms:
+# - macOS 10.15 (Catalina) and later, Intel and Apple Silicon
+# - Linux (Ubuntu, Debian, Fedora/RHEL, HPC clusters)
+#
+# Supported repository layouts:
+# - Standalone clone: /SPIDER/tools/get_spider.sh
+# -> PETSc defaults to /SPIDER/petsc/
+# - Nested clone: /PROTEUS/SPIDER/tools/get_spider.sh
+# -> PETSc defaults to /PROTEUS/petsc/
+#
+# Prerequisites:
+# - A cloned SPIDER repository (this script builds the current checkout)
+# - C compiler accessible via MPI wrapper (mpicc), or PETSc's MPICH download
+# - make
+#
+# Usage:
+# ./tools/get_spider.sh # build the current checkout in place
+# ./tools/get_spider.sh /path/to/SPIDER # build a different cloned checkout
+#
+# Logs:
+# Full build logs are written to:
+# /logs/get_spider-YYYYmmdd-HHMMSS.log
+#
+# The script is suitable for standalone SPIDER installs, and still behaves
+# nicely inside a PROTEUS/SPIDER checkout by installing PETSc in PROTEUS/petsc.
+#
+# =============================================================================
+
+set -euo pipefail
+
+# -----------------------------------------------------------------------------
+# Console stream setup
+# -----------------------------------------------------------------------------
+if tty -s 2>/dev/null && [[ -w /dev/tty ]]; then
+ exec 3>/dev/tty
+ exec 4>/dev/tty
+else
+ exec 3>&1
+ exec 4>&2
+fi
+
+console() {
+ printf '%s\n' "$*" >&3
+}
+
+announce() {
+ printf '%s\n' "$*" >&3
+ printf '%s\n' "$*"
+}
+
+# -----------------------------------------------------------------------------
+# Portable path helpers
+# -----------------------------------------------------------------------------
+portable_realpath() {
+ if command -v realpath >/dev/null 2>&1; then
+ realpath "$1"
+ else
+ python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$1"
+ fi
+}
+
+portable_abspath() {
+ if command -v realpath >/dev/null 2>&1; then
+ realpath -m "$1" 2>/dev/null || python3 -c "import os,sys; print(os.path.abspath(sys.argv[1]))" "$1"
+ else
+ python3 -c "import os,sys; print(os.path.abspath(sys.argv[1]))" "$1"
+ fi
+}
+
+# -----------------------------------------------------------------------------
+# Repository layout helpers
+# -----------------------------------------------------------------------------
+default_petsc_path_for_repo() {
+ local repo_root="$1"
+ local parent_root
+
+ parent_root="$(dirname "$repo_root")"
+
+ # If this checkout lives at PROTEUS/SPIDER, prefer PROTEUS/petsc so that
+ # PETSc is shared with the wider PROTEUS tree.
+ if [[ "$(basename "$repo_root")" == "SPIDER" ]] && [[ "$(basename "$parent_root")" == "PROTEUS" ]]; then
+ printf '%s/petsc\n' "$parent_root"
+ else
+ printf '%s/petsc\n' "$repo_root"
+ fi
+}
+
+petsc_built_ok() {
+ local petsc_dir="$1"
+ local petsc_arch="$2"
+ local petsc_lib_dir petsc_conf_dir f
+
+ [[ -d "$petsc_dir" ]] || return 1
+
+ petsc_lib_dir="$petsc_dir/$petsc_arch/lib"
+ petsc_conf_dir="$petsc_dir/lib/petsc/conf"
+
+ for f in "$petsc_lib_dir"/libpetsc.*; do
+ [[ -f "$f" ]] || continue
+ [[ -f "$petsc_conf_dir/variables" ]] || return 1
+ [[ -f "$petsc_conf_dir/rules" ]] || return 1
+ return 0
+ done
+
+ return 1
+}
+
+# -----------------------------------------------------------------------------
+# Error handling: report which step failed on any non-zero exit
+# -----------------------------------------------------------------------------
+current_step="initialising"
+logfile=""
+
+on_error() {
+ local rc=$?
+
+ console ""
+ console "========================================"
+ console " ERROR: SPIDER installation failed"
+ console ""
+ console " Step that failed: $current_step"
+ console " Command: $BASH_COMMAND"
+ console " Exit code: $rc"
+ if [[ -n "${logfile:-}" ]]; then
+ console " Log file: $logfile"
+ fi
+ console ""
+ console " Troubleshooting:"
+
+ case "$current_step" in
+ *"required tools"*)
+ console " - Install the missing prerequisite and re-run the script"
+ console " - On minimal HPC/login nodes, load any needed modules first"
+ ;;
+ *"PETSc"*)
+ console " - Check the PETSc installer output above for errors"
+ console " - Re-run ./tools/get_petsc.sh manually if needed"
+ ;;
+ *"Building"*)
+ console " - Check the compiler output in the log file"
+ console " - Verify mpicc is working: mpicc --version"
+ console " - Verify PETSc is intact: ls \$PETSC_DIR/\$PETSC_ARCH/lib/libpetsc.*"
+ console " - On macOS: ensure SDKROOT is set (xcrun --show-sdk-path)"
+ ;;
+ *"Verif"*)
+ console " - The build completed without make errors but no binary was produced"
+ console " - This usually indicates a linker failure that was suppressed"
+ console " - Try rebuilding with verbose output: make V=1"
+ ;;
+ *)
+ console " - Review the log file for the failing command"
+ ;;
+ esac
+
+ console ""
+ console " PETSc environment used:"
+ console " PETSC_DIR = ${PETSC_DIR:-}"
+ console " PETSC_ARCH = ${PETSC_ARCH:-}"
+ console "========================================"
+}
+trap on_error ERR
+
+# -----------------------------------------------------------------------------
+# 1. Detect platform and set PETSC_ARCH
+# -----------------------------------------------------------------------------
+current_step="Detecting platform"
+
+if [[ "$OSTYPE" == linux* ]]; then
+ PETSC_ARCH=arch-linux-c-opt
+elif [[ "$OSTYPE" == darwin* ]]; then
+ PETSC_ARCH=arch-darwin-c-opt
+else
+ echo "ERROR: Unsupported OS type '$OSTYPE'. Only Linux and macOS are supported." >&2
+ exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# 2. Verify required tools are available
+# -----------------------------------------------------------------------------
+current_step="Verifying required tools"
+
+for cmd in make; do
+ if ! command -v "$cmd" >/dev/null 2>&1; then
+ echo "ERROR: Required command '$cmd' not found in PATH." >&2
+ exit 1
+ fi
+done
+
+# portable_abspath / portable_realpath need either realpath or python3
+if ! command -v realpath >/dev/null 2>&1 && ! command -v python3 >/dev/null 2>&1; then
+ echo "ERROR: Neither 'realpath' nor 'python3' was found in PATH." >&2
+ echo "Install one of them so the script can resolve paths correctly." >&2
+ exit 1
+fi
+
+# -----------------------------------------------------------------------------
+# 3. Locate SPIDER checkout to build
+# -----------------------------------------------------------------------------
+current_step="Locating SPIDER checkout"
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+default_repo_root="$(dirname "$script_dir")"
+
+if [[ -n "${1:-}" ]]; then
+ workpath="$(portable_abspath "$1")"
+else
+ workpath="$default_repo_root"
+fi
+
+if [[ ! -d "$workpath" ]]; then
+ echo "ERROR: SPIDER directory not found at $workpath." >&2
+ exit 1
+fi
+
+if [[ ! -f "$workpath/Makefile" ]]; then
+ echo "ERROR: No Makefile found in $workpath." >&2
+ echo "Expected an already-cloned SPIDER checkout." >&2
+ exit 1
+fi
+
+if [[ ! -x "$workpath/tools/get_petsc.sh" ]]; then
+ echo "ERROR: Could not find executable PETSc installer at $workpath/tools/get_petsc.sh." >&2
+ echo "Ensure this script lives inside the SPIDER checkout." >&2
+ exit 1
+fi
+
+workpath="$(portable_realpath "$workpath")"
+
+# -----------------------------------------------------------------------------
+# 4. Set up logging
+# -----------------------------------------------------------------------------
+current_step="Setting up logging"
+
+log_dir="$workpath/logs"
+mkdir -p "$log_dir"
+timestamp="$(date +%Y%m%d-%H%M%S)"
+logfile="$log_dir/get_spider-$timestamp.log"
+
+exec >>"$logfile" 2>&1
+
+announce "Logging SPIDER build to: $logfile"
+
+# -----------------------------------------------------------------------------
+# 5. Locate or bootstrap PETSc installation
+# -----------------------------------------------------------------------------
+current_step="Validating PETSc installation"
+
+if [[ -n "${PETSC_DIR:-}" ]]; then
+ petsc_path="$PETSC_DIR"
+else
+ petsc_path="$(default_petsc_path_for_repo "$workpath")"
+fi
+
+if ! petsc_built_ok "$petsc_path" "$PETSC_ARCH"; then
+ current_step="Installing PETSc via tools/get_petsc.sh"
+ announce "PETSc not found (or incomplete) at $petsc_path"
+ announce "Bootstrapping PETSc first..."
+ announce "The PETSc installer will create its own log file."
+ "$workpath/tools/get_petsc.sh" "$petsc_path"
+ current_step="Validating PETSc installation"
+fi
+
+if ! petsc_built_ok "$petsc_path" "$PETSC_ARCH"; then
+ echo "ERROR: PETSc library/configuration files not found after installation." >&2
+ echo "Checked: $petsc_path" >&2
+ exit 1
+fi
+
+export PETSC_DIR="$(portable_realpath "$petsc_path")"
+export PETSC_ARCH
+
+announce "PETSC_DIR = $PETSC_DIR"
+announce "PETSC_ARCH = $PETSC_ARCH"
+
+# -----------------------------------------------------------------------------
+# 6. macOS-specific environment setup
+# -----------------------------------------------------------------------------
+if [[ "$OSTYPE" == darwin* ]]; then
+ if command -v xcrun >/dev/null 2>&1; then
+ export SDKROOT
+ SDKROOT="$(xcrun --show-sdk-path)"
+ announce "SDKROOT = $SDKROOT"
+ fi
+fi
+
+# -----------------------------------------------------------------------------
+# 7. Verify build tools are available
+# -----------------------------------------------------------------------------
+current_step="Verifying build tools"
+
+if ! command -v mpicc >/dev/null 2>&1; then
+ announce "WARNING: mpicc not found in PATH."
+ announce " This is fine if PETSc was built with downloaded MPICH and the"
+ announce " wrapper is available through PETSc's build rules during make."
+fi
+
+# -----------------------------------------------------------------------------
+# 8. Build SPIDER
+# -----------------------------------------------------------------------------
+current_step="Building SPIDER (make)"
+
+if command -v nproc >/dev/null 2>&1; then
+ njobs="$(nproc)"
+elif command -v sysctl >/dev/null 2>&1; then
+ njobs="$(sysctl -n hw.ncpu)"
+else
+ njobs=2
+fi
+
+announce ""
+announce "Building SPIDER in $workpath ($njobs parallel jobs)..."
+olddir="$(pwd)"
+cd "$workpath"
+
+make -j "$njobs"
+
+# -----------------------------------------------------------------------------
+# 9. Verify the build produced the SPIDER binary
+# -----------------------------------------------------------------------------
+current_step="Verifying SPIDER binary"
+
+if [[ ! -x "$workpath/spider" ]]; then
+ echo "ERROR: SPIDER binary not found after build." >&2
+ echo "Check the build output in the log file." >&2
+ cd "$olddir"
+ exit 1
+fi
+
+spider_version="$("$workpath/spider" --help 2>&1 | head -1 || true)"
+announce ""
+announce "Build successful: $spider_version"
+
+# -----------------------------------------------------------------------------
+# 10. Done
+# -----------------------------------------------------------------------------
+cd "$olddir"
+
+announce ""
+announce "========================================"
+announce " SPIDER installation complete."
+announce ""
+announce " Binary: $(portable_realpath "$workpath/spider")"
+announce " PETSC_DIR = $PETSC_DIR"
+announce " PETSC_ARCH = $PETSC_ARCH"
+announce " Log file: $logfile"
+announce "========================================"
\ No newline at end of file
+
+ 
+ 
+ 
+