Add installation scripts + update documentation with Zensical

.github/workflows/ci.yml

@@ -46,3 +46,19 @@ jobs:
       with:
         name: spider-sciath-test-dir
         path: test_dir
+
+  installer-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install Python requirements
+        run: pip install -r py/requirements.txt
+      - name: Run installer
+        run: ./tools/get_spider.sh
+      - name: Test with SciATH
+        run: |
+          cd tests && git clone https://github.com/sciath/sciath --depth=1 && cd -
+          export PYTHONPATH=$PYTHONPATH:$PWD/tests/sciath
+          mkdir -p test_dir && cd test_dir
+          python -m sciath -d -w pth.conf
+          python -m sciath -f -w pth.conf ../tests/tests.yml

.github/workflows/docs.yaml

@@ -5,25 +5,25 @@ on:
       - master
       - main
 permissions:
-  contents: write
+  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/checkout@v4
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/configure-pages@v5
+      - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - run: pip install zensical markdown-include pymdown-extensions mkdocstrings mkdocstrings-python mkdocs-material mkdocs-bibtex
+      - run: zensical build --clean 
+      - uses: actions/upload-pages-artifact@v4
         with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: ~/.cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material markdown-include pymdown-extensions mkdocstrings  mkdocstrings-python mkdocs-bibtex
-      - run: mkdocs gh-deploy --force
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -50,3 +50,9 @@ verification/
 *.lot
 *.synctex.gz
 *.toc
+
+# petsc directory 
+petsc*/
+
+# site 
+site/

README.md

@@ -1,12 +1,18 @@
 # SPIDER
 **Simulating Planetary Interior Dynamics with Extreme Rheology**
 
