Documentation for ACCESS-RAM3 beta release #857

heidinett · 2024-12-10T05:31:42Z

Documentation for the beta release of ACCESS-RAM3

Fixes #841
Fixes #877

github-actions · 2024-12-10T05:31:57Z

PR Preview
🚀 Deployed preview to https://access-hive.org.au/pr-preview/pr-857
2025-02-07 08:54 AEDT

docs/models/run-a-model/run-access-ram.md

flicj191

Suggestions to fix the hierarchy of the headings so that the navigation on he right can show the sub-headings

engelca · 2024-12-11T23:20:27Z

The major comment relates to how persistent sessions work with the RAS/RNS.
In the RAS/RNS you currently have to ssh -Y directly into the persistent session to run the suite.
The suite can be edited thought via a non-persistent session.
To run from within a persistent session, I do the following:

ls ~/.persistent-session/ to get the "persistent-session" name
ssh -Y "persistent-session"
module use /g/data/hr22/modulefiles
module load cylc7
cd roses
cd "suite-directory"
rose suite-run

In the Quickstart for both the RAS and RNS after taking the chekout/copy of the suite, the users needs to manually change into the suite directory prior to any further commands.

In the "Specify target persistent session" section. This doesn't work for me. I did do it but the rose suite-run command will crash. It only works from within the persistent-session. We need to either remove this section or edit the rose/cylc suite so the cylc-session file works.

In RAS/"Run the suite". again I can't run from a non-persistent session so I do the steps above first.

In RAS/"Monitor the suite runs". The text says two main ways but only the GUI way is listed. The second way is through the file system. The users have not been told of this option or where to look for the output files. The file locations are non-trivial, i.e. "output directory"/"user"/cylc-run/"suite-id"/log/job/"cycle-date"/"job-name"/"run-number; usually 01 unless repeated".

In RAS/"Edit the RAS configuration". There is a type "congiguration".

In RAS/"Change the region centre and name". The video is not showing (I did record one and upload it though ...)

In RNS/"RNS output files". The subdirectories (ics, lbcs, and um) are not being shown in a list. And another typo "scienc_choice".

In RNS/"Edit the RNS configuration". The "Rose GUI" link goes to the RAS specific example not to the "rose edit &" command above it.

Added RNS content to quick start

Co-authored-by: Felicity Chun <[email protected]> Update docs/models/run-a-model/run-access-ram.md Co-authored-by: Felicity Chun <[email protected]> Update docs/models/run-a-model/run-access-ram.md Co-authored-by: Felicity Chun <[email protected]>

Fixing list format in RNS output files Fixing list format in RNS output files Fixing list format in RNS output files

Updated persistent sessionanimation

…y to the other 'How to run' pages

atteggiani

This PR is now the Hive Docs documentation for the beta release (and future 1.0 release) of the regional model.

I reintegrated a few portions (About, references, etc.) and adjusted a few minor things (please see my commits starting from 525eb0fe18722963483a596c38ae433813d02a36 for details) for consistency with the other "How to run" pages.

I added my review, listing both the comments in my previous version of the documentation (the ones that I had marked with a TODO within the code), and other additional comments (please refer to the related comments for details).
This will make it easier to add further reviews to this PR and commenting to the specific portions/comments with ideas and suggestions.

atteggiani · 2025-02-05T02:17:23Z

docs/models/configurations/access-ram.md

+TODO
+{: style="color:red"}
+<!-- Create the model overview page for ACCESS-RAM. Refer to the ACCESS-ESM1.5 one for an example. -->


Suggested change

TODO

{: style="color:red"}



Add the model overview page for ACCESS-RAM.
More details in #877's first task.

@engelca Could you please comment on how our ACCESS-NRI RAM3 configuation differs from the UKMO RNS.
Perhaps users need to know that there is a different config option using an existing executable instead of building the model, and that python scripts exist.

@engelca Could you please address this comment?
In addition to what heidi mentioned, I think the overview page should have content about any information that we would like to provide about the configuration, so that we can link to this overview page also within the "How to run page", without having redundant information in the latter.

atteggiani · 2025-02-05T03:02:05Z

docs/models/configurations/index.md

+    <!-- ACCESS-RAM -->
+    <a href="/models/configurations/access-ram/" class="horizontal-card">
+        <div class="card-image-container">
+            <img src="/assets/model-config-logos/configurations-without-titles/access-om.png" class="white-background img-contain"></img> 


Suggested change

<img src="/assets/model-config-logos/configurations-without-titles/access-om.png" class="white-background img-contain"></img>

<img src="/assets/model-config-logos/configurations-without-titles/access-ram.png" class="white-background img-contain"></img>

