Merge branch 'development' into 978-General-how-to-use-Payu-Docs

Author: ccarouge

docs/css/access-nri.css

@@ -920,11 +920,8 @@ details.code {
 }
 
 /* Adjust anchors to links */
-:target::before {
-  content: "";
-  display: block;
-  height: 1rem; /* This identifies the distance of the element from the banner when clicking on an achor link */
-  margin-top: -1rem; /* This should be match the height with the sign switched */
+[id] {
+  scroll-margin-top: 7rem !important;
 }
 
 

docs/getting_started/are.md

@@ -50,7 +50,7 @@ Hence, there are multiple [PBS directives](https://opus.nci.org.au/display/Help/
 - **Storage**<br>
     `/g/data` (inserted as _gdata/&lt;project-ID&gt;_) `/scratch` (inserted as _scratch/&lt;project-ID&gt;_) data storage projects that will be available to the session.<br>
     In ARE, data storage locations need to be explicitly defined. This means that you need to insert any `/g/data` and `/scratch` project folders you want to execute data I/O operations from.<br>
-    Multiple storage projects are separated by a plus (_+_) (e.g., _gdata/tm70+gdata/hh5+scratch/xp65_).
+    Multiple storage projects are separated by a plus (_+_) (e.g., _gdata/tm70+gdata/xp65+scratch/xp65_).
 {: id="storage-option"}
 
     !!! warning

docs/getting_started/environments.md

@@ -7,7 +7,7 @@
 # _conda/analysis3_ Python Environment
 
 !!! danger
-    All users are advised to [update their workflows](#update-workflows) to replace the `hh5` `conda/analysis3` environment with the `xp65` `conda/analysis3` environment as soon as possible to ensure continued support and access to the latest features. The `hh5` `conda/analysis3` environment is no longer actively maintained and, **after 30 May 2025**, may be taken down without prior notice.
+    All users are advised to [update their workflows](#update-workflows) to replace the `hh5` `conda/analysis3` environment with the `xp65` `conda/analysis3` environment as soon as possible to ensure continued support and access to the latest features. The `hh5` `conda/analysis3` environment is no longer available.
 
 
 ACCESS-NRI now supports and maintains the `conda/analysis3` _Python_ environment, housed within the `xp65` NCI project. This environment includes _Python_ libraries commonly used for climate data processing and analysis, allowing users to run workflows on _Gadi_ without having to manage package installations themselves. This is the continuation of the environments formerly [maintained by CLEX](#acknowledgements) within the `hh5` NCI project.

docs/models/build_a_model/build_source_code.md

@@ -782,8 +782,8 @@ A limitation of the NCI's _Linaro Forge_ license is that the maximum number of p
 
 * __UM7__: In `atmosphere/um_env.yaml`, change `UM_ATM_NPROCX` and `UM_ATM_NPROCY`, which describe the number of chunks in the x and y directions, as well as `UM_NPES` to the product of `UM_ATM_NPROCX` and `UM_ATM_NPROCY`. In `config.yaml`, change the `atmosphere: ncpus` to be the same as `UM_NPES`.
 * __MOM5__: In `ocean/input.nml`, change `layout` in the `&ocean_model_nml` namelist, which describes the number of chunks in the x and y directions in `nx,ny` format. In `config.yaml`, change the `ocean: ncpus` to the product of `nx` and `ny`.
-* __CICE4__: Requires the user to have their own Spack installation. In the user's Spack installation, in `${SPACK_ROOT}/spack-packages/packages/cice4/package.py`, modify the entries in the `__targets` dictionary to the desired number of processes and blocks (the product of the blocks must be the same as the processes). The resulting executable name is `cice_<driver>_<grid>_<blocks>_<nprocs>p.exe`, which must be specified in the `config.yaml`. In the configuration's `ice/cice_in.nml`, change `nprocs` in the `&domain_nml` namelist to the desired number of processes. Finally, in the `config.yaml`, change the `ice: ncpus` to the desired number of processes.
-* __CICE5__: Requires the user to have their own Spack installation. In the user's Spack installation, in `${SPACK_ROOT}/spack-packages/packages/cice5/package.py`, modify the entries in the `self.__targets` dictionary and `self.add_target` calls to the desired number of processes and blocks (the product of the blocks must be the same as the processes). The resulting executable name is `cice_<driver>_<grid>_<blocks>_<nprocs>p.exe`, which must be specified in the `config.yaml`. In the configuration's `ice/cice_in.nml`, change `nprocs` in the `&domain_nml` namelist to the desired number of processes. Finally, in the `config.yaml`, change the `ice: ncpus` to the desired number of processes.
+* __CICE4__: To change the number of processes used by _CICE4_, the _CICE4_ executable needs to be recompiled. This requires the user to modify their own _Spack_ installation. In the user's Spack installation, in `${SPACK_ROOT}/spack-packages/packages/cice4/package.py`, modify the entries in the `__targets` dictionary to the desired number of processes and blocks (the product of the blocks must be the same as the processes). The resulting executable name is `cice_<driver>_<grid>_<blocks>_<nprocs>p.exe`, which must be specified in the `config.yaml`. In the configuration's `ice/cice_in.nml`, change `nprocs` in the `&domain_nml` namelist to the desired number of processes. Finally, in the `config.yaml`, change the `ice: ncpus` to the desired number of processes.
+* __CICE5__: To change the number of processes used by CICE5, the CICE5 executable needs to be recompiled, and the new blocksizes need to be specified. In `spack.yaml`, modify or add the [five variants _nxglob_, _nyglob_, _blckx_, _blcky_, _mxblcks_](https://github.com/search?q=repo%3AACCESS-NRI%2Faccess-spack-packages+%5C%22nxglob%5C%22+%5C%22nyglob%5C%22+%5C%22blckx%5C%22+%5C%22blcky%5C%22+%5C%22mxblcks%5C%22&type=code) to the desired number of processes and blocks. For ACCESS-ESM1.6, nprocs must be a divisor of _nxglob_(=360), therefore set _blckx = 360/nprocs_ and _mxblcks=1_. For ACCESS-OM2, there are more options (see Section 4.7 of the CICE5 [documentation](https://github.com/ACCESS-NRI/cice5/blob/master/doc/cicedoc.pdf)). In the configuration's `ice/cice_in.nml`, change `nprocs` in the `&domain_nml` namelist to the desired number of processes. Finally, in the `config.yaml`, change the executable name to the new build and change `ice: ncpus` to the desired number of processes.
 
 For the example above, the number of processes requested is larger than the number allowed by _Linaro Forge_. Therefore, changes to the atmosphere (UM) and ocean (MOM5) decompositions are required. For this reason, we will reduce the number of processes to 16 for UM and to 12 for MOM5. As CICE4 only requests 12 processes, this can be kept as is. The updated configuration would look like the following:
 

docs/models/run_a_model/run_access-cm2.md

@@ -27,6 +27,7 @@
 
     - [access](https://my.nci.org.au/mancini/project/access/join)
     - [hr22](https://my.nci.org.au/mancini/project/hr22/join)
+    - [xp65](https://my.nci.org.au/mancini/project/xp65/join)
     - [ki32](https://my.nci.org.au/mancini/project/ki32/join)
     - [ki32_mosrs](https://my.nci.org.au/mancini/project/ki32_mosrs/join)
 
@@ -64,10 +65,10 @@ Go to the [ARE VDI](https://are.nci.org.au/pun/sys/dashboard/batch_connect/sys/d
     The project must have allocated _Service Units (SU)_ to run your simulation. Usually, but not always, this corresponds to your `$PROJECT`.<br>
     For more information, refer to how to [Join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects).
 
-- **Storage** &rarr; `gdata/access+gdata/hh5+gdata/hr22+gdata/ki32` (minimum)<br>
+- **Storage** &rarr; `gdata/access+gdata/xp65+gdata/hr22+gdata/ki32` (minimum)<br>
     This is a list of all project data storage, joined by plus (`+`) signs, needed for the {{ model }} simulation. In ARE, storage locations need to be explicitly defined to access data from within a VDI instance.<br>
-    Every {{ model }} simulation can be unique and input data can originate from various sources. Hence, if your simulation requires data stored in project folders other than `access`, `hh5`, `hr22` or `ki32`, you need to add those projects to the storage path.<br>
-    For example, if your {{ model }} simulation requires data stored in `/g/data/tm70` and `/scratch/w40`, your full storage path will be: `gdata/access+gdata/hh5+gdata/hr22+gdata/ki32+gdata/tm70+scratch/w40`
+    Every {{ model }} simulation can be unique and input data can originate from various sources. Hence, if your simulation requires data stored in project folders other than `access`, `xp65`, `hr22` or `ki32`, you need to add those projects to the storage path.<br>
+    For example, if your {{ model }} simulation requires data stored in `/g/data/tm70` and `/scratch/w40`, your full storage path will be: `gdata/access+gdata/xp65+gdata/hr22+gdata/ki32+gdata/tm70+scratch/w40`
 
 Launch the ARE session and, once it starts, click on _Launch VDI Desktop_.
 
@@ -599,11 +600,46 @@ For the `{{ suite_id }}` suite in this example, the `atm` directory contains:
 
 Files formatted as `<suite-name>a.xhist-<year><month><day>` contain metadata information.
 
-## Port suites from accessdev
+## Troubleshooting
+### Update suites still relying on hh5
+!!! warning
+    Some suites might still not work when ported this way.<br>
+    If you have a suite that was relying on `hh5` and, even after following the steps below, the run submission fails, consider [getting help on the Hive Forum](/about/user_support/ask_on_forum).
+
+Previously, the `hh5` NCI project hosted the Python environments and software often used within suites (e.g., `conda/analysis3` environments, `pythonlib/um2netcdf4` utility).<br>
+Due to `hh5` decommissioning, all references to `hh5` must be replaced with the project storing the updated versions of the environments and software. For suites derived from the example suite above (`{{ suite_id }}` ), the updated versions are stored in `xp65`.
+
+Follow the steps below to ensure your suite is not using software from `hh5`:
+
+#### 1. Update netcdf_conversion task {: .no-toc }
+In the `suite.rc` file, within the `[[netcdf_conversion]]` task, update the loading of `pythonlib/um2netcdf4` to be using `pythonlib/um2netcdf4/xp65` instead:
+```diff
+- module load pythonlib/um2netcdf4
++ module load pythonlib/um2netcdf4/xp65
+```
+
+#### 2. Replace hh5 with xp65 {: .no-toc }
+To check if your {{ model }} suite relies on `hh5`, run the following command from your suite directory:
+```
+grep -r hh5 --exclude-dir=.svn .
+```
+
+Then, if you see any output from the command above, replace any `hh5` occurrency with `xp65`.<br>
+Lines that you will likely need to replace include storage specification lines (e.g., `-l storage = ...+gdata/hh5...`) and modules (e.g., `module use /g/data/hh5/public/modules`).
+
+!!! warning
+    If your suite loads `conda/analysis3`, to ensure reproducibility it is suggested to use a specific version of the environment (e.g., `conda/analysis3-25.11`).
+    For more information about `conda/analysis3` Python environment, refer to the [conda/analysis3 Python Environment page](/getting_started/environments/).
+
+### Port suites from accessdev
+!!! warning
+    Some suites might not be ported this way.<br>
+    If you have a suite that was running on _accessdev_ and even after following the steps below the run submission fails, consider [getting help on the Hive Forum](/about/user_support/ask_on_forum).
+
 _accessdev_ was the server used for {{ model }} run submission workflow before the update to persistent sessions.<br>
 If you have a suite that was running on accessdev, you can run it using persistent sessions by carrying out the following steps:
 
-### Initialisation step
+#### 1. Initialisation step {: .no-toc }
 To set the correct SSH configuration for _Cylc_, some SSH keys need to be created in the `~/.ssh` directory.<br>
 To create the required SSH keys, run the following command:
 ```
@@ -612,27 +648,23 @@ To create the required SSH keys, run the following command:
 !!! tip
     You only need to run this initialisation step once.
 
-### Set host to localhost
+#### 2. Set host to localhost {: .no-toc }
 To enable _Cylc_ to submit PBS jobs directly from the persistent session, the suite configuration should have its `host` set as `localhost`.<br>
 You can manually set all occurrences of `host` to `localhost` in the suite configuration files.<br>
 Alternatively, you can run the following command in the suite folder:
 ```
 grep -rl --exclude-dir=.svn "host\s*=" . | xargs sed -i 's/\(host\s*=\s*\).*/\1localhost/g'
 ```
 
-### Add _gdata/hr22_ and _gdata/ki32_ in the PBS storage directives
+#### 3. Add _gdata/hr22_ and _gdata/ki32_ in the PBS storage directives {: .no-toc }
 As the persistent sessions workflow uses files in the `hr22` and `ki32` project folders on _Gadi_, the respective folders need to be added to the `storage` directive in the suite configuration files.<br>
 You can do this manually or run the following command from within the suite directory:
 ```
 grep -rl --exclude-dir=.svn "\-l\s*storage\s*=" . | xargs sed -i '/\-l\s*storage\s*=\s*.*gdata\/hr22.*/! s/\(\-l\s*storage\s*=\s*.*\)/\1+gdata\/hr22/g ; /\-l\s*storage\s*=\s*.*gdata\/ki32.*/! s/\(\-l\s*storage\s*=\s*.*\)/\1+gdata\/ki32/g'
 ```
 
-!!! warning
-    Some suites might not be ported this way.<br>
-    If you have a suite that was running on _accessdev_ and, even after following the steps above, the run submission fails, consider [getting help on the Hive Forum](/about/user_support/ask_on_forum).
-
-## Known issues
-Below are listed some {{ model }} known issues which will not be fixed.
+### Known issues
+Below are listed some {{ model }} known issues which are not going to be fixed.
 
 - [Different cycling frequencies break reproducibility](https://forum.access-hive.org.au/t/different-cycling-frequencies-in-access-cm2-lead-to-different-solutions/4539)
 {: #issues-cycling-repro }

docs/models/run_a_model/run_access-om2.md

@@ -168,7 +168,7 @@ For information about `restart_period`, refer to [Change run length](#change-run
     <terminal-line lineDelay=50>Loading exe manifest: manifests/exe.yaml</terminal-line>
     <terminal-line lineDelay=50>payu: Found modules in /opt/Modules/v4.3.0</terminal-line>
     <terminal-line lineDelay=50>
-        qsub -q normal -P tm70 -l walltime=10800 -l ncpus=288 -l mem=1000GB -N 1deg_jra55_ryf -l wd -j n -v PAYU_PATH=/g/data/hh5/public/apps/miniconda3/envs/analysis3-23.10/bin,MODULESHOME=/opt/Modules/v4.3.0,MODULES_CMD=/opt/Modules/v4.3.0/libexec/modulecmd.tcl,MODULEPATH=/g/data/hr22/modulefiles:/g/data/hh5/public/modules:/etc/scl/modulefiles:/opt/Modules/modulefiles:/opt/Modules/v4.3.0/modulefiles:/apps/Modules/modulefiles -W umask=027 -l storage=gdata/hh5+gdata/vk83 -- /g/data/hh5/public/apps/miniconda3/envs/analysis3-23.10/bin/python3.10 /g/data/hh5/public/apps/miniconda3/envs/analysis3-23.10/bin/payu-run
+        qsub -q normal -P tm70 -l walltime=10800 -l ncpus=288 -l mem=1000GB -N 1deg_jra55_ryf -l wd -j n -v PAYU_PATH=/g/data/vk83/apps/base_conda/envs/payu-1.1.6/bin,MODULESHOME=/opt/Modules/v4.3.0,MODULES_CMD=/opt/Modules/v4.3.0/libexec/modulecmd.tcl,MODULEPATH=/g/data/vk83/modules:/etc/scl/modulefiles:/opt/Modules/modulefiles:/opt/Modules/v4.3.0/modulefiles:/apps/Modules/modulefiles -W umask=027 -l storage=gdata/vk83 -- /g/data/vk83/./apps/conda_scripts/payu-1.1.6.d/bin/python /g/data/vk83/apps/base_conda/envs/payu-1.1.6/bin/payu-run
     </terminal-line>
     <terminal-line lineDelay=50>&lt;job-ID&gt;.gadi-pbs</job-ID>></terminal-line>
 </terminal-window>

drafts/med/model_evaluation_getting_started/model_evaluation_getting_started.md

@@ -7,7 +7,7 @@ The following instructions explain how to load the curated python environment on
 ???+ warning "ACCESS-NRI provides code and support, but not computing resources"
     You do not automatically have access to all `/g/data/` storage on <i>Gadi</i>. You need to <a href="/getting_started/set_up_nci_account#join-relevant-nci-projects">join an NCI project</a> to view files on `/g/data/$PROJECT`.
     <br>
-    For model evaluation and diagnostics, you need to join projects `xp65` and `hh5` for code access and a `$PROJECT` with sufficient compute resources.
+    For model evaluation and diagnostics, you need to join project `xp65` for code access and a `$PROJECT` with sufficient compute resources.
 
 ## What is the `access-med` environment?
 
@@ -114,7 +114,7 @@ Below are some example values that you should change to match your `$PROJECT` an
 - **Queue** `normalbw` 
 - **Compute Size** `tiny` 
 - **Project** `iq82` (This should match your `$PROJECT` with compute resources)
-- **Storage** `gdata/xp65+gdata/hh5` (Select all that match your project's `/g/data` storage)
+- **Storage** `gdata/xp65` (Select all that match your project's `/g/data` storage)
 - *Advanced Options ...* (click button to expand) 
 - **Module directories** `/g/data/xp65/public/modules`
 - **Modules** `conda/are`
@@ -132,7 +132,7 @@ Launch JupyterLab by clicking on the <i>Open JupyterLab</i> button at the bottom
 <br>
 This will open a window which contains a directory structure on the left and a Jupyter notebook on the right, as shown below. 
 <br>
-If you loaded the modules from `hh5` or `xp65`, you should be able to import python packages such as `numpy`, `xarray` or `intake`, as shown below:
+If you loaded the modules from `xp65`, you should be able to import python packages such as `numpy`, `xarray` or `intake`, as shown below:
 
 <div style="text-align: center;">
     <img src="../../../assets/getting_started/are_2.png" alt="Example of a JupyterLab session with directory tree to the left and jupyter notebook to the right, showing successfully imported python packages." width="75%" />