Update documentation with Zensical

.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
+      - 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
-      - run: mkdocs gh-deploy --force
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

README.md

@@ -2,20 +2,16 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Documentation Status](https://readthedocs.org/projects/aragog/badge/?version=latest)](https://aragog.readthedocs.io/en/latest/?badge=latest)
-[![Python package](https://github.com/ExPlanetology/aragog/actions/workflows/python-package.yml/badge.svg)](https://github.com/ExPlanetology/aragog/actions/workflows/python-package.yml)
-
-## Under development
-
-This code remains under active development, hence the interface is not stable and should not be relied upon.
+[![Documentation](https://github.com/FormingWorlds/aragog/actions/workflows/docs.yaml/badge.svg)](https://proteus-framework.org/aragog)
+[![Tests](https://github.com/FormingWorlds/aragog/actions/workflows/ci_tests.yml/badge.svg)](https://github.com/FormingWorlds/aragog/actions/workflows/ci_tests.yml)
 
 ## About
 
-Aragog is a Python package that computes the 1-D interior dynamics of rocky mantles that are solid, liquid, or mixed phase. It is mostly a pure Python version of the [SPIDER code](https://github.com/djbower/spider) originally written in C albeit with some differences. Note that the atmosphere module in the original SPIDER code is now supported by a separate and more comprehensive Python package Atmodeller (release forthcoming).
+Aragog is a Python package that computes the 1-D interior dynamics of rocky mantles that are solid, liquid, or mixed phase. It is mostly a pure Python version of the [SPIDER code](https://github.com/FormingWorlds/SPIDER) originally written in C albeit with some differences. Note that the atmosphere module in the original SPIDER code is now supported by a separate and more comprehensive Python package Atmodeller.
 
-Documentation: <https://aragog.readthedocs.io>
+Documentation: <https://proteus-framework.org/aragog>
 
-Source code: <https://github.com/ExPlanetology/aragog>
+Source code: <https://github.com/FormingWorlds/aragog>
 
 ## Citation
 
@@ -30,37 +26,67 @@ Open access versions of the publication are available:
 
 ## Installation
 
+> **Note:** The standard way of installing this version of Aragog is within the PROTEUS Framework, as described in the [PROTEUS installation guide](https://proteus-framework.org/PROTEUS/installation.html#9-install-submodules-as-editable).  
+
 ### Quick install
 
 The basic procedure is to install Aragog into a Python environment. For example, if you are using a Conda distribution to create and manage Python environments (e.g. [Anaconda](https://www.anaconda.com/download)), create a new environment noting that Aragog requires Python >= 3.10. Once created, make sure to activate the environment. To achieve this, terminal commands are given below, but you can also use the Anaconda Navigator (or similar GUI) to create and activate environments:
 
-    conda create -n aragog python
-    conda activate aragog
+```sh
+conda create -n aragog python
+conda activate aragog
+```
 
 Alternatively, you can create and activate a [virtual environment](https://docs.python.org/3/library/venv.html).
 
 Finally, install Aragog into the activated environment:
 
-	pip install aragog
+```sh
+pip install fwl-aragog
+```
 
 ### Developer install
 
-> - See this [guide](https://gist.github.com/djbower/c66474000029730ac9f8b73b96071db3) to develop Aragog using [VS Code](https://code.visualstudio.com) and [Poetry](https://python-poetry.org).
-> - See this [guide](https://gist.github.com/djbower/c82b4a70a3c3c74ad26dc572edefdd34) to develop Aragog if you are a Windows or Spyder user.
-
 Navigate to a location on your computer and obtain the source code using git:
 
-    git clone git@github.com:ExPlanetology/aragog.git aragog
-    cd aragog
+```sh
+git clone git@github.com:FormingWorlds/aragog.git aragog
+cd aragog
+```
+
+Install Aragog into the environment using either: (a) [Poetry](https://python-poetry.org), or (b) [pip](https://pip.pypa.io/en/stable/getting-started/). 
+
+There are some subtle differences between Poetry and pip, but in general Aragog is configured to be interoperable for most common operations (e.g. see this [Gist](https://gist.github.com/djbower/e9538e7eb5ed3deaf3c4de9dea41ebcd)). 
+
+(a) Poetry option, which requires that [Poetry](https://python-poetry.org) is installed:
+
+```sh
+poetry install --with docs
+```
+
+(b) pip option, where the ``-e`` option is for an [editable install](https://setuptools.pypa.io/en/latest/userguide/development_mode.html):
+
+```sh 
+pip install -e ".[docs]"
+```
+
+If desired, you will need to manually install the dependencies for the tests, which are automatically installed by Poetry but not by pip. See the additional dependencies to install in `pyproject.toml`.
+
+More comprehensive set up guides are available here:
 
-Install Aragog into the environment using either (a) [Poetry](https://python-poetry.org) or (b) [pip](https://pip.pypa.io/en/stable/getting-started/). There are some subtle differences between Poetry and pip, but in general Aragog is configured to be interoperable for most common operations (e.g. see this [Gist](https://gist.github.com/djbower/e9538e7eb5ed3deaf3c4de9dea41ebcd)).
+- [VS Code and Poetry guide](https://gist.github.com/djbower/c66474000029730ac9f8b73b96071db3)
+- [Windows and Spyder guide](https://gist.github.com/djbower/c82b4a70a3c3c74ad26dc572edefdd34)
 
-- (a) Poetry option, which requires that [Poetry](https://python-poetry.org) is installed:
+### Download data from the OSF repository
 
-		poetry install --all-extras
+Aragog requires lookup table data storing thermophysics properties of the liquid and solid matter. These data are stored in an [OSF repository](https://osf.io/phsxf/) and on a [Zenodo record](https://zenodo.org/records/15728072). You can download it with the command:
 
-- (b) pip option, where the `-e` option is for an [editable install](https://setuptools.pypa.io/en/latest/userguide/development_mode.html):
+```sh
+aragog download all
+```
 
-		pip install -e ".[docs]"
+The command `aragog env` will give you the path where the data have been downloaded. If you want to set up your own path, setup the environment variable `FWL_DATA` before running the download command:
 
-	If desired, you will need to manually install the dependencies for the tests, which are automatically installed by Poetry but not by `pip`. See the additional dependencies to install in `pyproject.toml`.
+```sh
+export FWL_DATA=your_absolute_path/
+```

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/aragog/issues) | Bug reports, specific feature requests |
+| [proteus_dev@formingworlds.space](mailto:proteus_dev@formingworlds.space) | General enquiries |

docs/Explanations/enthalpy_balance.md

@@ -0,0 +1,110 @@
+# Aragog: model overview
+
+## Enthalpy balance
+
+We start with the enthalpy balance in integral form:
+
+$$\int_V \rho c_p \left.\frac{\partial T}{\partial t}\right|_\xi \, dV = -\oint_S \mathbf{q} \cdot \mathbf{n} \, dS + \int_V \Phi \, dV \tag{1}$$
+
+where $T$ is the effective temperature of the melting medium, assuming thermal equilibrium between solid and melt phases. Mass coordinates $\xi$ are used (see Sec. 1.3), but integration is performed over a physical domain of volume $V$ and surface boundary $S$. Any control volume $V$ is assumed to coincide with a material volume that does not evolve in time — the mass of each volume is constant and there is no mass flux at the interfaces.
+
+Spherical symmetry is assumed and only spatial variations along the radial direction are considered. In what follows, only the radial component of vector quantities is retained. The enthalpy balance, heat fluxes, and heat sources are implemented in Aragog in [`solver.py`](https://github.com/FormingWorlds/aragog/blob/main/aragog/solver.py).
+
+---
+
+## 1.1 Heat fluxes
+
+The total heat flux is defined as the sum of the conductive ($q_{cd}$), convective ($q_{cv}$), convective mixing ($q_{cm}$), and gravitational separation ($q_{gm}$) contributions:
+
+$$q_{tot} = q_{cd} + q_{cv} + q_{cm} + q_{gm} \tag{2}$$
+
+The **conductive flux** is:
+
+$$q_{cd} = -\lambda \frac{\partial T}{\partial r} \tag{3}$$
+
+The **convective flux** is modelled as:
+
+$$q_{cv} = -\rho c_p \kappa_h \left(\frac{\partial T}{\partial r} - \left.\frac{\partial T}{\partial r}\right|_S\right) \tag{4}$$
+
+where the adiabatic temperature gradient (temperature gradient at constant entropy $S$) is:
+
+$$\left.\frac{\partial T}{\partial r}\right|_S = -\frac{g \alpha T}{c_p} \tag{5}$$
+
+The **convective mixing flux** and the **gravitational separation flux** are enthalpy fluxes associated with corresponding mass fluxes:
+
+$$q_{cm} + q_{gm} = \Delta h \left(j_{cm} + j_{gm}\right) \tag{6}$$
+
+where $j_{cm}$ and $j_{gm}$ are mass fluxes associated with the melt (the corresponding fluxes for the solid are $-j_{cm}$ and $-j_{gm}$, such that the sum of species mass fluxes is zero).
+
+The **mass diffusion flux of melt** is:
+
+$$j_{cm} = -\rho \kappa_h \frac{\partial \phi}{\partial r} \tag{7}$$
+
+where $\phi$ is the mass fraction of melt (defined in Sec. 2.1). The mass diffusivity is assumed equal to the eddy diffusivity $\kappa_h$.
+
+The **melt mass flux associated with gravitational separation** is:
+
+$$j_{gm} = \rho \phi (1 - \phi) v_{rel} \tag{8}$$
+
+where $v_{rel}$ is the relative velocity between melt and solid:
+
+$$v_{rel} = \frac{(\rho_m - \rho_s) g K}{\eta_m} \tag{9}$$
+
+Both mass fluxes $j_{cm}$ and $j_{gm}$ are zero outside the mixed-phase region.
+
+---
+
+## 1.2 Heat sources
+
+The volumetric heat sources considered are:
+
+$$\Phi = \Phi_{tidal} + \Phi_{radio} + \Phi_{vol} \tag{10}$$
+
+associated with tidal heating, radiogenic heating, and volumetric dilatation or compression, respectively.
+
+The **volumetric dilatation/compression** source is expressed as a function of the mass fluxes:
+
+$$\Phi_{vol} = \rho g \left(\frac{1}{\rho_m} - \frac{1}{\rho_s}\right)(j_{cm} + j_{gm}) \tag{11}$$
+
+The **radiogenic heating** is defined as:
+
+$$\Phi_{radio} = \sum_i \rho \phi_i \chi_i \exp\left(-\frac{t - t_0}{\tau^{1/2}_i}\right) \tag{12}$$
+
+where $\phi_i$, $\chi_i$, and $\tau^{1/2}_i$ are the power generation per unit mass, the mass fraction, and the half-life associated with radioisotope $i$, respectively. The radiogenic heating is time-dependent but spatially uniform.
+
+The **tidal heating** volume source must be provided by the user. It can be spatially dependent but is constant in time.
+
+---
+
+## 1.3 Mass coordinates
+
+Mass coordinates $\xi$ (in unit length) correspond to a change of variable from the spatial coordinate $r$, such that the mass contained in an element $\Delta\xi$ is constant regardless of depth.
+
+The transformation from spatial to mass coordinates is:
+
+$$\xi(r) = \left[3\int_{r_{cmb}}^{r} \frac{\rho^*(r')}{\rho^*_{planet}} r'^2 \, dr' + \xi_{cmb}^3\right]^{1/3} \tag{13}$$
+
+where $\rho^*_{planet}$ is the volume-averaged density of the planet and $\rho^*$ is the local mantle density. The mass coordinate at the core-mantle boundary (CMB) is defined as:
+
+$$\xi_{cmb} = \left(\frac{\rho^*_{core}}{\rho^*_{planet}}\right)^{1/3} r_{cmb} \tag{14}$$
+
+where $\rho^*_{core}$ is the volume-averaged density of the core. Using the volume-averaged planetary density as a scaling quantity ensures that the spatial coordinate and the mass coordinate coincide at the surface:
+
+$$\xi_{top} = r_{top} \tag{15}$$
+
+which equals the planetary radius. The reverse transformation from mass coordinates back to spatial coordinates is:
+
+$$r(\xi) = \left[3\int_{\xi_{cmb}}^{\xi} \frac{\rho^*_{planet}}{\rho^*(\xi')} \xi'^2 \, d\xi' + r_{cmb}^3\right]^{1/3} \tag{16}$$
+
+The spatial gradient of any quantity $\psi$ is computed according to:
+
+$$\frac{\partial \psi}{\partial r} = \frac{\rho^*(r)}{\rho^*_{planet}} \left(\frac{r}{\xi}\right)^2 \frac{\partial \psi}{\partial \xi} \tag{17}$$
+
+!!! note
+    If the spatial mesh is uniform, the mass coordinate mesh will generally not be uniform. The notation $\rho^*$ for density will be clarified in the [next section](thermodynamics.md).
+
+If this transformation is ignored and spatial coordinates are used directly, the convective derivative term in the enthalpy balance is neglected, i.e.:
+
+$$\left.\frac{\partial T}{\partial t}\right|_\xi \simeq \left.\frac{\partial T}{\partial t}\right|_r \tag{18}$$
+
+Mass coordinates are implemented in Aragog in [`mesh.py`](https://github.com/FormingWorlds/aragog/blob/main/aragog/mesh.py).