Skip to content

Commit 39a82e3

Browse files
blimlimblimlim
committed
Add restart description and instructions for changing date
1 parent a4935d6 commit 39a82e3

2 files changed

Lines changed: 121 additions & 0 deletions

File tree

‎documentation/docs/pages/inputs/restarts.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
2+
ESM1.6 restart files contain copies of complete model states, allowing for experiments to be stopped and restarted at a later time. This page outlines their structure and details basic procedures for manipulating them.
3+
4+
5+
## Structure of the ESM1.6 restart directory
6+
7+
An ESM1.6 restart directory contains separate restart files for each component. These are are organised as follows:
8+
9+
10+
<terminal-window static>
11+
<terminal-line>ls /g/data/vk83/prerelease/configurations/inputs/access-esm1p6/modern/pre-industrial-emissions/restart/2025.11.28</terminal-line>
12+
<terminal-line>atmosphere coupler ice ocean README</terminal-line>
13+
</terminal-window>
14+
15+
16+
### Atmosphere
17+
The atmosphere restart directory contains the following files
18+
```bash
19+
restart_dump.astart um.res.yaml
20+
```
21+
`restart_dump.astart` is the main UM restart file, containing the atmospheric state in addition to static boundary information such as the land-sea mask, vegetation maps and orography.
22+
23+
`um.res.yaml` is a separate calendar file which holds the date and time associated with the restart. Information in this file is copied by `payu` into the model namelist files at runtime.
24+
25+
26+
### Ocean
27+
The ocean restart files are organised into seperate groups of variables:
28+
```bash
29+
ocean_age.res.nc ocean_density.res.nc ... ocean_solo.res
30+
```
31+
32+
The netCDF files contain snapshots of the model state while `ocean_solo.res` is a text file specifying the model date and time.
33+
34+
### Ice
35+
36+
The ice restart directory contains the following files:
37+
38+
```bash
39+
cice_in.nml iced.2145-01-01-00000.nc ice.restart_file mice.nc
40+
```
41+
42+
The `iced.YYYY-MM-DD-00000.nc` holds the model state and also carries the date and time in the global attributes. `ice.restart_file` is
43+
a pointer file used by CICE when finding the correct restart file to read. `mice.nc` contains ice coupling data to be sent to the ocean model
44+
at the beginning of the next run.
45+
46+
### Coupler
47+
The coupler restart directory contains data sent from each component at the termination of the previous run, allowing for the submodels to access the required boundary conditions at the beginning of the next run.
48+
49+
```bash
50+
a2i.nc i2a.nc o2i.nc
51+
```
52+
53+
54+
55+
## Common restart manipulations
56+
57+
### Changing the date of a restart file
58+
59+
It's commonly required to change the date for a restart file. For example when setting up a historical experiment, a restart might be taken from a pre-industrial simulation and the date changed to 1850.
60+
61+
The following instructions outline how to modify the date for each component. It's important to apply the updates to all components consistently, as inconsistencies in the model dates can cause crashes.
62+
63+
#### Atmosphere:
64+
Navigate to the `restart/atmosphere` directory:
65+
66+
<terminal-window static>
67+
<terminal-line>module use /g/data/xp65/public/modules</terminal-line>
68+
<terminal-line>module load conda/analysis3</terminal-line>
69+
70+
<terminal-line><span style='color:#009933'>&#35 Update the date in the UM dump file</span></terminal-line>
71+
<terminal-line>python ~access/apps/pythonlib/umfile_utils/access_cm2/change_dump_date.py restart_dump.astart <<< "YYYY MM DD"</terminal-line>
72+
<terminal-line><span style='color:#009933'># Update the date in the calendar file</span></terminal-line>
73+
<terminal-line>sed -i "s/end_date:.*/end_date: YYYY-MM-DD 00:00:00/" <new-restart-path>/atmosphere/um.res.yaml</terminal-line>
74+
</terminal-window>
75+
76+
#### Ocean:
77+
In the `restart/ocean` directory, edit `ocean_solo.res`:
78+
79+
```
80+
3 (Calendar: no_calendar=0, thirty_day_months=1, julian=2, gregorian=3, noleap=4)
81+
1 1 1 0 0 0 Model start time: year, month, day, hour, minute, second
82+
2145 1 1 0 0 0 Current model time: year, month, day, hour, minute, second
83+
```
84+
85+
Replace the date in the 3rd line, taking care to preserve the column alignment. The entries should not be zero-padded.
86+
87+
#### Ice:
88+
In the `restart/ice` directory:
89+
90+
Rename the `iced.YYYY-MM-DD-00000.nc` with new date. The year, month, and day should be zero padded.
91+
92+
Edit the `ice.restart` pointer file to use the new file name:
93+
<terminal-window static>
94+
<terminal-line>echo ./RESTART/iced.YYYY-MM-DD-00000.nc > ice.restart</terminal-line>
95+
</terminal-window>
96+
97+
Replace the `year`, `nyr`, `month`, and `mday` global attributes using `nco` (in most cases, only the year will need to be changed):
98+
<terminal-window static>
99+
<terminal-line>module load nco</terminal-line>
100+
<terminal-line>ncatted -O -a year,global,o,l,<span style="color:red">YYYY</span> iced.YYYY-MM-DD-00000.nc</terminal-line>
101+
<terminal-line>ncatted -O -a nyr,global,o,l,<span style="color:red">YYYY</span> iced.YYYY-MM-DD-00000.nc</terminal-line>
102+
<terminal-line>ncatted -O -a month,global,o,l,<span style="color:red">MM</span> iced.YYYY-MM-DD-00000.nc</terminal-line>
103+
<terminal-line>ncatted -O -a mday,global,o,l,<span style="color:red">DD</span> iced.YYYY-MM-DD-00000.nc</terminal-line>
104+
</terminal-window>
105+
106+
107+
Replace the `time` global attribute to equal the total number of seconds between 1/1/1 and the new date using the proleptic Gregorian calendar. This can be calculated using the `cftime` python library. E.g. using 2105-03-01 as the new date:
108+
<terminal-window static>
109+
<terminal-line>python</terminal-line>
110+
<terminal-line>>>> import cftime</terminal-line>
111+
<terminal-line>>>> start = cftime.datetime(1,1,1, calendar="proleptic_gregorian")</terminal-line>
112+
<terminal-line>>>> end = cftime.datetime(2105,3,1, calendar="proleptic_gregorian")</terminal-line>
113+
<terminal-line>>>> (end-start).total_seconds()</terminal-line>
114+
<terminal-line>66400905600.0</terminal-line>
115+
</terminal-window>
116+
117+
Then add this to the restart file using `nco`:
118+
<terminal-window static>
119+
<terminal-line>ncatted -O -a time,global,o,d,66400905600 iced.YYYY-MM-DD-00000.nc</terminal-line>
120+
</terminal-window>

‎documentation/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,7 @@ nav:
111111
- Sea ice: pages/inputs/seaice.md
112112
- Atmosphere: pages/inputs/atmosphere.md
113113
- Land: pages/inputs/land.md
114+
- Restarts: pages/inputs/restarts.md
114115

115116
- Configurations and Experiments:
116117
- Configuration: pages/configs_experiments/overviewconfiguration.md

0 commit comments

Comments
 (0)
⚡