-
+
Atmosphere
-
+
Land
-
+
Ocean
-
+
Sea Ice
-
+
Aerosols
-
+
Atmospheric Chemistry
-
+
Biogeochemistry Land
-
+
Biogeochemistry Ocean
-
+
Coupler
diff --git a/docs/models/model_components/aerosols_atmospheric_chemistry.md b/docs/models/model_components/aerosols_atmospheric_chemistry.md
index 8479d6b8e..ab08f04ab 100644
--- a/docs/models/model_components/aerosols_atmospheric_chemistry.md
+++ b/docs/models/model_components/aerosols_atmospheric_chemistry.md
@@ -4,9 +4,9 @@
-
+
-##
[UKCA][ukca-wiki]
+## [UKCA][ukca-wiki]
The [UK Chemistry-Aerosol model (UKCA)][ukca-wiki] is a community atmospheric chemistry-aerosol global model developed in the United Kingdom. It is suitable for a range of topics in climate and environmental change research.
@@ -16,7 +16,7 @@ UKCA chemistry model is enabled in ACCESS-CM2-Chem.
-##
[GLOMAP][glomap-wiki]
+## [GLOMAP][glomap-wiki]
UKCA contains an aerosol scheme [GLObal Model of Aerosol Processes (GLOMAP)][glomap-wiki] that can be used independently. The multi-component, multi-modal GLOMAP model allows simulation of aerosol number, size and concentrations of individual components such as sulphate,sea salt and different types of carbon.
diff --git a/docs/models/model_components/atmosphere.md b/docs/models/model_components/atmosphere.md
index 3ccb7c25d..c310aedfd 100644
--- a/docs/models/model_components/atmosphere.md
+++ b/docs/models/model_components/atmosphere.md
@@ -4,32 +4,25 @@
-
+
-##
The Unified Model (UM)
+## The Unified Model (UM)
-[The Unified Model (UM)][um-web] is a numerical model of the atmosphere used for both weather and climate applications, developed by the [Met Office][metoffice-web] in the United Kingdom (UK). It includes solutions of the equations of atmospheric fluid dynamics with advanced parameterizations of subgrid-scale physical processes like convection, cloud formation and atmospheric radiation.
-
-The Unified Model gets its name because a single model is used across a wide range of both timescales (nowcasting to centennial) and spatial scales (sub km convective scale to global climate modelling).
-
-The UM is used by several international operational meteorology and research organizations and these contribute towards its development through the UM partnership.
+The UK Met Office [Unified Model (UM)][um-web] is a numerical model of the atmosphere used for both weather and climate applications across a wide range of time scales (nowcasting to centennial) and spatial scales (sub km convective scale to global). The UM includes solutions of the equations of atmospheric fluid dynamics with advanced parameterisations of physical processes like convection, cloud formation and atmospheric radiation.
## How is the UM used?
-The UM Model component represents the atmosphere in many of the ACCESS Models used at regional and global scales.
-
-The ACCESS-CM2 climate model and ACCESS-ESM1-5 earth system model use versions of the UM as their atmospheric components.
+The UM is the atmospheric component in many of the ACCESS models used at regional and global scales, e.g. the [ACCESS-CM](../configurations/access-cm.md) and [ACCESS-ESM](../configurations/access-esm.md) global climate models.
-[The Australian Bureau of Meteorology][bom-web] operational 12 km spatial resolution global forecasting system uses the Unified Model, as part of ACCESS for:
+The Australian Bureau of Meteorology (BoM) uses the UM in its suite of ACCESS forecast systems for [daily and seasonal weather][bom-forecasts] as well as extreme events and emergencies (e.g., bushfires, cyclones, floods, coral bleaching, coastal inundation, etc.).
-- Forecasting of extreme events and emergencies such as heatwaves, bushfires, cyclones, floods, coral bleaching, sea-level rise, coastal inundation and more.
-- Daily and seasonal weather forecasts
+The UM is used by several international operational meteorology and research organisations, and these contribute towards its development through the [UM partnership][metoffice-web].
-## Useful links
-
-[STASH register](metoffice-stash-register): Metadata reference for the outputs variables.
+
[um-web]: https://www.metoffice.gov.uk/research/approach/modelling-systems/unified-model
-[bom-web]: http://www.bom.gov.au/
[metoffice-web]: https://www.metoffice.gov.uk/research/approach/collaboration/unified-model/partnership
-[metoffice-stash-register]: https://reference.metoffice.gov.uk/um/_stash
+[bom-forecasts]: http://www.bom.gov.au/australia/charts/viewer/
diff --git a/docs/models/model_components/bgc_land.md b/docs/models/model_components/bgc_land.md
index 86ee66a21..704ec200c 100644
--- a/docs/models/model_components/bgc_land.md
+++ b/docs/models/model_components/bgc_land.md
@@ -5,9 +5,9 @@
-
+
-##
[CASA-CNP][casa-web]
+## [CASA-CNP][casa-web]
[CASA-CNP][casa-web], the Carnegie-Ames-Stanford Approach with Carbon-Nitrogen-Phosphorus, is the biogeochemical module implemented in the ACCESS land surface model [CABLE][cable-wiki]. It models the dynamics of carbon pools and the dependance of carbon uptake due to nitrogen and phosphorous limitations.
diff --git a/docs/models/model_components/bgc_ocean.md b/docs/models/model_components/bgc_ocean.md
index 638902b65..ae589df8e 100644
--- a/docs/models/model_components/bgc_ocean.md
+++ b/docs/models/model_components/bgc_ocean.md
@@ -4,15 +4,14 @@
-
+
##
WOMBAT
-WOMBAT is the ocean carbon model (World Ocean Model of Biogeochemistry And Trophic-dynamics), developed in Australia. It calculates the carbon fluxes of the ocean, by simulating the evolution of phosphate, oxygen, dissolved inorganic carbon, alkalinity and iron with one class of phytoplankton and zooplankton.
-WOMBAT is a Nutrient, Phytoplankton, Zooplankton and Detritus (NPZD) model, with one zooplankton and one phytoplankton class.
+The World Ocean Model of Biogeochemistry And Trophic-dynamics (WOMBAT) is the ocean biogeochemistry module added to ACCESS models. The core of WOMBAT is a Nutrient, Phytoplankton, Zooplankton and Detritus (NPZD) cycle. WOMBAT simulates the evolution of open-ocean phosphate, oxygen, dissolved inorganic carbon, alkalinity, iron and carbon fluxes with one zooplankton and one phytoplankton class.
### How is WOMBAT used?
+WOMBAT is applied as a tracer package in the ACCESS ocean model [MOM5][mom5-github]. In the ACCESS-OM2 configuration, WOMBAT is used in MOM5 and coupled with sea ice biogeochemistry. WOMBAT is also applied in [MOM5 of the ACCESS-ESM1.5 configuration][MOM5-esm-code] used for CMIP6.
-WOMBAT is [coupled to the MOM5 ocean model][MOM5-WOMBAT-code] in the ACCESS-ESM1.5 and ACCESS-OM2 models.
-
-[MOM5-WOMBAT-code]: https://github.com/COSIMA/ACCESS-ESM1.5-MOM5
+[mom5-github]: https://github.com/mom-ocean/MOM5
+[MOM5-esm-code]: https://github.com/COSIMA/ACCESS-ESM1.5-MOM5
diff --git a/docs/models/model_components/coupler.md b/docs/models/model_components/coupler.md
index f36a6d52d..8c8c20798 100644
--- a/docs/models/model_components/coupler.md
+++ b/docs/models/model_components/coupler.md
@@ -1,12 +1,12 @@
-#
Coupler
+#
Coupler
-
+
A coupler is a software package that allows synchronised exchanges of coupling information between numerical codes representing different components of the climate system.
-##
[OASIS3-MCT][OASIS3-MCT]
+## [OASIS3-MCT][OASIS3-MCT]
[OASIS3-MCT][OASIS3-MCT] is the version of the Ocean Atmosphere Sea Ice Soil (OASIS) coupler interfaced with the Model Coupling Toolkit (MCT) from the Argonne National Laboratory. OASIS3-MCT is the coupler used in the configurations:
@@ -15,7 +15,7 @@ A coupler is a software package that allows synchronised exchanges of coupling i
- ACCESS-OM2
- ACCESS-S
-##
[NUOPC interoperability layer][NUOPC]
+## [NUOPC interoperability layer][NUOPC]
[NUOPC][NUOPC-int-layer] (National Unified Operational Prediction Capability) Interoperability Layer defines conventions and a set of generic components for building coupled models using the Earth System Modeling Framework (ESMF).
diff --git a/docs/models/model_components/index.md b/docs/models/model_components/index.md
index ee36b8c5d..81bcef79e 100644
--- a/docs/models/model_components/index.md
+++ b/docs/models/model_components/index.md
@@ -1,70 +1,70 @@
#
Model Components
-ACCESS components represent different chemical, physical or biological parts of the Earth System.
+ACCESS model components represent different chemical, physical or biological parts of the Earth System.
-Most model components have originated from collaborations with international research groups. These include:
+Most of these model components have originated from collaborations with international research groups, such as:
-- [UK Met Office][met-office-web] → Unified Model (UM) atmospheric component.
-- [NOAA/ Geophysical Fluid Dynamics Laboratory (GFDL)][noaa-gfdl-web] → Modular Ocean Model (MOM) component.
-- [Los Alamos National Laboratory (LANL)][lanl-web] → Sea ice model (CICE) component.
-- [Centre Européen de Recherche et de Formation Avancée en Calcul Scientifique (CERFACS)][cerfacs-web] → Ocean-Atmosphere-Sea Ice-Snowpack Model Coupling Toolkit (OASIS3-MCT).
-- [United Kingdom Chemistry and Aerosols (UKCA)][ukca-web] → UK community atmospheric Chemistry-Aerosol (UKCA) model.
-- [CSIRO][csiro-web], [COSIMA][cosima-web] and [CLEX][clex-web] → Community Atmosphere Biosphere Land Exchange (CABLE), Whole Ocean Model with Biogeochemistry And Trophic-dynamics (WOMBAT) and land biogeochemistry Carnegie–Ames–Stanford-Approach (CASA) models. These models have been developed in Australia.
+- [UK Met Office][met-office-web]: UM atmospheric model.
+- [NOAA/ GFDL][noaa-gfdl-web]: MOM ocean model.
+- [LANL][lanl-web]: CICE sea ice model.
+- [CERFACS][cerfacs-web]: OASIS3-MCT coupling software package.
+- [UKCA][ukca-web]: UKCA atmospheric chemistry-aerosol model.
+- [CSIRO][csiro-web], [COSIMA][cosima-web], [CLEX][clex-web]: CABLE land surface model, WOMBAT ocean biogeochemistry package and CASA land biogeochemistry model; all developed in Australia.
[met-office-web]: https://www.metoffice.gov.uk/
[noaa-gfdl-web]: https://www.gfdl.noaa.gov/
diff --git a/docs/models/model_components/land.md b/docs/models/model_components/land.md
index 9406427c7..b8f393083 100644
--- a/docs/models/model_components/land.md
+++ b/docs/models/model_components/land.md
@@ -4,15 +4,15 @@
-
+
-##
[CABLE][cable-wiki]
+## [CABLE][cable-wiki]
-[Community Atmosphere Biosphere Land Exchange (CABLE)][cable-web] is a land surface model, used to calculate the fluxes of momentum, energy, water and carbon between the land surface and the atmosphere. It also models the main biogeochemical cycles of the land ecosystem when used in conjunction with [the CASA-CNP module][casa-cnp].
+[Community Atmosphere Biosphere Land Exchange (CABLE)][cable-web] is a land surface model used to calculate the fluxes of momentum, energy, water and carbon between the land surface, vegetation canopy and the atmospheric boundary layer. It also includes descriptions of thermal and hydrological processes in the soil and snow, and models the main biogeochemical cycles of the land ecosystem when used in conjunction with the [CASA-CNP][casa-cnp] module.
### How is CABLE used?
-CABLE can be run as a standalone model, for a single location, a region or globally. Coupled to the Met Office [Unified Model (UM)](um-web), CABLE provides the land surface component of the ACCESS Earth System Model (ACCESS-ESM) and ACCESS Coupled Model (ACCESS-CM).
+CABLE provides the land surface component of the ACCESS Earth System Model (ACCESS-ESM) and the ACCESS Coupled Model (ACCESS-CM). Directly coupled into the [Unified Model (UM)](um-web), CABLE replaces relevant parts of the functionality of the UM’s own land surface scheme (JULES). CABLE can also be run as a standalone model, for a single location, a region or globally.
CABLE is an open source model developed by a community of Australian climate science researchers. [Registration][cable-wiki] is required to access the CABLE code repository.
@@ -20,7 +20,7 @@ CABLE is an open source model developed by a community of Australian climate sci
[um-web]: https://www.metoffice.gov.uk/research/approach/modelling-systems/unified-model
-##
[JULES][jules-web]
+## [JULES][jules-web]
The [Joint UK Land Environment System (JULES)](jules-web) is a community land surface model that can be used both as a standalone model and as the land surface component in the UM model. By modelling different land surface processes (surface energy balance, hydrological cycle, carbon cycle, dynamic vegetation, etc.) and their interaction with each other, JULES provides a framework to assess the impact of modifying a particular process on the ecosystem as a whole, e.g., the impact of climate change on hydrology.
diff --git a/docs/models/model_components/ocean.md b/docs/models/model_components/ocean.md
index 4a9f5ffe8..0bd11f001 100644
--- a/docs/models/model_components/ocean.md
+++ b/docs/models/model_components/ocean.md
@@ -4,20 +4,20 @@
-
+
-##
[Modular Ocean Model (MOM)][mom-wiki]
+## [Modular Ocean Model (MOM)][mom-wiki]
The [Modular Ocean Model (MOM)][mom-wiki] is one of the ocean components of the ACCESS climate model system. Used to simulate ocean currents at both regional and global scales, MOM is an invaluable tool for studying the global ocean climate system, as well as capabilities for regional and coastal applications.
MOM is an open source development by a consortium of scientists across several government agencies and academic institutions worldwide.
-###
MOM5
+### MOM5
[**Source Code**][mom5-github]
MOM5 is used in supported configurations, such as ACCESS-OM2, ACCESS-CM2 and ACCESS-ESM1.5.
-###
MOM6
+### MOM6
[**Source Code**][mom6-github] |
[**Tutorials**][mom6-tutes]
diff --git a/docs/models/model_components/sea-ice.md b/docs/models/model_components/sea-ice.md
index c7f39993e..119ec3d69 100644
--- a/docs/models/model_components/sea-ice.md
+++ b/docs/models/model_components/sea-ice.md
@@ -4,9 +4,9 @@
-
+
-##
CICE
+## CICE
CICE is a numerical model for simulating the growth, melting and movement of polar sea ice. This software package was developed by researchers at [Los Alamos National Laboratory team][lanl-web] and is currently managed by the [CICE Consortium][cice-web], an international group of institutions formed to maintain and develop CICE in the public domain.
[CICE5][cice5-wiki] is the current version used in ACCESS model configurations.
diff --git a/docs/models/run-a-model/getting_started/access_to_gadi_at_nci.md b/docs/models/run-a-model/getting_started/access_to_gadi_at_nci.md
deleted file mode 100644
index 1d6055d7a..000000000
--- a/docs/models/run-a-model/getting_started/access_to_gadi_at_nci.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-hide:
- - toc
----
-
-#
Getting Started: Computing Access (Gadi@NCI)
-
-Here, we provide you the important information to give you access to the large data that we curate at NCI's storage:
-
-1) [Get an NCI Account](#1-nci-account)
-2) [Join relevant NCI projects](#2-join-relevant-nci-projects)
-3) [Logging in to Gadi@NCI](#3-logging-in-to-gadinci)
-4) [Computing on Gadi](#4-computing-on-gadi)
-
-## 1) NCI Account
-
-To be able to work with our data, you need an NCI account.
-
-If you don't have one yet, [signup here](https://my.nci.org.au/mancini/signup/0).
-
-Note: You will need an institutional email address with an organisation that allows access to NCI (e.g., CSIRO, a university, etc.).
-
-Once you have signed up, you will be allocated a username. We will refer to this username (e.g. `kf1234`) as `$USER`.
-
-## 2) Join relevant NCI projects
-
-There is a plethora of NCI projects that may or may not be relevant for you.
-
-We recommend you have a chat with your supervisor to identify the relevant projects, but in any case suggest to join `xp65` for MED code as well as `kj13` for MED data.
-
-To get this conversation started, we list some possibly relevant projects below:
-
-| Project | Description with link, * indicated compute resource|
-|------|---------------------------------------------------------------------------------------------------------------------------------|
-| | *ACCESS-NRI projects* |
-| tm70 |
ACCESS-NRI Working Project * |
-| iq82 |
ACCESS-NRI MED Compute * |
-| kj13 |
ACCESS-NRI MED Data Dev |
-| ct11 |
ACCESS-NRI Replicated Datasets |
-| xp65 |
ACCESS-NRI Analysis Environments |
-| | *ACCESS projects* |
-| access |
ACCESS software sharing |
-| p66 |
ACCESS - AOGCM / suppport development of the ACCESS modelling system * |
-| p73 |
ACCESS Model Output Archive (AOGCM) |
-| | *Data projects* |
-| hh5 |
Climate-LIEF Data Storage |
-| ub7 |
Seasonal Prediction ACCESS-S1 Hindcast |
-| ux62 |
Seasonal Prediction ACCESS-S2 Hindcast |
-| cb20 |
ESGF CMIP3 Replication Data |
-| al33 |
ESGF CMIP5 Replication Data |
-| rr3 |
ESGF CMIP5 Australian Data Publication |
-| oi10 |
ESGF CMIP6 Replication Data |
-| fs38 |
ESGF CMIP6 Australian Data Publication |
-| rt52 |
ERA5 Replicated Data: Single and pressure-levels data |
-| uc16 |
ERA5 Replicated Datasets on Potential Temperature & Vorticity Levels |
-| zz93 |
ERA5-Land Replicated Data |
-| zv2 |
Australian Gridded Climate Data (AGCD) Collection |
-| qv56 |
Reference Datasets for Climate Model Analysis/Forcing |
-| cj50 |
COSIMA Model Output Collection |
-| | *Other projects* |
-| ik11 |
COSIMA shared working space |
-| v45 |
Ocean Extremes * |
-| ga6 |
Modelling the formation of sedimentary basins and continental margins * |
-| m18 |
Evolution and dynamics of the Australian lithosphere * |
-| q97 |
Earth dynamics and resources over the last billion years * |
-| qu79 |
Collaborative REAnalysis Technical Environment Intercomparison Project (CREATE-IP) |
-
-To join a project or find more projects, please use this [NCI website](https://my.nci.org.au/mancini/project-search).
-
-The first project that you join will become your default login project, e.g. `xp65`. We will refer to it as `$PROJECT` and we show you how to change it below.
-
-## 3) Logging in to Gadi@NCI
-
-If you have never logged onto Gadi before, we recommend to take a look at NCI's [Welcome to Gadi website](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi).
-It provides all the important commands and information for logging properly onto Gadi, like the following:
-"To run jobs on Gadi, you need to first log in to the system. Users on Mac/Linux can use the built-in terminal. For Windows users, we recommend using [MobaXterm](https://mobaxterm.mobatek.net/) as the local terminal. Logging in to Gadi happens through a Gadi login node."
-
-When you login, via the command
-```
-ssh -Y $USER@gadi.nci.org.au
-```
-you will enter your $HOME directory with your default `$PROJECT` and your default SHELL. Both are saved at `$HOME/.config/gadi-login.conf` and you can print them via
-```
-cat $HOME/.config/gadi-login.conf
-```
-
-The `-Y` option is needed to run graphical tools by enabling the forwarding of trusted X protocol mesgs between X-Server on local system and X programs on Gadi.
-You need to enable X Windowing system on your local system before running ssh. This can be done by running X-Server like XQuartz (Mac), MobaXterm (MS Windows), startx or similar (Linux).
-
-Again, for more useful information we recommend to check out NCI's [Welcome to Gadi website](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi).
-
-## 4) Computing on Gadi
-
-### Gadi Resources
-Coupled climate models like ACCESS-CM involve, among other things, calculation of complex mathematical equations that explain the physics of the atmosphere and oceans. Performed at hundreds of millions of points around the Earth, these calculations require vast computing power to complete them in a reasonable amount of time, thus relying on the power of high-performance computing (HPC) like Gadi. The [Gadi supercomputer](https://nci.org.au/our-systems/hpc-systems) can handle more than 10 million billion (10 quadrillion) calculations per second and is connected to 100,000 Terabytes of high-performance research data storage.
-
-An overview of [Gadi resources](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-GadiResources) such as compute, storage and PBS jobs are described below.
-
-Useful NCI commands to check your available compute resources are:
-
-| Command | Purpose |
-| ---------------------- | ------------- |
-| `logout` or ++ctrl+"D"++ | To exit a session |
-| `hostname` | Displays login node details|
-| `module list` | Modules currently loaded |
-| `module avail` | Available modules |
-| `nci_account -P [proj]`| Compute allocation for [proj]|
-| `nqstat -P [proj]` | Jobs running/queued in [proj]|
-| `lquota` | Storage allocation and usage for all your projects|
-
-#### Compute Hours
-Compute allocations are granted to projects instead of directly to users and, hence, you need to be a member of a project in order to use its compute allocation. To run jobs on Gadi, you need to have sufficient allocated [compute hours](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-ComputeHours) available, where the [job cost](https://opus.nci.org.au/display/Help/2.+Compute+Grant+and+Job+Debiting) depends on the resources reserved for the job and the amount of walltime it uses.
-
-#### Storage
-Each user has a project-independent [`$HOME`](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-TheHomeFolder$HOME) directory, which has a storage limit of 10 GiB. All data on `/home` is backed up.
-
-Through project membership, the user gets access to the storage space within the
-[project folders](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-ProjectFolderonLustreFilesystems/scratchand/g/data) `/scratch` and `/g/data` filesystems for that particular project.
-
-#### PBS Jobs
-To run compute tasks such as an ACCESS-CM suite on Gadi, users need to submit them as *jobs* to *queues*. Within a [job submission](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-JobSubmission), you can specify the queue, duration and computational resources needed for your job. When a job submission is accepted, it is assigned a jobID (shown in the return message) that can then be used to monitor the job’s [status](https://opus.nci.org.au/display/Help/0.+Welcome+to+Gadi#id-0.WelcometoGadi-QueueStatus).
-
-On job completion, contents of the job’s standard output/error stream gets copied to a file in the working directory with the respective format: `
.o` and `.e`. Users should check these two log files before proceeding with post-processing of any output from their corresponding job.
diff --git a/docs/models/run-a-model/getting_started/index.md b/docs/models/run-a-model/getting_started/index.md
deleted file mode 100644
index 3dfd72dd1..000000000
--- a/docs/models/run-a-model/getting_started/index.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Getting Started to Run a Model
-
-If *Model*, *Model Component* or *Model Configuration* are not familiar terms for you, please check out our [Model overview](../index.md).
-
-If you have not run a model before, our [Getting Started Guide](./access_to_gadi_at_nci.md) will give you the basics to access the Model infrastructure on the high-performance-computing facility Gadi@NCI.
-
-Detailed guides for the different Model configurations can then be found on the following pages:
-- [Run ACCESS-ESM](../run-access-esm.md) for the ACCESS Earth System Model configurations
-- [Run ACCESS-CM](../run-access-cm.md) for the ACCESS Coupled Model configurations
-- [Run ACCESS-AM](../run-access-am.md) for the ACCESS Atmosphere Model configurations
-- [Run ACCESS-OM](../run-access-om.md) for the ACCESS Ocean Model configurations
\ No newline at end of file
diff --git a/docs/models/run-a-model/index.md b/docs/models/run-a-model/index.md
index d4e3ff664..291596f83 100644
--- a/docs/models/run-a-model/index.md
+++ b/docs/models/run-a-model/index.md
@@ -1,13 +1,40 @@
# Run a Model
+If you are new to climate science or ACCESS Models, check [how to get started](../../../get_started).
-Here, we are providing the information to run different ACCESS models.
+If you are not sure which ACCESS Model is the right one for your needs, check out our
+[ACCESS Models overview](../).
-If *Model*, *Model Component* or *Model Configuration* are not familiar terms for you, please check out our [Model overview](../index.md).
-
-If you have not run a model before, our [Getting Started Guide](./getting_started/access_to_gadi_at_nci.md) will give you the basics to access the Model infrastructure on the high-performance-computing facility Gadi@NCI.
-
-Detailed guides for the different Model configurations can then be found on the following pages:
-- [Run ACCESS-ESM](./run-access-esm.md) for the ACCESS Earth System Model configurations
-- [Run ACCESS-CM](./run-access-cm.md) for the ACCESS Coupled Model configurations
-- [Run ACCESS-AM](./run-access-am.md) for the ACCESS Atmosphere Model configurations
-- [Run ACCESS-OM](./run-access-om.md) for the ACCESS Ocean Model configurations
\ No newline at end of file
+
diff --git a/docs/models/run-a-model/run-access-cm.md b/docs/models/run-a-model/run-access-cm.md
index daaab6790..35b2f3a4f 100644
--- a/docs/models/run-a-model/run-access-cm.md
+++ b/docs/models/run-a-model/run-access-cm.md
@@ -2,22 +2,17 @@
# Run {{ model }}
## Requirements
-
Before running {{ model }}, you need to make sure to possess the right tools and to have an account with specific institutions.
-
### General requirements
-
### Model-specific requirements
-
-
Join the access project at NCI
- To join the access project at NCI, request membership for it on the NCI access project page.
+ To join the access project at NCI, request membership for it on the access NCI project page.
For more information on how to join specific NCI projects, please refer to How to connect to a project.
@@ -26,7 +21,7 @@ For the general requirements needed to run all ACCESS models, please refer to th
To run {{ model }} you need the connection to accessdev, an NCI server providing configuration and run control for {{ model }}.
- Also, you need to make sure there is correct communication between accessdev and gadi.
+ Also, you need to make sure there is correct communication between accessdev and Gadi.
To complete these steps, you can follow the guides on SSH connections on accessdev.
@@ -38,24 +33,19 @@ For the general requirements needed to run all ACCESS models, please refer to th
To apply for a MOSRS account, please contact your local institutional sponsor.
-
--------------------------------------------
## Get {{ model }} suite
-
{{ model }} is a set of submodels (e.g. UM, MOM, CICE, CABLE, OASIS) with a range of model parameters, input data, and computer related information, that need to be packaged together as a suite in order to run.
Each {{ model }} suite has an ID, in the format u-<suite-name>
, with <suite-name>
being a unique identifier (e.g. u-br565
is the CMIP6 release preindustrial experiment suite).
Typically, an existing suite is copied and then edited as needed for a particular run.
-
### Copy {{ model }} suite with Rosie
-
Rosie is an
SVN repository wrapper with a set of options to work with {{ model }} suites.
To copy an existing suite, on
accessdev:
-
-
Run
@@ -105,22 +95,21 @@ The suite directory usually contains 2 subdirectories and 3 files:
app meta rose-suite.conf rose-suite.info suite.rc
-
----------------------------------------------------------------------------------------
## Edit {{ model }} suite configuration
### Rose
-
Rose is a configuration editor which can be used to view, edit, or run an {{ model }} suite.
To edit a suite configuration, on
accessdev:
-
From inside the relevant suite directory (e.g.
~/roses/<suite-ID>
), run
rose edit &
to open the
Rose GUI and inspect the suite information.
-
Note: the
&
is optional and keeps the terminal prompt active while runs the GUI as a separate process.
+
+ The &
is optional and keeps the terminal prompt active while runs the GUI as a separate process.
+
cd ~/roses/<suite-ID>
rose edit &
@@ -128,20 +117,18 @@ to open the Rose GUI and inspect the suite information.
-
### Change NCI project
-
To make sure we run the suite under the NCI project we belong to, we can navigate to
suite conf → Machine and Runtime Options, edit the
Compute project field, and click the
Save button
. (Check
how to connect to a project if you have not joined one yet).
For example, to run {{ model }} under the
tm70
project (ACCESS-NRI), we will insert
tm70
in the
Compute project field:
-
Note: You should be part of a project with allocated
Service Units (SU) to be able to run {{ model }}. For more information please check
(TO DO reference projects).
+
+ You should be part of a project with allocated
Service Units (SU) to be able to run {{ model }}. For more information please check
(TO DO reference projects).
### Change run length and cycling frequency
-
{{ model }} suites are often run in multiple steps, each of them constituting a cycle, with the job scheduler resubmitting the suite every chosen
Cycling frequency, until the
Total Run length is met.
To modify these parameters, we can navigate to
suite conf → Run Initialisation and Cycling, edit the respective fields, and click the
Save button
. The values are in the
ISO 8601 Duration format.
@@ -149,10 +136,8 @@ To modify these parameters, we can navigate to
suite conf → Run Initiali
If, for example, we want to run the suite for a total of 50 Years, and resubmit every year, we will change Total Run length to P50Y
and Cycling frequency to P1Y
. Note that the current maximum Cycling frequency is 2 years:
-
### Change wallclock time
-
The
Wallclock time is the time requested by the PBS job to run a single cycle. If this time is not enough for the suite to end its cycle, our job will be terminated before the suite can complete the run.
If we change the
Cycling frequency, we might need to change the
Wallclock time accordingly.
@@ -162,21 +147,16 @@ The time needed for the suite to run a full cycle depends on several factors, bu
To modify the
Wallclock time, we can navigate to
suite conf → Run Initialisation and Cycling, edit the respective field, and click the
Save button
. The value is in the
ISO 8601 Duration format.
-
----------------------------------------------------------------------------------------
## Run {{ model }} suite
-
-
-{{ model }} suites run on
gadi through a PBS job submission.
+{{ model }} suites run on
Gadi through a PBS job submission.
-When the suite gets run, its configuration files are copied on gadi under
/scratch/$PROJECT/$USER/cylc-run/<suite-ID>
, and a symbolic link to this folder is also created in the
$USER
's home directory under
~/cylc-run/<suite-ID>
.
+When the suite gets run, its configuration files are copied on
Gadi under
/scratch/$PROJECT/$USER/cylc-run/<suite-ID>
, and a symbolic link to this folder is also created in the
$USER
's home directory under
~/cylc-run/<suite-ID>
.
An {{ model }} suite is constituted by several tasks (such as checking out code repositories, compiling and building the different model components, running the model, etc.). The workflow of these tasks is controlled by
Cylc.
-
### Cylc
-
Cylc (pronounced ‘silk’), is a workflow manager that automatically executes tasks according to the model main cycle script
suite.rc
.
Cylc deals with how the job will be run and manages the time steps of each submodel, as well as monitoring all the tasks and reporting any error that might occur.
To run an {{ model }} suite, on
accessdev:
@@ -236,19 +216,20 @@ To run an {{ model }} suite, on
accessdev:
[INFO] $ ps -opid,args <PID> # on accessdev.nci.org.au
-
-
Note: If after you run the command
rose suite-run
you get an error similar to the following:
-
[FAIL] Suite "<suite-ID>" appears to be running:
- [FAIL] Contact info from: "/home/565/<$USER>/cylc-run/<suite-ID>/.service/contact"
- [FAIL] CYLC_SUITE_HOST=accessdev.nci.org.au
- [FAIL] CYLC_SUITE_OWNER=<$USER>
- [FAIL] CYLC_SUITE_PORT=<port>
- [FAIL] CYLC_SUITE_PROCESS=<PID> python2 /usr/local/cylc/cylc-7.8.3/bin/cylc-run <suite-ID>
- [FAIL] Try "cylc stop '<suite-ID>'" first?
-
- you should run
-
rm /home/565/<$USER>/cylc-run/<suite-ID>/.service/contact
- before running the
rose suite-run
command again.
+
+ If after you run the command
rose suite-run
you get an error similar to the following:
+
[FAIL] Suite "<suite-ID>" appears to be running:
+ [FAIL] Contact info from: "/home/565/<$USER>/cylc-run/<suite-ID>/.service/contact"
+ [FAIL] CYLC_SUITE_HOST=accessdev.nci.org.au
+ [FAIL] CYLC_SUITE_OWNER=<$USER>
+ [FAIL] CYLC_SUITE_PORT=<port>
+ [FAIL] CYLC_SUITE_PROCESS=<PID> python2 /usr/local/cylc/cylc-7.8.3/bin/cylc-run <suite-ID>
+ [FAIL] Try "cylc stop '<suite-ID>'" first?
+
+ you should run
+
rm /home/565/<$USER>/cylc-run/<suite-ID>/.service/contact
+ before running the
rose suite-run
command again.
+
You are done!!
@@ -258,14 +239,10 @@ Note that, at this stage, it is possible to close the
Cylc GUI.
If you want to open it again, from inside the suite directory run
rose suite-gcontrol
-
-
----------------------------------------------------------------------------------------
## Monitor {{ model }} runs
### Check for errors
-
-
It is quite common, especially during the first few runs, to experience errors and job failures. An {{ model }} suite is constituted by several tasks, and each of these tasks could fail. When a task fails, the suite is halted and you will see a red icon next to the respective task name in the Cylc GUI.
To investigate the cause of a failure, we need to look at the logs (job.err
and job.out
) from the suite run. There are two main ways to do so:
@@ -313,13 +290,9 @@ To investigate the cause of a failure, we need to look at the logs (job.er
-
-
----------------------------------------------------------------------------------------
## Stop, restart and reload suites
-
-
Sometimes, you may want to control the running state of a suite.
If your
Cylc GUI has been closed and you are unsure whether your suite is still running, you can scan for active suites and reopen the GUI if desired.
@@ -335,10 +308,8 @@ To reopen the
Cylc GUI, from inside the suite directory run
rose suite-gcontrol
-
### STOP a suite
-
To shutdown a suite in a safe manner, from inside the suite directory run
rose suite-stop -y
Alternatively, you can directly kill the PBS job(s) connected to your run. To do so:
@@ -352,10 +323,8 @@ Alternatively, you can directly kill the PBS job(s) connected to your run. To do
qdel <job-ID>
-
### RESTART a suite
-
There are two main ways to restart a suite:
-
@@ -407,22 +376,16 @@ There are two main ways to restart a suite:
if you want to overwrite any previous runs of the suite and begin completely afresh (WARNING!! This will overwrite all existing model output and logs for the same suite).
-
### RELOAD a suite
-
In some cases the suite needs to be updated without necessarily having to stop it (e.g. after fixing a typo in a file). Updating an active suite is called a 'reload', where the suite is 're-installed' and
Cylc is updated with the changes (this is similar to a 'soft' restart, but with the new changes installed, so you may need to manually trigger failed tasks from the
Cylc GUI).
To reload a suite, from inside the suite directory run
rose suite-run --reload
-
-
----------------------------------------------------------------------------------------
## {{ model }} output files
-
-
-All {{ model }} output files (as well as work files) are available on gadi under /scratch/$PROJECT/$USER/cylc-run/<suite-ID>
(also symlinked in ~/cylc-run/<suite-ID>
).
+All {{ model }} output files (as well as work files) are available on Gadi under /scratch/$PROJECT/$USER/cylc-run/<suite-ID>
(also symlinked in ~/cylc-run/<suite-ID>
).
While the suite is running, files move between the share
and the work
directories.
@@ -433,10 +396,8 @@ This directory contains 2 subdirectories:
history
restart
-
### Output data
-
/scratch/$PROJECT/$USER/archive/<suite-name>/history
is the directory where the model output data is found, separated for each model component:
-
@@ -467,10 +428,8 @@ In the case of the
u-br565
suite we will have:
-
### Restart files
-
/scratch/$PROJECT/$USER/archive/<suite-name>/restart
is the directory where the restart dumps are found, subdivided for each model component (see
history
folder above).
For the atmospheric restart files, each of them is a
UM fieldsfile, formatted as
<suite-name>a.da<year><month><day>_00
.
@@ -485,9 +444,6 @@ In the case of the
u-br565
suite we will have:
br565a.da09500201_00 br565a.da09510101_00 br565.xhist-09500131 br565.xhist-09501231
-
-
-
References
diff --git a/docs/models/run-a-model/run-access-esm.md b/docs/models/run-a-model/run-access-esm.md
index 6c802109a..522f6a9f1 100644
--- a/docs/models/run-a-model/run-access-esm.md
+++ b/docs/models/run-a-model/run-access-esm.md
@@ -1,36 +1,48 @@
{% set model = "ACCESS-ESM" %}
# Run {{ model }}
## Requirements
-
Before running {{ model }}, you need to make sure to possess the right tools and to have an account with specific institutions.
-
### General requirements
-
### Model-specific requirements
-
----------------------------------------------------------------------------------------
## Get {{ model }} configuration
-
A suitable {{ model }} pre-industrial configuration is avaible on the
coecms GitHub.
-In order to get it, on
gadi, create a directory where to keep the model configuration, and clone the GitHub repo in it by running:
-
git clone https://github.com/coecms/esm-pre-industrial
+In order to get it, on
Gadi, create a directory where to keep the model configuration, and clone the GitHub repo in it by running:
+
git clone https://github.com/coecms/esm-pre-industrial.git
mkdir -p ~/access-esm
cd ~/access-esm
@@ -43,17 +55,16 @@ In order to get it, on gadi, create a directory where to keep the model c
Receiving objects: 100% (767/767), 461.57 KiB | 5.24 MiB/s, done.
Resolving deltas: 100% (450/450), done.
-
Note: Some modules might interfere with the
git
commands (for example matlab/R2018a). If you are running into issues during the cloning of the repository, it might be a good idea to run
module purge
first, before trying again.
+
+ Some modules might interfere with the
git
commands (for example matlab/R2018a). If you are running into issues during the cloning of the repository, it might be a good idea to run
module purge
first, before trying again.
----------------------------------------------------------------------------------------
## Edit {{ model }} configuration
-
-In order to modify an {{ model }} configuration, it is worth understanding a bit more how its job scheduler payu works.
-
+First, is good practice to create another git branch where to keep all modifications we put in place for our run, and to keep the
reference configuration unmodified. If we call the local branch
"example_run", we can run:
+
git checkout -b example_run
### Payu
-
Payu is a workflow management tool for running numerical models in supercomputing environments.
The general layout of a
payu-supported model run consists of two main directories:
@@ -65,7 +76,7 @@ The general layout of a
payu-supported model run consists of two main dir
The
control directory, where the model configuration is kept and from where the model is run (in our case is the cloned directory
~/access-esm/esm-pre-industrial
).
-This distinction of directories keeps the small-size configuration files separated from the larger binary outputs and inputs. In this way, we can place the configuration files in the
$HOME
directory (being the only filesystem on
gadi that is actively backed up), without overloading it with too much data.
+This distinction of directories keeps the small-size configuration files separated from the larger binary outputs and inputs. In this way, we can place the configuration files in the
$HOME
directory (being the only filesystem on
Gadi that is actively backed up), without overloading it with too much data.
Moreover, this separation allows to run multiple self-resubmitting experiments simultaneously that might share common executables and input data.
@@ -85,10 +96,8 @@ This will create the
laboratory directory, along with other subdirectorie
archive path: /scratch/$PROJECT/$USER/access-esm/archive
-
### Edit the Master Configuration file
-
The
config.yaml
file, located in the
control directory, is the Master Configuration file.
This file controls the general model configuration and if we open it in a text editor, we can see different parts:
@@ -104,6 +113,9 @@ This file controls the general model configuration and if we open it in a text e
For example, to run {{ model }} under the
tm70
project (ACCESS-NRI), add the following line to this section:
project: tm70
+
+ You should be part of a project with allocated
Service Units (SU) to be able to run {{ model }}. For more information please check
(TO DO reference projects).
+
-
Link to the laboratory directory
@@ -153,7 +165,7 @@ This file controls the general model configuration and if we open it in a text e
This section specifies the submodels and contains configuration options (for example the directories of input files) that are required to ensure the model can execute correctly. Each submodel also has additional configuration options that are read in when the submodel is running. These specific configuration options are found in the subdirectory of the control directory having the name of the submodel (e.g. in our case the configuration for the atmosphere submodel, i.e. the UM, will be in the directory
~/access-esm/esm-pre-industrial/atmosphere
).
-
- collate
+ Collate
collate:
exe: /g/data/access/payu/access-esm/bin/mppnccombine
@@ -163,7 +175,7 @@ This file controls the general model configuration and if we open it in a text e
The collate process joins a number of smaller files, which contain different parts of the model grid, together into target output files. The restart files are typically tiled in the same way and will also be joined together if the restart option is set to true
.
-
- restart
+ Restart
restart: /g/data/access/payu/access-esm/restart/pre-industrial
The location of the files used for a warm restart.
@@ -183,7 +195,9 @@ This file controls the general model configuration and if we open it in a text e
This section specifies the start date and internal run length.
- Note: The internal run length (controlled by runtime
) can be different from the total run length. Also, the runtime
value can be lowered, but should not be increased to a total of more than 1 year, to avoid errors. If you want to know more about the difference between internal run and total run lenghts, or if you want to run the model for more than 1 year, check Run configuration for multiple years.
+
+ The internal run length (controlled by
runtime
) can be different from the total run length. Also, the
runtime
value can be lowered, but should not be increased to a total of more than 1 year, to avoid errors. If you want to know more about the difference between internal run and total run lenghts, or if you want to run the model for more than 1 year, check
Run configuration for multiple years.
+
-
Number of runs per PBS submission
@@ -191,20 +205,21 @@ This file controls the general model configuration and if we open it in a text e
runspersub: 5
{{ model }} configurations are often run in multiple steps (or cycles), with payu running a maximum of runspersub
internal runs for every PBS job submission.
- Note: If we increase runspersub
, we might need to increase the walltime in the PBS resources.
+
+ If we increase runspersub
, we might need to increase the walltime in the PBS resources.
+
+
To know more about other configuration settings for the
config.yaml
file, please check
how to configure your experiment with payu.
-
----------------------------------------------------------------------------------------
## Run {{ model }} configuration
After editing the configuration, we are ready to run {{ model }}.
-{{ model }} suites run on
gadi through a PBS job submission managed by
payu.
+{{ model }} suites run on
Gadi through a PBS job submission managed by
payu.
### Payu setup (optional)
-
As a first step, from the control directory, is good practice to run:
payu setup
This will prepare the model run, based on the experiment configuration.
@@ -229,16 +244,18 @@ This will prepare the model run, based on the experiment configuration.
Writing manifests/restart.yaml
Writing manifests/exe.yaml
-
Note: You can skip this step as it is included also in the run command. However, runnning it explicitly helps to check for errors and make sure executable and restart directories are accessible.
+
+ You can skip this step as it is included also in the run command. However, runnning it explicitly helps to check for errors and make sure executable and restart directories are accessible.
### Run configuration
-
To run {{ model }} configuration for one internal run length (controlled by
runtime
in the
config.yaml
file), run:
payu run -f
This will submit a single job to the queue with a total run length of
runtime
. It there is no previous run, it will start from the
start
date indicated in the
config.yaml
file, otherwise it will perform a warm restart from a precedently saved restart file.
-
Note:The
-f
option ensures that
payu will run even if there is an existing non-empty
work directory, which happens if a run crashes.
+
+ The -f
option ensures that payu will run even if there is an existing non-empty work directory, which happens if a run crashes.
+
payu run -f
Loading input manifest: manifests/input.yaml
@@ -248,17 +265,13 @@ This will submit a single job to the queue with a total run length of runt
qsub -q normal -P <project> -l walltime=11400 -l ncpus=384 -l mem=1536GB -N pre-industrial -l wd -j n -v PAYU_PATH=/g/data/hh5/public/apps/miniconda3/envs/analysis3-23.01/bin,MODULESHOME=/opt/Modules/v4.3.0,MODULES_CMD=/opt/Modules/v4.3.0/libexec/modulecmd.tcl,MODULEPATH=/g/data3/hh5/public/modules:/etc/scl/modulefiles:/opt/Modules/modulefiles:/opt/Modules/v4.3.0/modulefiles:/apps/Modules/modulefiles -W umask=027 -l storage=gdata/access+gdata/hh5 -- /g/data/hh5/public/apps/miniconda3/envs/analysis3-23.01/bin/python3.9 /g/data/hh5/public/apps/miniconda3/envs/analysis3-23.01/bin/payu-run
<job-ID>.gadi-pbs
-
### Run configuration for multiple years
-
If you want to run {{ model }} configuration for multiple internal run lengths (controlled by
runtime
in the
config.yaml
file), you can use the option
-n
:
-
payu run -n <number-of-runs>
+
payu run -f -n <number-of-runs>
This will run the configuration
number-of-runs
times with a total run length of
runtime * number-of-runs
. The number of consecutive PBS jobs submitted to the queue depends on the
runspersub
value specified in the
config.yaml
file.
-
### Understand
runtime
,
runspersub
, and
-n
parameters
-
With the correct use of
runtime
,
runspersub
, and
-n
parameters, we can have full control of our run.
@@ -278,14 +291,14 @@ Let's have some practical examples:
Run 20 years of simulation, with resubmission every 5 years
To have a total run length of 20 years, with a resubmition cycle of 5 years, we can leave runtime
to the default value of 1 year
, set runspersub
to 5
, and run the configuration using -n 20
:
-
payu run -n 20
+
payu run-f -n 20
This will submit subsequent jobs for the following years: 1 to 5, 6 to 10, 11 to 15, and 16 to 20. With a total of 4 PBS jobs.
-
Run 7 years of simulation, with resubmission every 3 years
To have a total run length of 7 years, with a resubmition cycle of 3 years, we can leave runtime
to the default value of 1 year
, set runspersub
to 3
, and run the configuration using -n 7
:
- payu run -n 7
+ payu run -f -n 7
This will submit subsequent jobs for the following years: 1 to 3, 4 to 6, and 7. With a total of 3 PBS jobs.
-
@@ -297,7 +310,7 @@ Let's have some practical examples:
days: 10
set
runspersub
to 1
(or any value > 1), and run the configuration without -n
(or with -n
equals 1
):
- payu run
+ payu run -f
-
Run 1 year and 4 months of simulation, with resubmission every 4 months
@@ -308,14 +321,12 @@ Let's have some practical examples:
days: 0
Since the internal run length is set to 4 months, to resubmit our jobs every 4 months (i.e. every internal run), we have to set
runspersub
to 1
. Finally, we will perform 4 internal runs by running the configuration with -n 4
:
- payu run -n 4
+ payu run -f -n 4
-
----------------------------------------------------------------------------------------
## Monitor {{ model }} runs
-
Currently, there is no specific tool to monitor {{ model }} runs.
One way to check the status of our run is running:
@@ -326,10 +337,10 @@ This will show the status of all your PBS jobs (if there is any PBS job submitte
Job id Name User Time Use S Queue
--------------------- ---------------- ---------------- -------- - -----
<job-ID>.gadi-pbs pre-industrial <$USER> <time> R normal-exec
-
<job-ID>.gadi-pbs <other-job-name> <$USER> <time> R normal-exec
-
<job-ID>.gadi-pbs <other-job-name> <$USER> <time> R normal-exec
+
<job-ID-2>.gadi-pbs <other-job-name> <$USER> <time> R normal-exec
+
<job-ID-3>.gadi-pbs <other-job-name> <$USER> <time> R normal-exec
-If you changed the
jobname
in the PBS resources of the
Master Configuration file, that will be your job's
Name instead of
pre-industrial
.
+If you changed the
jobname
in the PBS resources of the
Master Configuration file, that will be your job's
Name instead of
pre-industrial
.
S indicates the status of your run:
----------------------------------------------------------------------------------------
## {{ model }} outputs
-
-
-
+----------------------------------------------------------------------------------------
-
References
-
diff --git a/docs/models/run-a-model/run-access-om.md b/docs/models/run-a-model/run-access-om.md
index df2873c0c..9b30239ca 100644
--- a/docs/models/run-a-model/run-access-om.md
+++ b/docs/models/run-a-model/run-access-om.md
@@ -1,37 +1,398 @@
-# Running ACCESS-OM2 Model
-Welcome to **ACCESS-OM2** — a coupled ocean-ice model and collection of [configurations](http://cosima.org.au/index.php/models/) developed by the [Consortium for Ocean-Sea Ice Modelling in Australia (COSIMA)](http://cosima.org.au/).
+{% set model = "ACCESS-OM" %}
+# Run {{ model }}
+## Requirements
-ACCESS-OM2 consists of the [MOM 5.1](https://mom-ocean.github.io) ocean model, [CICE 5.1.2](https://github.com/CICE-Consortium/CICE-svn-trunk/tree/cice-5.1.2) sea ice model, and a file-based atmosphere called [YATM](https://github.com/COSIMA/libaccessom2) coupled together using the [OASIS3-MCT v2.0](https://portal.enes.org/oasis) coupler. Regridding is done using [ESMF](https://www.earthsystemcog.org/projects/esmf/) and [KDTREE2](https://github.com/jmhodges/kdtree2).
+Before running {{ model }}, you need to make sure to possess the right tools and to have an account with specific institutions.
-The configurations available here are updated from the version 1.0 configurations described in [Kiss et al. (2020)](https://doi.org/10.5194/gmd-13-401-2020). Further details are given in the [ACCESS-OM2 technical report](https://github.com/COSIMA/ACCESS-OM2-1-025-010deg-report).
+### General requirements
+For the general requirements needed to run all ACCESS models, please refer to the Getting Started (TO DO check link) page.
-## How to access existing ACCESS-OM2 output
+### Model-specific requirements
+
+----------------------------------------------------------------------------------------
-[NCI](http://nci.org.au) users can access model output via the [COSIMA Cookbook](https://github.com/COSIMA/cosima-cookbook). A good place to start is the [data explorer](https://nbviewer.jupyter.org/github/COSIMA/cosima-recipes/blob/master/Tutorials/Using_Explorer_tools.ipynb), which will give an overview of the data available. Also see this [overview of 0.1° IAF outputs](http://cosima.org.au/index.php/2020/07/29/data-available-0-1-1958-2018-access-om2-iaf-run/).
+## Get {{ model }} configuration
-Non-NCI users can access a subset of the ACCESS-OM2 output via the [COSIMA Model Output Collection](https://dx.doi.org/10.4225/41/5a2dc8543105a).
+A standard {{ model }} configuration is avaible on the COSIMA GitHub.
+
+This is a 1° horizontal resolution configuration, with interannual forcing from 1 Jan 1958 to 31 Dec 2018.
+
+In order to get it, on Gadi, create a directory where to keep the model configuration, and clone the GitHub repo in it by running:
+git clone https://github.com/COSIMA/1deg_jra55_iaf.git
+
+ mkdir -p ~/access-om
+ cd ~/access-eom
+ git clone https://github.com/COSIMA/1deg_jra55_iaf.git
+ Cloning into '1deg_jra55_iaf'...
+ remote: Enumerating objects: 14715, done.
+ remote: Counting objects: 100% (3401/3401), done.
+ remote: Compressing objects: 100% (24/24), done.
+ remote: Total 14715 (delta 3383), reused 3379 (delta 3377), pack-reused 11314
+ Receiving objects: 100% (14715/14715), 35.68 MiB | 18.11 MiB/s, done.
+ Resolving deltas: 100% (10707/10707), done.
+
+
+ Some modules might interfere with the
git
commands (for example matlab/R2018a). If you are running into issues during the cloning of the repository, it might be a good idea to run
module purge
first, before trying again.
+
+----------------------------------------------------------------------------------------
-## How to run ACCESS-OM2
+## Edit {{ model }} configuration
+First, is good practice to create another git branch where to keep all modifications we put in place for our run, and to keep the reference configuration unmodified. If we call the local branch "example_run", we can run:
+git checkout -b example_run
-Start by reading the [[Quick start\|Getting-started#quick-start]] guide. If you are using [gadi.nci.org.au](http://nci.org.au/our-systems/hpc-systems) at the [NCI National Facility](http://nci.org.au/) and are happy to use our pre-compiled executables then this should be all you need. The page also provides instructions for building your own executables.
+### Payu
+Payu is a workflow management tool for running numerical models in supercomputing environments.
+
+The general layout of a payu-supported model run consists of two main directories:
+
+ -
+ The laboratory is the directory where all parts of the model are kept. For {{ model }}, it is typically
/scratch/$PROJECT/$USER/access-om2
.
+
+ -
+ The control directory, where the model configuration is kept and from where the model is run (in our case is the cloned directory
~/access-om/1deg_jra55_iaf
).
+
+
+This distinction of directories keeps the small-size configuration files separated from the larger binary outputs and inputs. In this way, we can place the configuration files in the $HOME
directory (being the only filesystem on Gadi that is actively backed up), without overloading it with too much data.
+
+Moreover, this separation allows to run multiple self-resubmitting experiments simultaneously that might share common executables and input data.
+
+To proceed with the setup of the laboratory directory, from the control directory run:
+payu init
+This will create the laboratory directory, along with other subdirectories (depending on the configuration). The main subdirectories we are interested in are:
+
+ work
→ temporary directory where the model is actually run. It gets cleaned after each run.
+ archive
→ directory where the output is placed after each run.
+
+ cd ~/access-om/1deg_jra55_iaf
+ payu init
+ laboratory path: /scratch/$PROJECT/$USER/access-om2
+ binary path: /scratch/$PROJECT/$USER/access-om2/bin
+ input path: /scratch/$PROJECT/$USER/access-om2/input
+ work path: /scratch/$PROJECT/$USER/access-om2/work
+ archive path: /scratch/$PROJECT/$USER/access-om2/archive
+
+
-**NOTE:** All ACCESS-OM2 model components and configurations are undergoing continual improvement. We strongly recommend that you "watch" this repo (see button at top of screen; ask to be notified of all conversations) and also watch all the [component models](https://github.com/COSIMA/access-om2/tree/master/src), whichever [configuration(s)](https://github.com/COSIMA/access-om2/tree/master/control) you are using, and [payu](https://github.com/payu-org/payu) to be kept informed of updates, problems and bug fixes as they arise.
+### Edit the Master Configuration file
+The config.yaml
file, located in the control directory, is the Master Configuration file.
+
+This file controls the general model configuration and if we open it in a text editor, we can see different parts:
+
+ -
+ PBS resources
+
+ queue: normal
+ walltime: 3:00:00
+ jobname: 1deg_jra55_iaf
+ mem: 1000GB
+
+ These are settings for the PBS scheduler. Edit lines in this section to change any of the PBS resources.
+
+ For example, to run {{ model }} under the tm70
project (ACCESS-NRI), add the following line to this section:
+ project: tm70
+
+ You should be part of a project with allocated
Service Units (SU) to be able to run {{ model }}. For more information please check
(TO DO reference projects).
+
+
+ -
+ Model configuration
+
name: common
+ model: access-om2
+ input: /g/data/ik11/inputs/access-om2/input_20201102/common_1deg_jra55
+
+ The main model configuration. This tells payu which driver to use (access-om).
+
+ The name
field here is not actually used for the configuration run and you can safely disregard it.
+
+ -
+ Submodels
+
+ submodels:
+ - name: atmosphere
+ model: yatm
+ exe: /g/data/access/payu/access-om2/bin/coe/um7.3x
+ input:
+ - /g/data/ik11/inputs/access-om2/input_20201102/yatm_1deg
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hr/rsds/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hr/rlds/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hr/prra/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hr/prsn/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hrPt/psl/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/land/day/friver/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hrPt/tas/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hrPt/huss/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hrPt/uas/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/atmos/3hrPt/vas/gr/v20190429
+ - /g/data/qv56/replicas/input4MIPs/CMIP6/OMIP/MRI/MRI-JRA55-do-1-4-0/landIce/day/licalvf/gr/v20190429
+ ncpus: 1
+ - name: ocean
+ model: mom
+ exe: /g/data/ik11/inputs/access-om2/bin/fms_ACCESS-OM_730f0bf_libaccessom2_d750b4b.x
+ input: /g/data/ik11/inputs/access-om2/input_20201102/mom_1deg
+ ncpus: 216
+ - name: ice
+ model: cice
+ exe: /g/data/ik11/inputs/access-om2/bin/cice_auscom_360x300_24p_edcfa6f_libaccessom2_d750b4b.exe
+ input: /g/data/ik11/inputs/access-om2/input_20201102/cice_1deg
+ ncpus: 24
+
+ {{ model }} is a coupled model, which means it has multiple submodels (i.e. model components).
+
+ This section specifies the submodels and contains configuration options (for example the directories of input files) that are required to ensure the model can execute correctly. Each submodel also has additional configuration options that are read in when the submodel is running. These specific configuration options are found in the subdirectory of the control directory having the name of the submodel (e.g. in our case the configuration for the atmosphere submodel will be in the directory ~/access-om/1deg_jra55_iaf/atmosphere
).
+
+ -
+ Collate
+
+ collate:
+ restart: true
+ walltime: 1:00:00
+ mem: 30GB
+ ncpus: 4
+ queue: normal
+ exe: /g/data/ik11/inputs/access-om2/bin/mppnccombine
+
+ The collate process joins a number of smaller files, which contain different parts of the model grid, together into target output files. The restart files are typically tiled in the same way and will also be joined together if the restart option is set to true
.
+
+ -
+ Runlog
+
+ runlog: true
+ When running a new configuration, payu automatically commits changes in git if runlog is set to true.
+
+ -
+ Stack size
+
+ stacksize: unlimited
+ The stack size is the maximum size of the per-thread resources allocated for each process (in KiB).
+ unlimited works without any issues, but explicit stacksize values may not be correctly communicated across Gadi nodes.
+
+ -
+ Restart frequency
+
+ restart_freq: 1
+ The restart frequency specifies the rate of saved restart files. For example, if restart_freq: 5
, we keep the restart files for every fifth run (restart004, restart009, restart014, etc.). Intermediate restarts are not deleted until a permanently archived restart has been produced. For example, if we have just completed run 11, then we keep restart004, restart009, restart010, and restart011. Restarts 10 through 13 are not deleted until restart014 has been saved.
+
+ restart_freq: 1
saves all restart files.
+
+ -
+ mpirun arguments
+
+ mpirun: --mca io ompio --mca io_ompio_num_aggregators 1
+ Append mpirun arguments to the mpirun call of the model.
+
+ -
+ qsub flags
+
+ qsub_flags: -W umask=027
+ Configuration marker for any additional qsub flags.
+
+ -
+ Environment variables
+
+ env:
+ UCX_LOG_LEVEL: 'error'
+
+ Add the specified variables to the run environment.
+
+ -
+ Platform specific defaults
+
+ platform:
+ nodesize: 48
+
+ Set platform specific defaults.
+
+ nodesize sets the default number of cpus per node to fully utilise nodes regardless of requested number of cpus.
+
+ -
+ User scripts
+
+ userscripts:
+ error: resub.sh
+ run: rm -f resubmit.count
+
+ Namelist to include separate userscripts or subcommands at various stages of a payu submission.
+
+ error
gets called if the model does not run correctly and returns an error code;
+
+ run
gets called after model execution but prior to model output archive.
+
+
+
+To know more about other configuration settings for the config.yaml
file, please check how to configure your experiment with payu.
-## Getting help and reporting issues
+### Change run length
+To change the internal run length, edit the restart_period
field in the &date_manager_nml
section of the ~/access-om/1deg_jra55_iaf/accessom2.nml
file:
+&date_manager_nml
+ forcing_start_date = '1958-01-01T00:00:00'
+ forcing_end_date = '2019-01-01T00:00:00'
+ ! Runtime for a single segment/job/submit, format is years, months, seconds,
+ ! two of which must be zero.
+ restart_period = 5, 0, 0
+
+
+ The internal run length (controlled by
restart_period
) can be different from the total run length. Also, the
restart_period
value can be lowered, but should not be increased to a total of more than 5 years, to avoid errors. If you want to know more about the difference between internal run and total run lenghts, or if you want to run the model for more than 1 year, check
Run configuration for multiple years.
+
-For all help requests and error reports please create a "GitHub issue" at [ACCESS-OM2 issues](https://github.com/COSIMA/access-om2/issues).
+----------------------------------------------------------------------------------------
-### For self-help
+## Run {{ model }} configuration
+After editing the configuration, we are ready to run {{ model }}.
+
+{{ model }} suites run on Gadi through a PBS job submission managed by payu.
-Setting up and running the model is primarily supported via the [[ACCESS-OM2 wiki|Home]] (that you are already reading). _It is a "wiki" so feel free to correct and contribute_.
+### Payu setup (optional)
+As a first step, from the control directory, is good practice to run:
+payu setup
+This will prepare the model run, based on the experiment configuration.
+
+ payu setup
+ laboratory path: /scratch/$PROJECT/$USER/access-om2
+ binary ppath: /scratch/$PROJECT/$USER/access-om2/bin
+ input path: /scratch/$PROJECT/$USER/access-om2/input
+ work path: /scratch/$PROJECT/$USER/access-om2/work
+ archive path: /scratch/$PROJECT/$USER/access-om2/archive
+ Loading input manifest: manifests/input.yaml
+ Loading restart manifest: manifests/restart.yaml
+ Loading exe manifest: manifests/exe.yaml
+ Setting up atmosphere
+ Setting up ocean
+ Setting up ice
+ Setting up access-om2
+ Checking exe and input manifests
+ Updating full hashes for 3 files in manifests/exe.yaml
+ Creating restart manifest
+ Writing manifests/restart.yaml
+ Writing manifests/exe.yaml
+
+
+ You can skip this step as it is included also in the run command. However, runnning it explicitly helps to check for errors and make sure executable and restart directories are accessible.
+
-## How to update this wiki
+### Run configuration
+To run {{ model }} configuration for one internal run length (controlled by restart_period
in the config.yaml
file), run:
+payu run -f
+This will submit a single job to the queue with a total run length of restart_period
.
+
+
+ The -f
option ensures that payu will run even if there is an existing non-empty work directory, which happens if a run crashes.
+
+
+ payu run -f
+ payu: warning: Job request includes 47 unused CPUs.
+ payu: warning: CPU request increased from 241 to 288
+ Loading input manifest: manifests/input.yaml
+ Loading restart manifest: manifests/restart.yaml
+ Loading exe manifest: manifests/exe.yaml
+ payu: Found modules in /opt/Modules/v4.3.0
+ qsub -q normal -P tm70 -l walltime=10800 -l ncpus=288 -l mem=1000GB -N 1deg_jra55_iaf -l wd -j n -v PYTHONPATH=/g/data3/tm70/dm5220/scripts/python_modules/,PAYU_PATH=/g/data/hh5/public/apps/miniconda3/envs/analysis3-23.01/bin,PAYU_FORCE=True,MODULESHOME=/opt/Modules/v4.3.0,MODULES_CMD=/opt/Modules/v4.3.0/libexec/modulecmd.tcl,MODULEPATH=/g/data3/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/ik11+gdata/qv56 -- /g/data/hh5/public/apps/miniconda3/envs/analysis3-23.01/bin/python3.9 /g/data/hh5/public/apps/miniconda3/envs/analysis3-23.01/bin/payu-run
+ <job-ID>.gadi-pbs
+
-The wiki attached to a public repository can be edited by anyone. Just navigate to the page you wish to edit and click on the 'edit' button on the top right hand side.
+### Run configuration for multiple years
+If you want to run {{ model }} configuration for multiple internal run lengths (controlled by restart_period
in the config.yaml
file), you can use the option -n
:
+payu run -f -n <number-of-runs>
+This will run the configuration number-of-runs
times with a total run length of restart_period * number-of-runs
.
+
+For example, if you want to run the configuration for a total of 50 years and you set restart_period = 5, 0, 0
(5 years), you will have to set the number-of-runs
to 10:
+payu run -f -n 10
+----------------------------------------------------------------------------------------
+## Monitor {{ model }} runs
+Currently, there is no specific tool to monitor {{ model }} runs.
+
+One way to check the status of our run is running:
+qstat -u $USER
+This will show the status of all your PBS jobs (if there is any PBS job submitted):
+
+ qstat -u $USER
+ Job id Name User Time Use S Queue
+ --------------------- ---------------- ---------------- -------- - -----
+ <job-ID>.gadi-pbs 1deg_jra55_iaf <$USER> <time> R normal-exec
+ <job-ID-2>.gadi-pbs <other-job-name> <$USER> <time> R normal-exec
+ <job-ID-3>.gadi-pbs <other-job-name> <$USER> <time> R normal-exec
+
+If you changed the jobname
in the PBS resources of the Master Configuration file, that will be your job's Name instead of 1deg_jra55_iaf
.
+
+S indicates the status of your run:
+
+ - Q → Job waiting in the queue to start
+ - R → Job running
+ - E → Job ending
+
+If there is no listed job with your jobname
(or if there is no job submitted at all), your run might have successfully completed, or might have been terminated due to an error.
+### Stop a run
+If you want to manually terminate a run, you can do it by running:
+qdel <job-ID>
-# References
-[ACCESS-OM2]: https://github.com/COSIMA/access-om2/
-[ACCESS-OM2 wiki]: https://github.com/COSIMA/access-om2/
+### Error and output log files
+While the model is running, payu saves the standard output and standard error into the files access-om2.out
and access-om2.err
in the control directory. You can examine these files, as the run progresses, to check on it's status.
+
+After the model has completed its run, or if it crashed, the output and error log files, respectively, are renamed by default into jobname.o<job-ID>
and jobname.e<job-ID>
.
+----------------------------------------------------------------------------------------
+
+## {{ model }} outputs
+While the configuration is running, output files (as well as restart files) are moved from the work
directory to the archive
directory, under /scratch/$PROJECT/$USER/access-om2/archive
(also symlinked in the control directory under ~/access-om/1deg_jra55_iaf/archive
).
+
+Both outputs and restarts are stored into subfolders for each different configuration (1deg_jra55_iaf
in our case), and inside the configuration folder, they are subdivided for each internal run.
+
+The format of a typical output folder is outputXXX
, whereas the typical restart folder is usually formatted as restartXXX
, with XXX being the number of internal run, starting from 000
.
+
+In the respective folders, outputs and restarts are separated for each model component.
+
+ cd /scratch/$PROJECT/$USER/access-om2/archive/1deg_jra55_iaf
+ ls
+ output000 pbs_logs restart000
+
+
+
+References
+
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 7de8ee88d..5da6896df 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -42,6 +42,7 @@ theme:
- content.action.view
- content.code.copy # for displaying copy icon at top right in code snippets
- content.code.annotate
+ - content.tabs.link
- search.suggest
- search.highlight
- search.share
@@ -98,13 +99,16 @@ nav:
# - Change the Navigation: contribute/change-the-navigation.md
# - Reviewers: contribute/reviewers.md
+ - Get Started:
+ - get_started/index.md
+
- Models:
- Models: models/index.md
- Model Configurations:
- Overview: models/configurations/index.md
- - ACCESS-ESM: models/configurations/access-esm.md
- - ACCESS-CM: models/configurations/access-cm.md
- ACCESS-AM: models/configurations/access-am.md
+ - ACCESS-CM: models/configurations/access-cm.md
+ - ACCESS-ESM: models/configurations/access-esm.md
- ACCESS-OM: models/configurations/access-om.md
- Model Components:
- Overview: models/model_components/index.md
@@ -121,17 +125,15 @@ nav:
- Run a Model:
- models/run-a-model/index.md
- - Gadi Computing Access at NCI: models/run-a-model/getting_started/access_to_gadi_at_nci.md
- - Run ACCESS-ESM: models/run-a-model/run-access-esm.md
- - Run ACCESS-CM: models/run-a-model/run-access-cm.md
- Run ACCESS-AM: models/run-a-model/run-access-am.md
+ - Run ACCESS-CM: models/run-a-model/run-access-cm.md
+ - Run ACCESS-ESM: models/run-a-model/run-access-esm.md
- Run ACCESS-OM: models/run-a-model/run-access-om.md
- Model Evaluation:
- model_evaluation/index.md
- Getting Started:
- model_evaluation/model_evaluation_getting_started/index.md
- - Gadi Computing Access at NCI: model_evaluation/model_evaluation_getting_started/access_to_gadi_at_nci.md
- Model Evaluation on Gadi: model_evaluation/model_evaluation_getting_started/model_evaluation_getting_started.md
- Model Variables: model_evaluation/model_evaluation_getting_started/model_variables/index.md
# - CMIP6: model_evaluation/model_evaluation_getting_started/model_variables/variables_cmip6.md
@@ -153,11 +155,15 @@ nav:
- Community Resources:
- community_resources/index.md
- Working Groups: community_resources/community_working_groups.md
+ - Events:
+ - community_resources/events/index.md
+ # - Add Event: community_resources/events/add_event.md
- Model Evaluation Links:
- - Observational Catalogs: community_resources/community_observational_catalogs.md
- - Model Catalogs: community_resources/community_model_catalogs.md
- - Data Formatting: community_resources/community_data_processing.md
- - Evaluation Recipes: community_resources/community_med_recipes.md
+ - community_resources/community_med/index.md
+ - Observational Catalogs: community_resources/community_med/community_observational_catalogs.md
+ - Model Catalogs: community_resources/community_med/community_model_catalogs.md
+ - Data Formatting: community_resources/community_med/community_data_processing.md
+ - Evaluation Recipes: community_resources/community_med/community_med_recipes.md
# - Training:
# - Training: community_resources/training/index.md
# - Git Version Control: community_resources/training/git-version-control.md
@@ -165,10 +171,7 @@ nav:
# - ACCESS Training: community_resources/training/ACCESS_training.md
# - NCI Training: community_resources/training/nci-training.md
# - Additional Training: community_resources/training/additional_training.md
- - Events:
- - community_resources/events/index.md
- # - Add Event: community_resources/events/add_event.md
-
+
- Community Forum: https://forum.access-hive.org.au
- About:
@@ -195,16 +198,14 @@ extra:
provider: google
property: G-2T6SQEH2CX
- # # Fontawesome icons
- # supported: ''
- # recommended: ''
- # community: ''
-
extra_css:
- - css/fontello.css
- "https://fonts.googleapis.com/icon?family=Material+Icons" # Material Icons Reference - https://material.io/resources/icons/?style=baseline
- - css/fontawesome-free-6.4.0-web/css/fontawesome.css
- - css/fontawesome-free-6.4.0-web/css/solid.css
+ - fontawesome-free-6.4.0-web/css/fontawesome.css
+ - fontawesome-free-6.4.0-web/css/solid.css
+ - fontello/css/fontello-codes.css
+ - fontello/css/fontello-ie7-codes.css
+ - fontello/css/fontello-ie7.css
+ - fontello/css/fontello.css
- css/access-nri.css
extra_javascript: