Added yaml README and add comments to experiment yaml explaining how …

…to run fre make

yamls/NWA12/CEFI_NWA12_cobalt.yaml

@@ -1,22 +1,47 @@
-# POSTPROCESSING GUIDE
+# USAGE
+#
+# The following yaml is designed to compile and postprocess the ocean_monthly component of the CEFI_NWA12_COBALT_V1 experiment
+# Full Documentation is available here: https://noaa-gfdl.github.io/fre-cli/index.html
+# 
+# 0.) Begin by setting up your environment by calling module load fre/2025.01
+#
+# For modularity and compatibility with with cylc workflow engine, fre/2025.01 splits up the compile and post processcing process 
+# into several sub steps.
 #
-# The following yaml is designed to postprocess the ocean_monthly component of the 2024_06 version of the CEFI_NWA12_COBALT_V1 experiment
-# if postprocessing data from a different version of this experiment, be sure to change the FRE_STEM variable before postprocessing
+# COMPILE GUIDE - BAREMETAL RUN
+# 
+# 1.) Create script that will be used to checkout model components
+# fre make create-checkout -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod
+# 
+# 2.) Create Makefile
+# fre make create-makefile -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod
 #
-# Quick start instructions and source code can be found here: https://github.com/NOAA-GFDL/fre-cli/tree/main/fre/pp
+# 3.) Create script that will compile the model, and OPTIONALLY run it with the --execute flag. You can manually run the 
+# compile script after this step as well
+# fre make create-compile -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod --execute
 #
-# 0.) Load module on GFDL Analysis: module load fre/canopy
+# COMPILE GUIDE - CONTAINERS
 #
-# For modularity and compatibility with with cylc workflow engine, fre/canopy splits up the post processcing process into several sub steps:
+# 1.) Create checkout script with the "no parallel checkouts option" - this is required for container builds
+# fre make create-checkout -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod --npc
+# 
+# 2.) Create Makefile AND a Docker file. You can then build the container by manually running the createContainer.sh
+# script, or by OPTIONALLY including the --execute file when creating the container
+# fre make create-makefile -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod
+# fre make create-dockerfile -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod --execute
+#
+# POSTPROCESSING GUIDE
 #
+# 0.) Load module on GFDL Analysis: module load fre/2025.01
+# 
 # 1.) Checkout the git repo containing postprocessing scripts and related files with the folowing command:
 # fre pp checkout -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod
 #
 # 2.) Combine your main yaml and experiment yamls into a single yaml, then set up the cylc-src dir with the configure-yaml command:
 # fre yamltools combine-yamls -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod -y CEFI_NWA12_cobalt.yaml
 # fre pp configure-yaml -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod -y combined-CEFI_NWA12_COBALT_V1.yaml
 #
-#     2a.) Fre/canopy does not automatically create the pp dir for you, so you will have to mkdir this first to pass the validator:
+#     2a.) fre/2025.01 does not automatically create the pp dir for you, so you will have to mkdir this first to pass the validator:
 #     mkdir /archive/$USER/fre/cefi/NWA/2024_06/CEFI_NWA12_COBALT_V1/gfdl.ncrc5-intel22-prod/pp
 #
 #     2b.) (OPTIONAL, BUT RECOMMENDED): Create a list of available tar files within your history tar archives to allow fre to catch a wider variety of errors
@@ -36,7 +61,7 @@
 
 
 fre_properties: 
-    - &FRE_STEM       "fre/cefi/NWA/2025_01"
+    - &FRE_STEM       "fre/cefi/NWA/2024_11"
 
     - &PP_START_YEAR  "1993"
     - &PP_END_YEAR    "2019"

yamls/NWA12/README.md

@@ -0,0 +1,112 @@
+# FRE yamls
+
+The latest version of the FMS Runtime Environment uses yamls instead of xmls to execute the FRE workflow. This folder contains experiment, compile, and platform yamls that can be used with the latest version of `fre` to compile and post process the `CEFI_NWA12_Cobalt_V1` experiment. The compiled experiment can then be run in conjuction with `fre/bronx-23` and the existing xmls in the `xml/NWA12` directory. 
+
+The following sections assume that you are compiling and running experiments on Gaea C5, and then conducting postprocessing on GFDL's PPAN system. The `platforms.yaml` does support compilation on C6, but `bronx-23` does not support containerized runs on C6 - baremetal runs, however, are supported on C6.
+
+## Compile the Experiment. 
+
+Begin by loading the appropriate modules on Gaea C5: 
+```
+module use -a /ncrc/home2/fms/local/modulefiles
+module load fre/2025.01
+```
+
+`fre/2025.01` supports both containerized compilation and bare-metal compilation, with very similar steps for both targets. 
+
+### Baremetal Compilation 
+
+Run the following command create the script that will be used to checkout the model components:
+```
+fre make create-checkout -y CEFI_NWA12_cobalt.yaml -p ncrc5.intel23 -t prod
+```
+
+Create the Makefile for the experiment: 
+```
+fre make create-makefile -y CEFI_NWA12_cobalt.yaml -p ncrc5.intel23 -t prod
+```
+
+Create the script that actually compiles the experiment, and optionally run the script by passing in the --execute flag
+```
+fre make create-compile -y CEFI_NWA12_cobalt.yaml -p ncrc5.intel23 -t prod --execute
+```
+
+### Containerized Compilation
+
+Compiling the experiment into a container is a similar process. The only changes are 1.) passing in the --npc flag during the checkout step to prevent parallel checkouts, 2.) changing you platform to `hpcme.2023` and 3.) creating a Dockerfile and container creation script instead of a compilation script. Note that the Dockerfile will compile the model within the container as part of the build process. 
+
+```
+fre make create-checkout -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod --npc
+fre make create-makefile -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod
+fre make create-dockerfile -y CEFI_NWA12_cobalt.yaml -p hpcme.2023 -t prod --execute
+```
+
+## Running the Experiment
+
+`fre/2025.01` does not currently support running experiments with yamls, so in order to run the compiled experiment in fre, you will have to use the existing xmls along with `fre/bronx`. Make sure the `FRE_STEM` set in the xml matches the `FRE_STEM` set in the experiment yaml.
+
+### Baremetal Run
+
+Baremetal experiments can be run using the same run [instructions](https://github.com/NOAA-GFDL/CEFI-regional-MOM6/tree/main/xmls) available in the xmls directory. Be sure to load the modules described in that page before running `frerun`. 
+
+### Containerized Run
+Current xmls can be used for containerized runs, as well, so long as the following changes are made: 
+
+1.) Run `module load fre/bronx-23` and change the `FRE_VERSION` property of the xml to `bronx-23`.
+2.) Right below the `<experiment name="CEFI_NWA12_COBALT_V1" inherit="MOM6_SIS2_GENERIC_4P_compile_symm">` tag, add a tag with a path to your `.sif` singularity image file: 
+    ```
+    <container file="path/to/container/"/>
+    ```
+
+With these changes, you should be able to run the experiment by calling `frerun` with an extra `--container` flag
+```
+frerun -x CEFI_NWA12_cobalt.xml -p ncrc5.intel23 -t prod CEFI_NWA12_COBALT_V1 --container
+```
+
+
+## Postprocessing the Experiment
+Like `fre make`, postprocessing is split into several subcommands to improve modularity. On PPAN, load the appropriate module: 
+```
+module load fre/2025.01
+```
+
+Checkout the git repo containing postprocessing scripts and related files with the folowing command:
+```
+fre pp checkout -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod
+```
+
+Combine your main yaml and experiment yamls into a single yaml, then set up the cylc-src dir with the configure-yaml command:
+```
+fre yamltools combine-yamls -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod -y CEFI_NWA12_cobalt.yaml
+fre pp configure-yaml -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod -y combined-CEFI_NWA12_COBALT_V1.yaml
+```
+
+`fre/2025.01` does not automatically create the pp dir for you, so you will have to mkdir this first to pass the validator:
+```
+mkdir /archive/$USER/fre/cefi/NWA/2024_06/CEFI_NWA12_COBALT_V1/gfdl.ncrc5-intel22-prod/pp
+```
+
+(OPTIONAL, BUT RECOMMENDED): Create a list of available tar files within your history tar archives to allow fre to catch a wider variety of errors
+```
+tar -tf /archive/$USER/fre/cefi/NWA/2024_06/CEFI_NWA12_COBALT_V1/gfdl.ncrc5-intel22-prod/history/19930101.nc.tar | grep -v tile[2-6] | sort > /home/$USER/cylc-src/CEFI_NWA12_COBALT_V1__gfdl.ncrc5-intel22__prod/history-manifest
+```
+
+Validate that all configuration files are correct
+```
+fre pp validate -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod
+```
+
+Create the cylc-run directory containing the final version of configuration files, scripts, and output directories
+```
+fre pp install -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod
+```
+
+Run post processing
+```
+fre pp run -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod
+```
+
+To monitor the status of each post processing step, run the following command:
+```
+fre pp status -e CEFI_NWA12_COBALT_V1 -p gfdl.ncrc5-intel22 -t prod
+```