how to run ACCESS-ISSM configuration documentation

docs/models/access_models/access-issm.md

@@ -0,0 +1,66 @@
+!!! release
+    This is a Beta Release.
+    Any model configuration and related source code mentioned in this page might change before the full release.
+    Limited support is currently provided for this model. Its usage is only recommended for testing by experienced users and collaborators.
+
+# ACCESS‑ISSM
+
+![ACCESS‑ISSM model](/assets/model-config-logos/configurations-without-titles/access-issm.png){: .img-contain .white-background .round-edges .with-padding .intro-img loading="lazy"}
+
+The ACCESS Ice-Sheet and Sea-Level System Model (ACCESS‑ISSM) is a global ice‑sheet and ice‑shelf model based on the [ISSM](/models/model_components/ice-sheet) framework.  It supports standalone ice dynamics and optional coupling to ocean and atmospheric forcing.
+
+## Configurations 
+ACCESS-ISSM provides the following released configurations:
+
+- [Marine Ice-Sheet Model Intercomparison Project (MISMIP)](#mismip)
+
+### Marine Ice-Sheet Model Intercomparison Project (MISMIP) {: #mismip }
+The _MISMIP_ configuration reproduces the Marine Ice‑Sheet Model Intercomparison Project benchmark in ACCESS‑ISSM. It is intended for code regression tests, parameter experiments and numerical‑scheme development.
+
+### 1.1 Domain & Physics
+
+- **Geometry**: 800 km × 80 km Cartesian slab; flat bed at –1500 m; ocean at the downstream end.
+- **Boundary conditions**: Marine ice sheet with grounding line migration; zero inflow at upstream wall; periodic lateral boundaries (y‑direction).
+- **Flow law**: Glen’s \(n = 3\) unless stated otherwise.
+- **Thermodynamics**: Isothermal (268 K) in the benchmark script.
+- **Available solvers**:
+  - **SSA**: default transient spin‑up.
+  - **HO / FS**: optional higher‑order checks (after 3‑D extrusion).
+
+### 1.2 Mesh Options
+
+| Nominal Δx (m) | Label in driver                  | Typical vertex count | Use‑case                  |
+| -------------- | -------------------------------- | -------------------- | ------------------------- |
+| 2000           | `2km_viscous` or `2km_coulomb`   |  ≈ 160 × 16 k        | Fast test runs            |
+| 1000           | `1km_viscous` or `1km_coulomb`   |  ≈ 320 × 32 k        | Standard benchmark        |
+| 500            | `500m_viscous` or `500m_coulomb` |  ≈ 640 × 64 k        | Convergence studies       |
+| 200            | `200m_viscous` or `200m_coulomb` |  ≈ 1600 × 160 k      | High‑resolution reference |
+
+**Basal friction law** options:
+
+- **Viscous** (power‑law, \(m = 3\)): `*_viscous` labels.
+- **Coulomb** (plastic till): `*_coulomb` labels, using \(\tau\_b = C_0 + C\_c |\sigma\_n|\).
+
+### 1.3 Workflow Steps
+
+The driver script (see `mismip_driver.py`) is orchestrated by an *organizer* object.  Key stages:
+
+1. **Mesh\_generation** → BAMG generates unstructured triangular mesh at chosen resolution.
+2. **Parameterization** → masks & initial geometry via `Mismip.py`.
+3. **Transient\_Steadystate** → 200 kyr relaxation with SSA.
+4. *(optional)* **Transient\_extrude** → extrude to 3‑D and switch to HO.
+5. **GlenSSA / GlenMOLHO / GlenHO** → Glen‐law transient experiments.
+6. **ESTARSSA / ESTARHO** → dual‐E (star) rheology experiments.
+7. **analyse** → automatic velocity‑field comparison and summary plots.
+
+To **run only the first comparison plot** on Gadi, adapt the example job script below (full listing in docs):
+
+```bash
+qsub run_mismip_first.sh   # runs steps 1–7 and stops
+```
+> **Warning**  
+> ACCESS‑ISSM is in alpha.  Expect API changes and incomplete documentation.  Use for testing and development only.
+
+More details, examples and forcing files are available on the [ACCESS‑ISSM GitHub](https://github.com/ACCESS-NRI/access-issm).
+
+[Run ACCESS‑ISSM](/models/run-a-model/run_access-issm){: .text-card }

docs/models/run_a_model/index.md

@@ -49,4 +49,13 @@ If you are unsure which ACCESS model is the best fit for your application, you c
             Run ACCESS-rAM
         </div>
     </a>
+    <!-- Run ACCESS-ISSM -->
+    <a href="/models/run-a-model/run_access-issm" class="vertical-card aspect-ratio1to1">
+        <div class="card-image-container">
+            <img class="img-contain with-padding white-background" src="/assets/model-config-logos/model_visualisation/access_ram_model_visualisation.png" alt="ACCESS-ISSM">
+        </div>
+        <div class="card-text-container bold">   
+            Run ACCESS-ISSM
+        </div>
+    </a>
 </div>

docs/models/run_a_model/run_access-issm.md

@@ -0,0 +1,179 @@
+{% set model = "ACCESS-ISSM" %}
+{% set pps_id = "u-ppppp" %} {# Pre‑Processing Suite ID (placeholder) #}
+{% set run_id = "u-rrrrr" %} {# Main Run Suite ID (placeholder) #}
+{% set branch = "access_rel_1" %}
+{% set pps_config = "https://github.com/ACCESS-NRI/access-issm/tree/main/pps" %}
+{% set run_config = "https://github.com/ACCESS-NRI/access-issm/tree/main/run" %}
+{% set model_configurations = "/models/access-issm" %}
+{% set release_notes = "https://forum.access-hive.org.au/t/access-issm-release-information/XXXX" %}
+[Cluster job guide]: https://opus.nci.org.au/display/Help/4.+PBS+Jobs
+[model components]: {{ model_configurations }}/#model-components
+[gadi]: https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-Overview
+[default project]: /getting_started/set_up_nci_account#change-default-project-on-gadi
+
+!!! release
+    This is a Beta Release.
+    Any model configuration and related source code mentioned in this page might change before the full release.
+    Limited support is currently provided for this model. Its usage is only recommended for testing by experienced users and collaborators.
+
+# Run {{ model }}
+
+## 1 About
+
+{{ model }} integrates the **Ice-sheet and Sea-level System Model (ISSM)** to the ACCESS climate modelling framework, enabling fully parallel ice‑sheet simulations on the [NCI _Gadi_ supercomputer][gadi].
+
+It is maintained and supported by **ACCESS‑NRI**.  
+A high‑level description of model components including the ISSM core, pre‑processing utilities and forcing data are available in the [{{ model }} overview]({{ model_configurations }}/#{{ model }}).
+
+The example below reproduces the ISSM controbution to the third [Marine Ice Sheet Model Intercomparison Project](https://tc.copernicus.org/articles/14/2283/2020/) (MISMIP+) benchmark for ice flow models.
+
+## 2 Prerequisites
+
+!!! warning
+    To run {{ model }}, you need to be a member of a project with allocated _Service Units (SU)_. For more information, check [how to join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects).
+
+- **NCI Account**<br>
+    Before running {{ model }}, you need to [Set Up your NCI Account](/getting_started/set_up_nci_account).
+
+- **Join NCI projects**<br>
+    Join the following projects by requesting membership on their respective NCI project pages:
+
+    - [vk83](https://my.nci.org.au/mancini/project/vk83/join)
+    - [xp65](https://my.nci.org.au/mancini/project/xp65/join)
+
+  For more information on joining specific NCI projects, refer to [How to connect to a project](https://opus.nci.org.au/display/Help/How+to+connect+to+a+project).
+
+- **Modules**
+
+  Load the following modules:
+
+   ```bash
+   module load python3/3.9.2 #3.10.4
+   module load git
+   ```
+
+---
+
+## 3  Quick‑start (Gadi login node)
+
+To run he model, a NCI project code with available compute allocation is required.
+
+```bash
+# 0. Choose a working directory for this test
+$ mkdir -p ~/experiments/mismip && cd ~/experiments/mismip
+
+# 1. Clone the ACCESS-ISSM repository (alpha branch)
+$ git clone --branch development \
+      https://github.com/ACCESS-NRI/access-issm.git
+
+# 2. Load the ACCESS-ISSM module (vk83 deployment)
+$ module use /g/data/vk83/modules
+$ module load access-issm
+
+# 3. Pre-process (mesh + inputs)
+$ cp access-issm/test/run_pps.sh ./
+$ qsub -P <NCI_PROJECT_CODE> run_pps.sh
+# Alternatively use `bash run_pps.sh` inside a pInteractive job.
+# Replace "<NCI_PROJECT_CODE>" with your active project code.
+
+# 4. When PPS finishes, run the first experiment bundle
+$ cp access-issm/examples/mismip/run_mismip_first.sh ./
+$ qsub run_mismip_first.sh  # generates SSA vs ESTAR comparison plot
+```
+
+Outputs:
+
+- Mesh + forcing NetCDF/HDF5 → `scratch/$PROJECT/$USER/mismip_pps/inputs/`
+- ISSM state & plots → `scratch/$PROJECT/$USER/mismip_run/Models_*/*`
+
+---
+
+## 4  Running from ARE Desktop
+
+> ARE provides a GUI VDI plus a terminal already SSH‑tunnelled to *gadi-login*.
+
+1. **Launch VDI** – open [https://are.nci.org.au](https://are.nci.org.au), choose **Gadi Desktop (x64)**, click **Launch**.
+2. **Gadi Terminal** – inside the desktop, open **Gadi Remote Terminal**.
+3. **Reserve nodes** (optional but recommended):
+   ```bash
+   persistent-sessions start issm
+   echo "issm.${USER}.au88.ps.gadi.nci.org.au" > \
+        ~/.persistent-sessions/cylc-session
+   ```
+4. **Load env + clone** – as in Quick‑start (`module …`, `git clone …`).
+5. **Pre‑process & Run** – submit the same `run_pps.sh` / `run_mismip_first.sh` with `qsub`.
+6. **Monitor** – `qstat -u $USER`, or `tail -f pps.o<jobid>` in a terminal; use ARE’s Paraview for quick looks.
+7. **Release nodes** when finished:
+   ```bash
+   persistent-sessions stop issm
+   ```
+
+*Tips*
+
+- Heavy solves **must** run on the reserved nodes, not on the VDI itself.
+- VDI sessions expire after 12 h; jobs keep running.
+
+---
+
+## 5  File structure
+
+```
+experiments/mismip/
+├── access-issm/                 # git clone (alpha branch)
+│   └── examples/mismip/
+│       ├── mismip_driver.py     # full driver script (all steps)
+│       ├── run_pps.sh           # helper: submits PPS job
+│       └── run_mismip_first.sh  # helper: submits early RUN job (steps 1‑7)
+├── run_pps.sh                   # copied helper – edit walltime/resources here
+└── run_mismip_first.sh          # copied helper – edit nodes/time as needed
+```
+
+---
+
+## 6  Editing job scripts
+
+Both helper scripts are standard PBS batch files.  Typical tweaks:
+
+| Directive          | Default    | Change when…                                                       |
+| ------------------ | ---------- | ------------------------------------------------------------------ |
+| `#PBS -P`          | `au88`     | Running under a different project code                             |
+| `#PBS -l ncpus`    | `32`       | Mesh resolution < 1 km → reduce to 8–16 ; very high‑res → increase |
+| `#PBS -l walltime` | `48:00:00` | Convergence problems: extend                                       |
+
+For quick interactive debugging you can run the driver directly inside an *ARE* Desktop or `qsub -I` session:
+
+```bash
+$ python mismip_driver.py  # uses default steps list
+```
+
+### {{ model }} configuration
+
+Key configurable groups (edit the configuration files as needed):
+
+| Suite | Section            | Purpose                                                              |
+|-------|--------------------|----------------------------------------------------------------------|
+| **PPS** | Domain setup      | Projection, bounds, resolution, MUA/SSA blend law, etc.             |
+|        | Datasets          | Surface mass balance, basal friction, geothermal heat, geometry DEMs  |
+| **RUN** | Time-stepping     | `INITIAL_CYCLE_POINT`, `FINAL_CYCLE_POINT`, dt, adaptive settings      |
+|        | Physics options   | Flow law, calving, melting parameterisations                          |
+|        | Resources         | MPI tasks, OpenMP threads, walltime                                   |
+
+After editing configurations, simply re-run the corresponding suite’s script.
+
+## 7 Troubleshooting
+
+* **NaNs in solver residuals** – try a smaller time‑step (`dt`) or increase the number of Picard iterations in the StressbalanceAnalysis.
+* **PETSc convergence errors** – confirm that `md.stressbalance.reltol` is properly set and not `NaN`; consider using hardware‑specific builds of PETSc ≥ 3.20.
+* **Job submission hangs** – check the log files for errors, verify that your module paths and environment variables (e.g., ISSM_DIR) are correctly set, and ensure proper resource allocation in your job scripts.
+
+## Get help
+
+Ask questions in the [ACCESS‑ISSM category](https://forum.access-hive.org.au/c/cryosphere/access-issm/) on ACCESS‑Hive, or email **support@access‑nri.org.au** with your suite ID and a log excerpt.
+
+---
+
+<custom-references>
+- ISSM User Guide: https://issm.jpl.nasa.gov/documentation
+- ACCESS‑NRI ISSM build recipe: https://github.com/ACCESS-NRI/access-issm
+- NCI Cylc docs: https://opus.nci.org.au/display/DAE/Run+Cylc7+Suites
+</custom-references>

mkdocs.yml

@@ -111,6 +111,7 @@ nav:
       - ACCESS-ESM: models/access_models/access-esm.md
       - ACCESS-OM: models/access_models/access-om.md
       - ACCESS-rAM: models/access_models/access-ram.md
+      - ACCESS-ISSM: models/access_models/access-issm.md
     - Model Components:
       - models/model_components/index.md
       - Atmosphere: models/model_components/atmosphere.md
@@ -128,6 +129,7 @@ nav:
       - Run ACCESS-OM2: models/run_a_model/run_access-om2.md
       - Run ACCESS-OM3: models/run_a_model/run_access-om3.md
       - Run ACCESS-rAM: models/run_a_model/run_access-ram.md
+      - Run ACCESS-ISSM: models/run_a_model/run_access-issm.md
     - Build a Model:
       - models/build_a_model/index.md
       - Modify and build an ACCESS model's source code: models/build_a_model/build_source_code.md