From 1f005b2a1036f04566a946108acfe5ba269314b5 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Fri, 8 May 2026 16:59:47 +1000 Subject: [PATCH 1/9] add include file for testing --- docs/includes/persistent_session.md | 71 +++++++++++++++++++++++ docs/models/run_a_model/run_access-cm2.md | 71 +---------------------- 2 files changed, 72 insertions(+), 70 deletions(-) create mode 100644 docs/includes/persistent_session.md diff --git a/docs/includes/persistent_session.md b/docs/includes/persistent_session.md new file mode 100644 index 000000000..455fc26d5 --- /dev/null +++ b/docs/includes/persistent_session.md @@ -0,0 +1,71 @@ +To support the use of long-running processes, such as ACCESS model runs, NCI provides a service on _Gadi_ called [persistent sessions](https://opus.nci.org.au/display/Help/Persistent+Sessions). + +To run {{ model }}, you need to start a persistent session and set it as the target session for the model run. + +### Start a new persistent session +To start a new persistent session on _Gadi_, using either a login node or an ARE terminal instance, run the following command: +``` +persistent-sessions start +``` + +This will start a persistent session with the given `name` that runs under your [default project](/getting_started/set_up_nci_account#change-default-project-on-gadi).
+If you want to assign a different project to the persistent session, use the option `-p`: +``` +persistent-sessions start -p +``` + +!!! tip + While the project assigned to a persistent session does not have to be the same as the project used to run the {{ model }} configuration, it does need to have allocated _Service Units (SU)_.
+ For more information, check how to [Join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects). + + + persistent-sessions start <name> + session <persistent-session-uuid> running - connect using +  ssh <name>.<$USER>.<project>.ps.gadi.nci.org.au + + +To list all active persistent sessions run: +``` +persistent-sessions list +``` + + + persistent-sessions list +              UUID  PROJECT   ADDRESS    CPUTIME MEMORY + <persistent-session-uuid> <project> 10.9.0.62 00:00:05.213 30.5M + + + +The label of a newly-created persistent session has the following format:
+`.<$USER>..ps.gadi.nci.org.au`. + +### Specify {{ model }} target persistent session + +After starting the persistent session, it is essential to assign it to the {{ model }} run.
+The easiest way to do this is to insert the persistent session label into the file `~/.persistent-sessions/cylc-session`.
+You can do it manually, or by running the following command (by substituting `` with the name given to the persistent session, and `` with the project assigned to it): +``` +cat > ~/.persistent-sessions/cylc-session <<< ".${USER}..ps.gadi.nci.org.au" +``` + +For example, if the user `abc123` started a persistent session named `cylc` under the project `xy00`, the command will be: + + + cat > ~/.persistent-sessions/cylc-session <<< cylc.abc123.xy00.ps.gadi.nci.org.au + cat ~/.persistent-sessions/cylc-session + cylc.abc123.xy00.ps.gadi.nci.org.au + + +For more information on how to specify the target session, refer to [Specify Target Session with Cylc7 Suites](https://opus.nci.org.au/display/DAE/Run+Cylc7+Suites#RunCylc7Suites-SpecifyTargetSession). + +!!! tip + You can simultaneously submit multiple {{ model }} runs using the same persistent session without needing to start a new one. Hence, the process of specifying the target persistent session for {{ model }} should only be done once.
+ After specifying the {{ model }} target persistent session the first time, to run {{ model }} you just need to make sure to have an active persistent session named like the specified {{ model }} target persistent session. + +### Terminate a persistent session +To stop a persistent session, run: +``` +persistent-sessions kill +``` +!!! warning + When you terminate a persistent session, any model running on that session will stop. Therefore, you should check whether you have any active model runs before terminating a persistent session. diff --git a/docs/models/run_a_model/run_access-cm2.md b/docs/models/run_a_model/run_access-cm2.md index 476c8f489..6441166be 100644 --- a/docs/models/run_a_model/run_access-cm2.md +++ b/docs/models/run_a_model/run_access-cm2.md @@ -81,77 +81,8 @@ To open the terminal, click on the black terminal icon at the top of the window. ![Open ARE VDI terminal example](/assets/run_access_cm/open_are_vdi_terminal.gif){: class="example-img" loading="lazy"} ## Set up {{ model }} persistent session -To support the use of long-running processes, such as ACCESS model runs, NCI provides a service on _Gadi_ called [persistent sessions](https://opus.nci.org.au/display/Help/Persistent+Sessions). -To run {{ model }}, you need to start a persistent session and set it as the target session for the model run. - -### Start a new persistent session -To start a new persistent session on _Gadi_, using either a login node or an ARE terminal instance, run the following command: -``` -persistent-sessions start -``` - -This will start a persistent session with the given `name` that runs under your [default project](/getting_started/set_up_nci_account#change-default-project-on-gadi).
-If you want to assign a different project to the persistent session, use the option `-p`: -``` -persistent-sessions start -p -``` - -!!! tip - While the project assigned to a persistent session does not have to be the same as the project used to run the {{ model }} configuration, it does need to have allocated _Service Units (SU)_.
- For more information, check how to [Join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects). - - - persistent-sessions start <name> - session <persistent-session-uuid> running - connect using -  ssh <name>.<$USER>.<project>.ps.gadi.nci.org.au - - -To list all active persistent sessions run: -``` -persistent-sessions list -``` - - - persistent-sessions list -              UUID  PROJECT   ADDRESS    CPUTIME MEMORY - <persistent-session-uuid> <project> 10.9.0.62 00:00:05.213 30.5M - - - -The label of a newly-created persistent session has the following format:
-`.<$USER>..ps.gadi.nci.org.au`. - -### Specify {{ model }} target persistent session - -After starting the persistent session, it is essential to assign it to the {{ model }} run.
-The easiest way to do this is to insert the persistent session label into the file `~/.persistent-sessions/cylc-session`.
-You can do it manually, or by running the following command (by substituting `` with the name given to the persistent session, and `` with the project assigned to it): -``` -cat > ~/.persistent-sessions/cylc-session <<< ".${USER}..ps.gadi.nci.org.au" -``` - -For example, if the user `abc123` started a persistent session named `cylc` under the project `xy00`, the command will be: - - - cat > ~/.persistent-sessions/cylc-session <<< cylc.abc123.xy00.ps.gadi.nci.org.au - cat ~/.persistent-sessions/cylc-session - cylc.abc123.xy00.ps.gadi.nci.org.au - - -For more information on how to specify the target session, refer to [Specify Target Session with Cylc7 Suites](https://opus.nci.org.au/display/DAE/Run+Cylc7+Suites#RunCylc7Suites-SpecifyTargetSession). - -!!! tip - You can simultaneously submit multiple {{ model }} runs using the same persistent session without needing to start a new one. Hence, the process of specifying the target persistent session for {{ model }} should only be done once.
- After specifying the {{ model }} target persistent session the first time, to run {{ model }} you just need to make sure to have an active persistent session named like the specified {{ model }} target persistent session. - -### Terminate a persistent session -To stop a persistent session, run: -``` -persistent-sessions kill -``` -!!! warning - When you terminate a persistent session, any model running on that session will stop. Therefore, you should check whether you have any active model runs before terminating a persistent session. +--8<-- "includes/persistent_session.md ## Rose/Cylc/MOSRS setup From 960349cc4249f3b768aca68acc0d996b357e13e1 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Fri, 8 May 2026 20:21:13 +1000 Subject: [PATCH 2/9] fix typo --- docs/models/run_a_model/run_access-cm2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/models/run_a_model/run_access-cm2.md b/docs/models/run_a_model/run_access-cm2.md index 6441166be..59409c7e4 100644 --- a/docs/models/run_a_model/run_access-cm2.md +++ b/docs/models/run_a_model/run_access-cm2.md @@ -82,7 +82,7 @@ To open the terminal, click on the black terminal icon at the top of the window. ## Set up {{ model }} persistent session ---8<-- "includes/persistent_session.md +--8<-- "includes/persistent_session.md" ## Rose/Cylc/MOSRS setup From be5a615ee9da4b7e165a003091d4ad66b0d2d646 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Fri, 8 May 2026 21:50:10 +1000 Subject: [PATCH 3/9] simplify includes file for testing --- docs/includes/persistent_session.md | 72 +---------------------------- 1 file changed, 1 insertion(+), 71 deletions(-) diff --git a/docs/includes/persistent_session.md b/docs/includes/persistent_session.md index 455fc26d5..cdfada16a 100644 --- a/docs/includes/persistent_session.md +++ b/docs/includes/persistent_session.md @@ -1,71 +1 @@ -To support the use of long-running processes, such as ACCESS model runs, NCI provides a service on _Gadi_ called [persistent sessions](https://opus.nci.org.au/display/Help/Persistent+Sessions). - -To run {{ model }}, you need to start a persistent session and set it as the target session for the model run. - -### Start a new persistent session -To start a new persistent session on _Gadi_, using either a login node or an ARE terminal instance, run the following command: -``` -persistent-sessions start -``` - -This will start a persistent session with the given `name` that runs under your [default project](/getting_started/set_up_nci_account#change-default-project-on-gadi).
-If you want to assign a different project to the persistent session, use the option `-p`: -``` -persistent-sessions start -p -``` - -!!! tip - While the project assigned to a persistent session does not have to be the same as the project used to run the {{ model }} configuration, it does need to have allocated _Service Units (SU)_.
- For more information, check how to [Join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects). - - - persistent-sessions start <name> - session <persistent-session-uuid> running - connect using -  ssh <name>.<$USER>.<project>.ps.gadi.nci.org.au - - -To list all active persistent sessions run: -``` -persistent-sessions list -``` - - - persistent-sessions list -              UUID  PROJECT   ADDRESS    CPUTIME MEMORY - <persistent-session-uuid> <project> 10.9.0.62 00:00:05.213 30.5M - - - -The label of a newly-created persistent session has the following format:
-`.<$USER>..ps.gadi.nci.org.au`. - -### Specify {{ model }} target persistent session - -After starting the persistent session, it is essential to assign it to the {{ model }} run.
-The easiest way to do this is to insert the persistent session label into the file `~/.persistent-sessions/cylc-session`.
-You can do it manually, or by running the following command (by substituting `` with the name given to the persistent session, and `` with the project assigned to it): -``` -cat > ~/.persistent-sessions/cylc-session <<< ".${USER}..ps.gadi.nci.org.au" -``` - -For example, if the user `abc123` started a persistent session named `cylc` under the project `xy00`, the command will be: - - - cat > ~/.persistent-sessions/cylc-session <<< cylc.abc123.xy00.ps.gadi.nci.org.au - cat ~/.persistent-sessions/cylc-session - cylc.abc123.xy00.ps.gadi.nci.org.au - - -For more information on how to specify the target session, refer to [Specify Target Session with Cylc7 Suites](https://opus.nci.org.au/display/DAE/Run+Cylc7+Suites#RunCylc7Suites-SpecifyTargetSession). - -!!! tip - You can simultaneously submit multiple {{ model }} runs using the same persistent session without needing to start a new one. Hence, the process of specifying the target persistent session for {{ model }} should only be done once.
- After specifying the {{ model }} target persistent session the first time, to run {{ model }} you just need to make sure to have an active persistent session named like the specified {{ model }} target persistent session. - -### Terminate a persistent session -To stop a persistent session, run: -``` -persistent-sessions kill -``` -!!! warning - When you terminate a persistent session, any model running on that session will stop. Therefore, you should check whether you have any active model runs before terminating a persistent session. +This is just a test to see if this text will appear in the Run CM2 page. \ No newline at end of file From 0a283fae935713ceb2aab30e25c3c47efbeb6c76 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Fri, 8 May 2026 22:07:29 +1000 Subject: [PATCH 4/9] add base_path to snippets --- mkdocs.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index c47b1bddf..6a95b3010 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,7 +83,9 @@ markdown_extensions: - pymdownx.caret - pymdownx.mark - pymdownx.tilde - - pymdownx.snippets + - pymdownx.snippets: + base_path: docs + check_paths: true - pymdownx.highlight - pymdownx.tasklist: custom_checkbox: true From 54a5c2457039e3b88296d3e72dd3f125e4546de6 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Fri, 8 May 2026 22:37:12 +1000 Subject: [PATCH 5/9] add text back in for persistent sessions --- docs/includes/persistent_session.md | 72 ++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/docs/includes/persistent_session.md b/docs/includes/persistent_session.md index cdfada16a..455fc26d5 100644 --- a/docs/includes/persistent_session.md +++ b/docs/includes/persistent_session.md @@ -1 +1,71 @@ -This is just a test to see if this text will appear in the Run CM2 page. \ No newline at end of file +To support the use of long-running processes, such as ACCESS model runs, NCI provides a service on _Gadi_ called [persistent sessions](https://opus.nci.org.au/display/Help/Persistent+Sessions). + +To run {{ model }}, you need to start a persistent session and set it as the target session for the model run. + +### Start a new persistent session +To start a new persistent session on _Gadi_, using either a login node or an ARE terminal instance, run the following command: +``` +persistent-sessions start +``` + +This will start a persistent session with the given `name` that runs under your [default project](/getting_started/set_up_nci_account#change-default-project-on-gadi).
+If you want to assign a different project to the persistent session, use the option `-p`: +``` +persistent-sessions start -p +``` + +!!! tip + While the project assigned to a persistent session does not have to be the same as the project used to run the {{ model }} configuration, it does need to have allocated _Service Units (SU)_.
+ For more information, check how to [Join relevant NCI projects](/getting_started/set_up_nci_account#join-relevant-nci-projects). + + + persistent-sessions start <name> + session <persistent-session-uuid> running - connect using +  ssh <name>.<$USER>.<project>.ps.gadi.nci.org.au + + +To list all active persistent sessions run: +``` +persistent-sessions list +``` + + + persistent-sessions list +              UUID  PROJECT   ADDRESS    CPUTIME MEMORY + <persistent-session-uuid> <project> 10.9.0.62 00:00:05.213 30.5M + + + +The label of a newly-created persistent session has the following format:
+`.<$USER>..ps.gadi.nci.org.au`. + +### Specify {{ model }} target persistent session + +After starting the persistent session, it is essential to assign it to the {{ model }} run.
+The easiest way to do this is to insert the persistent session label into the file `~/.persistent-sessions/cylc-session`.
+You can do it manually, or by running the following command (by substituting `` with the name given to the persistent session, and `` with the project assigned to it): +``` +cat > ~/.persistent-sessions/cylc-session <<< ".${USER}..ps.gadi.nci.org.au" +``` + +For example, if the user `abc123` started a persistent session named `cylc` under the project `xy00`, the command will be: + + + cat > ~/.persistent-sessions/cylc-session <<< cylc.abc123.xy00.ps.gadi.nci.org.au + cat ~/.persistent-sessions/cylc-session + cylc.abc123.xy00.ps.gadi.nci.org.au + + +For more information on how to specify the target session, refer to [Specify Target Session with Cylc7 Suites](https://opus.nci.org.au/display/DAE/Run+Cylc7+Suites#RunCylc7Suites-SpecifyTargetSession). + +!!! tip + You can simultaneously submit multiple {{ model }} runs using the same persistent session without needing to start a new one. Hence, the process of specifying the target persistent session for {{ model }} should only be done once.
+ After specifying the {{ model }} target persistent session the first time, to run {{ model }} you just need to make sure to have an active persistent session named like the specified {{ model }} target persistent session. + +### Terminate a persistent session +To stop a persistent session, run: +``` +persistent-sessions kill +``` +!!! warning + When you terminate a persistent session, any model running on that session will stop. Therefore, you should check whether you have any active model runs before terminating a persistent session. From b31d663bf7a6075b6fa9014a6e0bd91789695825 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Sat, 9 May 2026 13:20:18 +1000 Subject: [PATCH 6/9] add render_by_default to test text variables --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 6a95b3010..6286349f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,7 @@ plugins: 'models/run_a_model/run_access-ram.md': 'models/run_a_model/run_access-ram3.md' - resolve-absolute-urls - macros + render_by_default: true # Extensions markdown_extensions: From 04cb277765cd3c2f5bad6e6548f7a61f3f04058f Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Sat, 9 May 2026 13:44:20 +1000 Subject: [PATCH 7/9] fix typo --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 6286349f0..19845740e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,7 @@ plugins: redirect_maps: 'models/run_a_model/run_access-ram.md': 'models/run_a_model/run_access-ram3.md' - resolve-absolute-urls - - macros + - macros: render_by_default: true # Extensions From 492fc41246b81b0ebd88fda920c90674ab12da93 Mon Sep 17 00:00:00 2001 From: Paige Martin Date: Sat, 9 May 2026 14:03:29 +1000 Subject: [PATCH 8/9] try using macros instead of snippets --- docs/models/run_a_model/run_access-cm2.md | 2 +- mkdocs.yml | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/models/run_a_model/run_access-cm2.md b/docs/models/run_a_model/run_access-cm2.md index 59409c7e4..15da92297 100644 --- a/docs/models/run_a_model/run_access-cm2.md +++ b/docs/models/run_a_model/run_access-cm2.md @@ -82,7 +82,7 @@ To open the terminal, click on the black terminal icon at the top of the window. ## Set up {{ model }} persistent session ---8<-- "includes/persistent_session.md" +{% include "persistent_session.md" %} ## Rose/Cylc/MOSRS setup diff --git a/mkdocs.yml b/mkdocs.yml index 19845740e..eaffb8986 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,7 +70,7 @@ plugins: 'models/run_a_model/run_access-ram.md': 'models/run_a_model/run_access-ram3.md' - resolve-absolute-urls - macros: - render_by_default: true + include_dir: docs/includes # Extensions markdown_extensions: @@ -84,9 +84,7 @@ markdown_extensions: - pymdownx.caret - pymdownx.mark - pymdownx.tilde - - pymdownx.snippets: - base_path: docs - check_paths: true + - pymdownx.snippets - pymdownx.highlight - pymdownx.tasklist: custom_checkbox: true From b82c61e66040f1d0157485a3403672fb02ba29c7 Mon Sep 17 00:00:00 2001 From: Claire Carouge Date: Mon, 11 May 2026 17:16:33 +1000 Subject: [PATCH 9/9] Test includes in admonition --- docs/includes/cylc_warning.md | 3 +++ docs/models/run_a_model/run_access-cm2.md | 4 +--- 2 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 docs/includes/cylc_warning.md diff --git a/docs/includes/cylc_warning.md b/docs/includes/cylc_warning.md new file mode 100644 index 000000000..43946f2a1 --- /dev/null +++ b/docs/includes/cylc_warning.md @@ -0,0 +1,3 @@ + _Cylc_ version >= `cylc7/24.03` required.
+ + Also, before loading the _Cylc_ module, make sure to have started a _persistent session_ and have assigned it to the {{ model }} workflow. For more information about these steps, refer to [Set up {{ model }} persistent session]({{ '#set-up-%s-persistent-session'%model.lower() }}). diff --git a/docs/models/run_a_model/run_access-cm2.md b/docs/models/run_a_model/run_access-cm2.md index 15da92297..e21334b20 100644 --- a/docs/models/run_a_model/run_access-cm2.md +++ b/docs/models/run_a_model/run_access-cm2.md @@ -107,9 +107,7 @@ module load cylc7 !!! warning - _Cylc_ version >= `cylc7/24.03` required.
- - Also, before loading the _Cylc_ module, make sure to have started a _persistent session_ and have assigned it to the {{ model }} workflow. For more information about these steps, refer to [Set up {{ model }} persistent session]({{ '#set-up-%s-persistent-session'%model.lower() }}). +{% include "cylc_warning.md" %} ### Rose setup {: #rose } [Rose](https://metomi.github.io/rose/doc/html/index.html) is a toolkit that can be used to view, edit, or run an ACCESS modelling suite.