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/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..e21334b20 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. +{% include "persistent_session.md" %} ## Rose/Cylc/MOSRS setup @@ -176,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. diff --git a/mkdocs.yml b/mkdocs.yml index c47b1bddf..eaffb8986 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,8 @@ plugins: redirect_maps: 'models/run_a_model/run_access-ram.md': 'models/run_a_model/run_access-ram3.md' - resolve-absolute-urls - - macros + - macros: + include_dir: docs/includes # Extensions markdown_extensions: