Converting Binary Restarts from Older to Newer Versions

Background

WW3 writes binary restart files and it's generally not recommended to switch versions of restart files. The version of the restart file is determined in the code by the VERINI variable defined in MODULE W3IORSMD. While previously a version number was used, we currently define a date in which a change to writing/reading the restart was made as the version number. There are checks in the code to ensure that the version number is correct to prevent using inconsistent restarts and model code. Sometimes only minor updates were made to the restarts and there is a use case for continuing to use the older restarts. In this case, the functionality in ww3_gint which is used to interpolate between various resolutions of grids for restarts can be updated to create a utility to convert from an older to newer version of restart. Because the number of versions could theoretically be endless, this is not a utility that is included in the develop branch with the main source code. This is simply instructions of how you might create a one-off program to update your restarts if appropriate and required.

Steps for converting old to new restarts

Determine model versions and compare

The first thing to do, is to determine the version of model code (and MODULE W3IORSMD) that your original restarts were created from and the second is to determine which version of restarts you plan to convert the restarts to. Then, compare the old and the new versions. This step is important so you understand what the differences are and if it's feasible to convert between these versions or not. Note, this is a personal judgement and will also help you understand if you need to set or calculate variables.

Also note the switch files used to create the original restart file. Note, it's not necessarily recommended to switch the switch file version, although it can be possible in some cases.

Create Old Version of W3ioros

In a clone of WW3 that contains the model version of restart that is the target version of the new restart file, copy the "old" version of model/src/w3iorsmd.F90 from the older clone to the new version renaming it model/src/w3iorsmdold.F90

Then in model/src/w3iorsmdold.F90 update the following:

• Rename MODULE W3IORSMD to MODULE W3IORSMDOLD
• Rename SUBROUTINE W3IORS to SUBROUTINE W3IORSOLD
• If you are converting from different switches, you will need to manually update W3IORSOLD to use the switches that you used before as you will compile the code with "new" switches. Again, note this is not necessarily recommended.
• Depending on how different the old and new versions of the code are, additional changes might be required. This will have to be based on your specific differences between the old and new that you found during the "compare".

Add new file to cmake list

In model/src/cmake/src_list.cmake within the set(ftn_src section, add w3iorsmdold.F90 after w3iorsmd.F90.

Update ww3_gint

The following updates in ww3_gint are required:

• Add a line to use the new module: USE W3IORSMDOLD, ONLY: W3IORSOLD
• In the section of code that ! 5.b Initialize and read the first set of restarts for base grids change the call from CALL W3IORS to CALL W3IORSOLD. Note there are two places where we call W3IORS, only one (the read) needs to be changed and there is a comment in the code pointing you to that call.

Note, other updates might need to be made depending on the differences between the old and new code. There's no way to say what those changes are in a general sense. Again, while certainly possible, it's not always recommended to do this.

Create new restart file by running ww3_gint

Create your input files (ww3_gint.inp, the mod_defs using the new code, but for the grid ofthat is associated with the original restart file and a mod_def for the grid of the targeted output), compile ww3_gint and run to generate your new input file. Note there's an example of converting restart files in the regression tests (see https://github.com/NOAA-EMC/WW3/pull/962 for details about adding this feature):

./bin/run_cmake_test -b slurm -o all -S -T -s MPI_OMPH -w work_c -m grdset_c -f -p srun -n 140  -t 4 ../model ww3_ufs1.2
mkdir -p ww3_ufs1.2/work_l
cp ww3_ufs1.2/work_c/restart.hafsl ww3_ufs1.2/work_l/restart.hafsl
./bin/run_cmake_test -b slurm -o all -S -T -s MPI_OMPH -w work_l -m grdset_l -f -p srun -n 140  -t 4 ../model ww3_ufs1.2

Note: If the grid is the same for the orignal and target, you might need to use a different name for each one, even if they are the same.