diff --git a/documentation/docs/pages/inputs/restarts.md b/documentation/docs/pages/inputs/restarts.md new file mode 100644 index 00000000..04ad99eb --- /dev/null +++ b/documentation/docs/pages/inputs/restarts.md @@ -0,0 +1,129 @@ +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. + + +## Structure of the ESM1.6 restart directory + +An ESM1.6 restart directory contains separate restart files for each component. These are organised into the following directories: + +``` +atmosphere coupler ice ocean README +``` + +An example restart directory is available in `/g/data/vk83/prerelease/configurations/inputs/access-esm1p6/modern/pre-industrial/restart/2025.11.2`. + +### Atmosphere +The atmosphere restart directory contains the following files +``` +restart_dump.astart um.res.yaml +``` +`restart_dump.astart` is the main UM restart file, containing the atmospheric and land state in addition to static boundary information such as the land-sea mask, vegetation maps and orography. + +`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](https://payu.readthedocs.io) into the model namelist files at runtime. + + +### Ocean +The ocean restart files are organised into separate groups of variables: +``` +ocean_age.res.nc ocean_density.res.nc ... ocean_solo.res +``` + +These netCDF files contain snapshots of the model state while `ocean_solo.res` is a text file specifying the model date and time. + +### Ice + +The ice restart directory contains the following files: + +``` +iced.2145-01-01-00000.nc ice.restart_file mice.nc +``` + +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 +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 +at the beginning of the next run. + +### Coupler +The coupler restart directory contains data sent from each component at the termination of the previous run, allowing for the submodels to restart with the same boundary conditions at the beginning of the next run. + +``` +a2i.nc i2a.nc o2i.nc +``` + + + +## Common restart manipulations + +### Changing the date of restart files + +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. Another example is when combining ocean and atmosphere restarts from two different experiments into a single restart, where it is necessary to make sure the dates for the different components match. + +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. + +!!! info + Before starting any manipulation, copy the restart folders you want to modify to a new location of your choice. + + +#### Atmosphere: +Navigate to the `restart/atmosphere` directory: + + +module use /g/data/xp65/public/modules +module load conda/analysis3 +# Update the date in the UM dump file +python ~access/apps/pythonlib/umfile_utils/access_cm2/change_dump_date.py restart_dump.astart <<< "YYYY MM DD", +# Update the date in the calendar file +sed -i "s/end_date:.*/end_date: YYYY-MM-DD 00:00:00/" /atmosphere/um.res.yaml + + +#### Ocean: +In the `restart/ocean` directory, edit `ocean_solo.res`: + +``` + 3 (Calendar: no_calendar=0, thirty_day_months=1, julian=2, gregorian=3, noleap=4) + 1 1 1 0 0 0 Model start time: year, month, day, hour, minute, second + 2145 1 1 0 0 0 Current model time: year, month, day, hour, minute, second +``` + +Replace the date in the 3rd line, taking care to preserve the column alignment. The entries should not be zero-padded. + +#### Sea-ice: +In the `restart/ice` directory: + +Rename the `iced.YYYY-MM-DD-00000.nc` with new date. The year, month, and day should be zero padded. + +Edit the `ice.restart` pointer file to use the new file name: + +echo ./RESTART/iced.YYYY-MM-DD-00000.nc > ice.restart_file + + +Replace the `year`, `nyr`, `month`, and `mday` global attributes using `nco` (in most cases, only the `year` and `nyr` attributes will need to be changed. These should be given the same value.): + +module load nco +ncatted -O -a year,global,o,l,YYYY iced.YYYY-MM-DD-00000.nc +ncatted -O -a nyr,global,o,l,YYYY iced.YYYY-MM-DD-00000.nc +ncatted -O -a month,global,o,l,MM iced.YYYY-MM-DD-00000.nc +ncatted -O -a mday,global,o,l,DD iced.YYYY-MM-DD-00000.nc + + + +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: + +python +>>> import cftime +>>> start = cftime.datetime(1,1,1, calendar="proleptic_gregorian") +>>> end = cftime.datetime(2105,3,1, calendar="proleptic_gregorian") +>>> (end-start).total_seconds() +66400905600.0 + + +Then add this to the restart file using `nco`: + +ncatted -O -a time,global,o,d,66400905600 iced.YYYY-MM-DD-00000.nc + + +#### Update the configuration + +Update the payu configuration file, `config.yaml`, with the path to the new restart files: + +```yaml +restart: +``` \ No newline at end of file diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 4b94905e..a5282d1c 100755 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -111,6 +111,7 @@ nav: - Sea ice: pages/inputs/seaice.md - Atmosphere: pages/inputs/atmosphere.md - Land: pages/inputs/land.md + - Restarts: pages/inputs/restarts.md - Configurations and Experiments: - Configuration: pages/configs_experiments/overviewconfiguration.md @@ -135,6 +136,7 @@ extra: extra_css: - "https://fonts.googleapis.com/icon?family=Material+Icons" # Material Icons Reference - https://material.io/resources/icons/?style=baseline + - "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css" - fontello/css/fontello-codes.css - fontello/css/fontello-ie7-codes.css - fontello/css/fontello-ie7.css