-![SPIDER Logo](notes/logo/spider.png)
-
-[![Build](https://github.com/djbower/spider/actions/workflows/ci.yml/badge.svg)](https://github.com/djbower/spider/actions)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5682523.svg)](https://doi.org/10.5281/zenodo.5682523)
-
-
+<p align="center">
+  <img src="docs/assets/spider.png" style="max-width:40%; height:auto;" alt="SPIDER logo">
+</p>
+
+<p align="center">
+  <a href="https://github.com/FormingWorlds/SPIDER/actions">
+    <img src="https://github.com/FormingWorlds/SPIDER/actions/workflows/ci.yml/badge.svg" alt="Build">
+  </a>
+  <a href="https://doi.org/10.5281/zenodo.5682523">
+    <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.5682523.svg" alt="DOI">
+  </a>
+</p>
 
 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.
 

docs/Explanations/abe1993.md

@@ -0,0 +1,98 @@
+---
+tags:
+  - phase separation
+  - magma ocean
+  - thermal evolution
+---
+
+# SPIDER: model overview
+
+Here you can find a detailed overview of the SPIDER formulation.
+
+!!! note 
+    This model overview is taken from the [notes](https://github.com/FormingWorlds/SPIDER/tree/main/notes/) and contains an extended description of the equations and derivations related to the SPIDER code. It is still **work in progress.** 
+
+Notes specific to derivations in [^cite-ABE93].
+
+## Phase Separation
+
+Under the assumption of no melting/solidification, melt-solid separation is treated as a mass-transfer process. Average density of mixture:
+
+$$\frac{1}{\rho} = \frac{1}{\rho_s}(1-\phi)+\frac{1}{\rho_m}\phi$$
+
+where $\phi$ is mass fraction of melt.
+
+The masses of solid and melt phases per unit volume are:
+
+$$\rho_s^\ast \equiv (1-\phi) \rho = \frac{\rho_s \rho_m (1-\phi)}{\rho_s \phi + \rho_m(1-\phi)}$$
+
+$$\rho_m^\ast \equiv \phi \rho = \frac{\rho_s \rho_m \phi}{\rho_s \phi + \rho_m(1-\phi)}$$
+
+Define the velocity of the local barycenter:
+
+$$v \equiv \phi v_m + (1-\phi) v_s$$
+
+And the vertical mass flux of melt relative to the barycenter:
+
+$$J_m \equiv \rho \phi (1-\phi)(v_m-v_s)$$
+
+The phase separation equation becomes:
+
+$$\frac{\partial \phi}{\partial t} + v \frac{\partial \phi}{\partial z} = \frac{\rho_m \rho_s}{\rho (\rho_s-\rho_m)} \frac{\partial v}{\partial z} = - \frac{1}{\rho} \frac{\partial J_m}{\partial z}$$
+
+## Time Scale
+
+Characteristic time scale $\tau$ of melt-solid separation for a partially molten layer of thickness $L$:
+
+$$\tau = \frac{\rho L}{2 J_m} \min (\phi_0, 1-\phi_0 )$$
+
+## Impact Stirring
+
+During planetary accretion, planetesimal impacts stirred the mantle. Assuming a roughly linear accretion rate:
+
+$$\frac{dm}{dt} \sim \frac{M_E}{\tau_{acc}}$$
+
+The impactor mass distribution is:
+
+$$\frac{dN}{dm} = {K_{max}\left(\frac{m}{M_{max}}\right)^{-q}}$$
+
+with $q=1.5$ and $M_{max}=0.1 M_E$.
+
+The depth-dependent impact stirring timescale is:
+
+$$\tau_{s}(d) = \frac{\tau_{acc}}{N_{s}(d)}$$
+
+where $N_{s}$ is the effective number of complete stirring events at depth $d$.
+
+## Thermal Evolution of a Magma Ocean
+
+The energy (enthalpy) balance equation:
+
+$$\frac{\partial H}{\partial t} = - \frac{1}{\rho}\nabla \cdot \vec{J_{tot}} + \Delta V_m|g|\vec{J_m} \cdot \hat{r} + q_{heat}$$
+
+The total heat flux is a combination of sensible and latent heat:
+
+$$J_{tot} = J_q + T\Delta S_m J_m$$
+
+The melt fraction can be approximated as:
+
+$$\phi(H) = \frac{H - H_{sol}}{T\Delta S_m(P)}$$
+
+for $H_{sol} < H < H_{liq}$.
+
+Key assumptions for single-component modeling:
+- Use a single component melting curve roughly corresponding to the 50% solidus
+- Entropy of melting adjusted to ensure bounds match realistic mantle
+- Use realistic heat capacity and density values for both phases
+- Chemical differentiation negligible (second order effect)
+- Thermal range of partially molten region (~200 K) small compared to mantle temperature difference (~2500 K)
+
+## Gravitational potential energy
+
+The gravitational potential energy per unit mass is:
+
+$$E_{\rm grav} = - \frac{G M(r)}{r} = - |g(r)|r$$
+
+Melting influences gravitational potential energy through its effect on $g(r)$. However, since $g(r)$ is an integrated quantity it is not sensitive to small changes in density distribution. We therefore neglect changes in $E_{\mathrm{grav}}$ for silicate melting in a magma ocean.
+
+[^cite-ABE93]: Yutaka Abe, *Thermal Evolution and Chemical Differentiation of the Terrestrial Magma Ocean*, Evolution of the Earth and Planets, 1993.

docs/Explanations/atmosphere.md

@@ -0,0 +1,150 @@
+---
+tags:
+  - volatiles
+  - outgassing
+  - atmospheric escape
+---
+
+# SPIDER: model overview
+
+Here you can find a detailed overview of the SPIDER formulation.
+
+!!! note 
+    This model overview is taken from the [notes](https://github.com/FormingWorlds/SPIDER/tree/main/notes/) and contains an extended description of the equations and derivations related to the SPIDER code. It is still **work in progress.** 
+
+## Volatile Mass Balance
+
+The mass balance of a given volatile in the interior [^cite-LMC13] is:
+
+$$X_v^s M^s + X_v^l M^l + X_v^g M^g + m_v^e + m_v^o + m_v^r = X_v^{\rm init} M^m$$
+
+where superscripts $s$, $l$, $g$, $e$, $o$, $t$ denote solid, liquid (melt), gas, escaped, ocean, and total. **Only solid, liquid, and atmosphere are physical reservoirs.**
+
+The partition coefficient relates volatile concentrations:
+
+$$k_v = \frac{X_v^s}{X_v}$$
+
+### Atmospheric mass
+
+The total atmospheric mass of $q$ species composes as:
+
+$$m_t^g = \frac{4 \pi R_p^2}{g} P_s$$
+
+where $R_p$ is planetary radius and $P_s$ is surface pressure.
+
+The mass of a given volatile species is:
+
+$$m_v^g = 4 \pi R_p^2 \left( \frac{\mu_v^g}{\bar{\mu}} \right) \frac{p_v}{g}$$
+
+Partial pressure follows a modified (power-law) Henry's law:
+
+$$p_v ( X_v ) = \left( \frac{X_v}{\alpha_v} \right)^{\beta_v}$$
+
+In SPIDER we use scaled mass (omitting the $4 \pi$ factor):
+
+$$X_v (k_v M^s + M^l) + \frac{R_p^2}{g} \left( \frac{\mu_v^g}{\bar{\mu}} \right) p_v + m_v^e + m_v^o + m_v^r = X_v^{\rm init} M^m$$
+
+We solve for volatile mass fraction in the liquid phase, from which we can compute volatile mass in solid and gas phases.
+
+## Non-dimensionalisation
+
+### Mass
+
+Masses are non-dimensionalised as:
+
+$$M = \rho_0 R_0^3 \hat{M}$$
+
+### Volatile Concentration
+
+Volatile concentration is expressed as scaled mass fraction:
+
+$$X_v = V_0 \hat{X}_v$$
+
+where $V_0=10^{-6}$ gives parts-per-million (ppm), $V_0=10^{-2}$ gives weight percent (wt%), and $V_0=1$ gives mass fraction.
+
+### Power Law Solubility
+
+Non-dimensional partial pressure:
+
+$$\hat{p}_v ( \hat{X}_v ) = \left( \frac{\hat{X}_v}{\hat{\alpha}_v} \right)^{\beta_v}$$
+
+where:
+
+$$\hat{\alpha}_v = \frac{\alpha_v^{{\rm ppm/Pa}^{1/\beta_v}}}{10^6} \frac{P_0^\frac{1}{\beta_v}}{V_0}$$
+
+## Sossi Solubility
+
+For H$_2$O [^cite-SF17]:
+
+$$X_v = A{f_{H_2O}}^\frac{1}{2}+B G f_{H_2O}$$
+
+where fugacities are constrained by oxygen buffer, and $A=534$ ppm/bar$^{0.5}$ and $B=723$ ppm/bar.
+
+## Initial Volatile Concentration
+
+For an initial condition, we prescribe the total volatile concentration and solve the mass balance to obtain initial partial pressure consistent with chemical equilibrium criteria.
+
+## Chemical Reactions
+
+Reactions transfer mass between volatile species. For example:
+
+$$[\rm{H}_2O]\leftrightarrow \frac{1}{2} [\rm{O}_2] + [\rm{H}_2]$$
+
+with equilibrium constant:
+
+$$K=\frac{p_{\rm H_2} f_{\rm O_2}^{1/2}}{p_{\rm H_2\rm O}}$$
+
+Mass is conserved through stoichiometry:
+
+$$m_{H_2O} = m_{O2} + m_{H_2}$$
+
+## Atmospheric Escape
+
+### Jeans escape
+
+$$\frac{d m_v^e}{dt} = \left( \frac{d m_{\rm v}^{\rm g}}{dt} \right) \mathcal{R} (1 + \lambda_s) \exp(-\lambda_s) + \frac{\Phi}{4 \pi}$$
+
+where Jeans parameter:
+
+$$\lambda_s = \frac{g R_p \mu_{\rm v}}{k_b T_s N_A}$$
+
+### Zahnle escape model
+
+For H$_2$ [^cite-ZGC19]:
+
+$$\phi_{H_2} \approx \Gamma \frac{(1 \times 10^{12}) f_{H_2} S}{\sqrt{1+0.006S^2}}$$
+
+where $S$ is non-dimensional and $\Gamma$ is a scaling constant.
+
+## Grey atmosphere model
+
+### Optical depth
+
+$$\tau^\ast = \frac{3 \kappa^\prime p(\tau^\ast)}{2g}$$
+
+### Effective emissivity
+
+Optical depths for each volatile are combined:
+
+$$\epsilon = \frac{2}{\sum_j \tau_j^\ast +2}$$
+
+### Atmosphere temperature structure
+
+Temperature as function of optical depth [^cite-AM85]:
+
+$$T(\tau^\ast) = \left( T_0^4 \frac{(\tau^\ast+1)}{2} +T_\infty^4 \right)^\frac{1}{4}$$
+
+where:
+
+$$T_0 = \left( \frac{F_{atm}}{\sigma} \right)^\frac{1}{4}$$
+
+### Stellar flux
+
+$$F_{sun} = \sigma T_{eqm}^4 = (1-\alpha) \frac{F_0^\prime}{D^2}$$
+
+where $\alpha$ is bolometric albedo, $F_0'$ is averaged solar constant, and $D$ is planet-star distance.
+
+[^cite-LMC13]: Lebrun, T.; Massol, H.; Chassefi\`ere, E.; Davaille, A.; Marcq, E.; Sarda, P.; Leblanc, F.; Brandeis, G., *Thermal evolution of an early magma ocean in interaction with the atmosphere*, J. Geophys. Res.-Planet., 2013.
+[^cite-SF17]: Laura Schaefer; Bruce Fegley, *Redox States of Initial Atmospheres Outgassed on Rocky Planets and Planetesimals*, Astrophys. J., 2017.
+[^cite-ZGC19]: Kevin J. Zahnle; Marko Gacesa; David C. Catling, *Strange messenger: A new history of hydrogen on Earth, as told by Xenon*, Geochim. Cosmochim. Acta, 2019.
+[^cite-AM85]: Abe, Yutaka; Matsui, Takafumi, *The formation of an impact-generated H2O atmosphere and its implications for the early thermal history of the Earth*, J. Geophys. Res. Solid Earth, 1985.