The access-ram.png currently doesn't exist. It should be created and added to the repo.
Maybe Natalia has updates on the configuration image for the regional model?

@ACCESS-NRI/webops will take care of this.

atteggiani · 2025-02-05T03:03:41Z

docs/models/configurations/index.md

+        <div class="card-text-container">
+            <span class="bold" >ACCESS-RAM</span>
+            <span>
+                ACCESS-RAM -- add text here. Also add correct image.


Suggested change

ACCESS-RAM -- add text here. Also add correct image.

ACCESS-RAM is ............

Add a short description of what ACCESS-RAM is, similarly to what it's done for the other models above in the page.

This was included separately in the RAS and RNS descriptions in my branch. Maybe they can be combined here.

Can you please link the specific content you are referring to or, maybe better, write a comment below with the "combined" content you are suggesting?

atteggiani · 2025-02-05T03:06:44Z

docs/models/run-a-model/index.md

+    <!-- Run ACCESS-RAM -->
+    <a href="/models/run-a-model/run-access-ram" class="vertical-card aspect-ratio1to1">
+        <div class="card-image-container">
+            <img class="img-contain with-padding white-background" src="/assets/model-config-logos/globe_visualisation/access_om_globe_visualisation.png" alt="ACCESS-RAM">


Suggested change

<img class="img-contain with-padding white-background" src="/assets/model-config-logos/globe_visualisation/access_om_globe_visualisation.png" alt="ACCESS-RAM">

<img class="img-contain with-padding white-background" src="/assets/model-config-logos/globe_visualisation/access_ram_globe_visualisation.png" alt="ACCESS-RAM">

The access_ram_globe_visualisation.png currently doesn't exist. It should be created and added to the repo.
Do we have an image similar to the other in the page that can be used for ACCESS-RAM?

@ACCESS-NRI/webops will take care of this.

atteggiani · 2025-02-05T06:43:50Z

docs/models/run-a-model/run-access-ram.md

+<!--
+TODO
+{: style="color:red"}
+<!-- Can we put a configuration here taken from MOSRS instead of GitHub? SVN? -->


Suggested change



Can we place the link of a configuration taken from MOSRS?
Maybe they can two separate ones, one for RAS and one for RNS.
What about https://code.metoffice.gov.uk/trac/roses-u/browser/d/g/7/6/7/trunk and https://code.metoffice.gov.uk/trac/roses-u/browser/d/g/7/6/8/trunk?

They would need to be two separate links to MOSRS. The ones listed would be the right ones.

Ok I'm going to add those links. Thank you!

Added in b058fa7686af11e2f9d953b5ad03a3f5398e3fc5.

atteggiani · 2025-02-05T22:50:28Z

docs/models/run-a-model/run-access-ram.md

+<!--
+The RNS is ...
+-->
+The `suite-ID` of the RNS is `{{ rns_id }}`.
+
+<!--
+TODO
+{: style="color:red"}
+<!-- Add short description of what the RAS does -->


Suggested change



The `suite-ID` of the RNS is `{{ rns_id }}`.



The RNS is ...

The `suite-ID` of the RNS is `{{ rns_id }}`.

Would be good to add a short description (2-3 lines) of what the RNS does.
Also include the RNS suite-ID.

Those variables get filled in by the markup when it is run.

The description for the RNS was included in my original branch.

@Chermelle Can you please add a short suitable description in a comment below? Thank you.

atteggiani · 2025-02-05T23:06:52Z

docs/models/run-a-model/run-access-ram.md

+The RNS output data can be found in the `/scratch/$PROJECT/$USER/cycl-run/<suite-ID>/share/cycle` directory, grouped for each [cycle](#change-run-length-and-cycling-frequency).<br>
+Within the cycle directory, outputs are divided into multiple nested subdirectories in the format `<nested_region>/<science_choice>/<nest_name>`, with [nested_region](), [science_choice]() and [nest_name]() referring to the respective configurable options in the [RAS](#edit-the-ras-configuration).
+
+<!--
+TODO
+{: style="color:red"}
+<!-- Use the same names for `nested_region` `science_choice` and `nest_name` as the one used above for the RAS and make sure all of the are referenced in the RAS and there are clear instructions on how to modify them. There is no reference for how to change the `science_choice`. If it cannot be changed, I would call it in a different way. Add links -->
+
+Each of the `<nest_name>` directory has the following subdirectories:
+
+- `ics` &rarr; initial conditions
+- `lbcs` &rarr; lateral boundary conditions
+- `um` &rarr; model output data
+
+<!--
+TODO
+{: style="color:red"}
+<!-- Use the same names for `nested_region` `science_choice` and `nest_name` as the one used above for the RAS and make sure all of the are referenced in the RAS and there are clear instructions on how to modify them. Add links -->


Suggested change

The RNS output data can be found in the `/scratch/$PROJECT/$USER/cycl-run/<suite-ID>/share/cycle` directory, grouped for each [cycle](#change-run-length-and-cycling-frequency).<br>

Within the cycle directory, outputs are divided into multiple nested subdirectories in the format `<nested_region>/<science_choice>/<nest_name>`, with [nested_region](), [science_choice]() and [nest_name]() referring to the respective configurable options in the [RAS](#edit-the-ras-configuration).



Each of the `<nest_name>` directory has the following subdirectories:

- `ics` → initial conditions

- `lbcs` → lateral boundary conditions

- `um` → model output data



The RNS output data can be found in the `/scratch/$PROJECT/$USER/cycl-run/<suite-ID>/share/cycle` directory, grouped for each [cycle](#change-run-length-and-cycling-frequency).<br>

Within the cycle directory, outputs are divided into multiple nested subdirectories in the format `<nested_region>/<science_choice>/<nest_name>`, with [nested_region](<LINK>), [science_choice](<LINK>) and [nest_name](<LINK>) referring to the respective configurable options in the [RAS](#edit-the-ras-configuration).

Each of the `<nest_name>` directory has the following subdirectories:

- `ics` → initial conditions

- `lbcs` → lateral boundary conditions

- `um` → model output data

Use the same names for <nested_region> <science_choice> and <nest_name> as the one used above for the RAS and make sure all of them are referenced in the RAS and there are clear instructions on how to modify them. Make sure <LINK> is substituted with the proper link to the related portion/paragraph of the RAS.

There is no reference to how to change the science_choice, it would be good to add instructions. If it cannot be changed, I would maybe call it in a different way.

By default the RNS puts data into directories named with a convention naming the science choice.

Changing the science choice has implications beyond a "introductory simple guide". Perhaps we should note that it is out of scope for the "run-a-model" guide.

As you suggest, I would then write a very short line about what science_choice is (based on what you wrote in the comment above), and not mention it within the configuration options that users can change.
Can you please provide, in a comment below, a short paragraph we can use in the documentation to describe the science_choice parameter (and maybe the fact that its change is beyond the scope of this guide)? Thank you.

atteggiani · 2025-02-05T23:09:42Z

docs/models/run-a-model/run-access-ram.md

+#### Change where the output from run is stored project
+To change where the output from the model run is stored, edit the _NCI_STORAGE_ field in _suite conf &rarr; Nesting Suite &rarr; General run options _, and click the _Save_ button ![Save button](/assets/run_access_cm/save_button.png){: style="height:1em"}. 
+
+<!--
+TODO
+{: style="color:red"}
+<!-- I couldn't restructure this title/text because from them I am not really understanding what `NCI_STORAGE` is. From its default value in the rose-suite.conf (scratch/$PROJECT) and how it's used inside the suite, it seems to be a project folder added to the `storage` option for the PBS jobs submission of many tasks. Therefore is not necessarily related to model outputs (is also related to model input), but to filesystem mounts that the model need to be able to access. Why is the text mentioning changing where the output is stored? -->


Suggested change

#### Change where the output from run is stored project

To change where the output from the model run is stored, edit the _NCI_STORAGE_ field in _suite conf → Nesting Suite → General run options _, and click the _Save_ button ![Save button](/assets/run_access_cm/save_button.png){: style="height:1em"}.



#### Change where the output from run is stored project

To change where the output from the model run is stored, edit the _NCI_STORAGE_ field in _suite conf → Nesting Suite → General run options _, and click the _Save_ button ![Save button](/assets/run_access_cm/save_button.png){: style="height:1em"}.

I am not sure what NCI_STORAGE is. From its default value in the rose-suite.conf (scratch/$PROJECT) and how it's used inside the suite, it seems to be a project folder added to the storage option for the PBS jobs submission of multiple tasks. Therefore, is not necessarily related to model outputs but also related to model input.
I would say in general is related to filesystem mounts that the model need to be able to access.
Why is the text mentioning changing where the output is stored?

The NCI_STORAGE impacts where the user wants the output of their runs to be stored.
It is mentioned to given an example of changing where the output from the run is stored.

Looking at the RNS (u-dg768) I can only see NCI_STORAGE being added to the pbs storage option for different tasks, but I cannot see any part that link it to the experiment output.
I can see NCI_STORAGE_TOP_DIR used to provide an env variable to the ARCHIVE task (which might define where the output is being stored).

Can you please point me to a portion of the RNS suite where there is link between the NCI_STORAGE variable and the output of the run?
Thank you

atteggiani · 2025-02-05T23:30:09Z

docs/models/run-a-model/run-access-ram.md

+To modify these parameters, navigate to _suite conf &rarr; Nesting Suite &rarr; Cycling options_, edit the `INITIAL_CYCLE_POINT`, `FINAL_CYCLE_POINT` and the `CYCLE_INT_HR` fields (using [ISO 8601 Duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format) and click the _Save_ button ![Save button](/assets/run_access_cm/save_button.png){: style="height:1em"}.
+
+<!--
+TODO
+{: style="color:red"}
+<!-- Are there any other options more specific to the RNS that users may want to change here? -->


Suggested change

To modify these parameters, navigate to _suite conf → Nesting Suite → Cycling options_, edit the `INITIAL_CYCLE_POINT`, `FINAL_CYCLE_POINT` and the `CYCLE_INT_HR` fields (using [ISO 8601 Duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format) and click the _Save_ button ![Save button](/assets/run_access_cm/save_button.png){: style="height:1em"}.



To modify these parameters, navigate to _suite conf → Nesting Suite → Cycling options_, edit the `INITIAL_CYCLE_POINT`, `FINAL_CYCLE_POINT` and the `CYCLE_INT_HR` fields (using [ISO 8601 Duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format) and click the _Save_ button ![Save button](/assets/run_access_cm/save_button.png){: style="height:1em"}.

Are there any further options specific to the RNS, that users may want to change, that could be added here?

@Chermelle
This is related to another comment above, about the configuration options that we want to include in the instructions.
I think whatever configuration options we decide to detail in the instructions, we might want to add the options specific to the RNS here.

atteggiani · 2025-02-05T23:45:15Z

docs/models/run-a-model/run-access-ram.md

+<!--
+## Get Help
+If you have questions or need help regarding {{ model }}, consider creating a topic in the [Earth System Model category of the ACCESS-Hive Forum](https://forum.access-hive.org.au/c/esm/earth-system-model/72).<br>
+For assistance on how to request help from ACCESS-NRI, follow the [guidelines on how to get help](/about/user_support/#still-need-help).
+
+TODO
+{: style="color:red"}
+<!-- Check and change link details if needed -->


Suggested change



## Get Help

If you have questions or need help regarding {{ model }}, consider creating a topic in the ........ category of the ACCESS-Hive Forum](<LINK>).<br>

For assistance on how to request help from ACCESS-NRI, follow the [guidelines on how to get help](/about/user_support/#still-need-help).

Add the right forum category with the <LINK>.

@ACCESS-NRI/webops can take care of this, once there is a Forum post of the release.

…isation' to 'model-config-logos/model_visualisation' and changed 'globe_visualisations' part of assets name to 'model_visualisations' - Deleted unused asset folder 'assets/globe_visualisations' - Updated image for 'Run ACCESS-RAM' card

heidinett marked this pull request as draft December 10, 2024 05:32

heidinett changed the base branch from development to davide/access-ram-documentation December 11, 2024 00:42

flicj191 requested changes Dec 11, 2024

View reviewed changes

KAUR1984 added a commit that referenced this pull request Dec 11, 2024

🚧 (#857): First pull from development branch

deea514

engelca approved these changes Dec 13, 2024

View reviewed changes

atteggiani force-pushed the heidi/ram-doc-issue841 branch from 5533d4b to e4e1873 Compare February 5, 2025 01:29

atteggiani mentioned this pull request Feb 5, 2025

Access ram documentation #847

Closed

atteggiani changed the base branch from davide/access-ram-documentation to development February 5, 2025 01:49

atteggiani and others added 19 commits February 5, 2025 12:49

Collated Chermelle's documentation on ACCESS-RAM

7204de7

created quickstart guide

0f58145

Added RAS content to quick start

a058b77

Added RNS content to quick start

Removed TODO comments and non-updated sections

f28be7d

Added detailed guide and intro to RNS

0a045c7

Fixed formatting and add intro to RNS

50fdc54

Removing code block info box at top of page

f75b757

Fixed typo

5d86c33

Fixed typos and formatting

649e007

Edited intro for quick guide

4f61511

Testing line break

604cada

Testing numbered list items

f9ee9fc

Fixed section headings

2b2df0a

Moved config card above info note

18788a6

Fixed the table of contents on right hand side

a6ae57b

Changed back the spil of sections

754fba7

Edited tip at end of quick start

f579720

Moved tip to above Detailed Guide section

dc58883

heidinett added 2 commits February 5, 2025 12:49

Edited text in Detailed Guide section

3a69dcd

Fixed typos and put back in uncommented section

575d29c

atteggiani force-pushed the heidi/ram-doc-issue841 branch from e4e1873 to c6134db Compare February 5, 2025 01:49

heidinett added 5 commits February 5, 2025 12:51

Fixing list format in RNS output files

304ac32

Fixing list format in RNS output files Fixing list format in RNS output files Fixing list format in RNS output files

Edited log dir & added tip on logout persistent sessions

49fc709

Updated persistent sessions instructions

98fe281

Updated persistent session terminal animation

a35cd83

Updated persistent sessionanimation

Fixed formatting in Quick Start

5196296

atteggiani force-pushed the heidi/ram-doc-issue841 branch from c6134db to 5196296 Compare February 5, 2025 01:51

atteggiani mentioned this pull request Feb 5, 2025

Update documentation for ACCESS regional model beta release #877

Open

2 tasks

atteggiani changed the title ~~ACCESS-RAM3: Quick start guide (issue #841)~~ Documentation for ACCESS-RAM3 Feb 5, 2025

atteggiani changed the title ~~Documentation for ACCESS-RAM3~~ Documentation for ACCESS-RAM3 beta release Feb 5, 2025

atteggiani self-requested a review February 5, 2025 02:15

Moved ACCESS-RAM configuration button at the top of the page similarl…

525eb0f

…y to the other 'How to run' pages

atteggiani force-pushed the heidi/ram-doc-issue841 branch from cc52c3a to 525eb0f Compare February 5, 2025 06:12

Reintroduced About section with updated description

0a0fe83

atteggiani force-pushed the heidi/ram-doc-issue841 branch from 17aeed9 to 0a0fe83 Compare February 5, 2025 07:06

atteggiani added 5 commits February 5, 2025 18:26

Removed model description from the 'Detailed Guide'

46c9149

Added Gadi link

a20e2e8

Reorganized paragraphs' hierarchy

1debfee

Added abbreviation to UK Met Office

63a961b

Added intentation

521a072

atteggiani requested changes Feb 5, 2025

View reviewed changes

atteggiani added 4 commits February 6, 2025 14:10

Updated configurations buttons at the top.

b058fa7

Removed mention to namelists

66a8813

Un-commented the example for region center choice

7136430

atteggiani requested review from flicj191 and removed request for flicj191 February 6, 2025 06:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for ACCESS-RAM3 beta release #857

Documentation for ACCESS-RAM3 beta release #857

heidinett commented Dec 10, 2024 •

edited by atteggiani

Loading

github-actions bot commented Dec 10, 2024 •

edited

Loading

flicj191 left a comment

engelca commented Dec 11, 2024 •

edited

Loading

atteggiani left a comment •

edited

Loading

atteggiani Feb 5, 2025

heidinett Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

engelca Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

engelca Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

engelca Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

engelca Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

engelca Feb 6, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

atteggiani Feb 6, 2025

atteggiani Feb 5, 2025

atteggiani Feb 6, 2025

	TODO
	{: style="color:red"}
	<!-- Create the model overview page for ACCESS-RAM. Refer to the ACCESS-ESM1.5 one for an example. -->

	<img src="/assets/model-config-logos/configurations-without-titles/access-om.png" class="white-background img-contain"></img>
	<img src="/assets/model-config-logos/configurations-without-titles/access-ram.png" class="white-background img-contain"></img>

	ACCESS-RAM -- add text here. Also add correct image.
	ACCESS-RAM is ............

	<img class="img-contain with-padding white-background" src="/assets/model-config-logos/globe_visualisation/access_om_globe_visualisation.png" alt="ACCESS-RAM">
	<img class="img-contain with-padding white-background" src="/assets/model-config-logos/globe_visualisation/access_ram_globe_visualisation.png" alt="ACCESS-RAM">

Documentation for ACCESS-RAM3 beta release #857

Are you sure you want to change the base?

Documentation for ACCESS-RAM3 beta release #857

Conversation

heidinett commented Dec 10, 2024 • edited by atteggiani Loading

github-actions bot commented Dec 10, 2024 • edited Loading

flicj191 left a comment

Choose a reason for hiding this comment

engelca commented Dec 11, 2024 • edited Loading

atteggiani left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

heidinett commented Dec 10, 2024 •

edited by atteggiani

Loading

github-actions bot commented Dec 10, 2024 •

edited

Loading

engelca commented Dec 11, 2024 •

edited

Loading

atteggiani left a comment •

edited

Loading