Merge branch 'CAM-ML' into add-yog-rebase

README.md

@@ -1,4 +1,92 @@
-# CAM: The Community Atmosphere Model
+# CAM-ML: A Fork of The Community Atmosphere Model Implementing a Machine Learning Convection Parameterisation
+
+This Fork of the CAM model is a version in which we are aiming to implement a new
+convection parameterisation, YOG.
+The parameterisation is a machine learning implementation using a neural net trained
+on high-resolution cloud-resolving simulations in the SAM model as described in:\
+
+- Yuval, J., O’Gorman, P.A.
+  _Stable machine-learning parameterization of subgrid processes for climate modeling at
+  a range of resolutions_
+  Nat Commun 11, 3295 (2020). DOI: [10.1038/s41467-020-17142-3](https://doi.org/10.1038/s41467-020-17142-3)
+- Yuval, J., O'Gorman, P.A., Hill, C.N.
+  _Use of Neural Networks for Stable, Accurate and Physically Consistent Parameterization of Subgrid Atmospheric Processes With Good Performance at Reduced Precision_
+  Geophysical Research Letters, 48, e2020GL091363 (2021). DOI: [10.1029/2020GL091363](https://doi.org/10.1029/2020GL091363)
+
+The work is contained in a `CAM-ML` branch which is based off the `cam_cesm2_1_rel_60`
+tag.
+
+## Using this model in a CESM Run
+
+### Obtaining CESM
+
+Clone a copy of CESM from git and checkout the `cesm2.1.5` tag on which this work is based:
+```
+git clone https://github.com/escomp/cesm.git my_cesm_sandbox_2_1
+cd my_cesm_sandbox_2_1/
+git checkout cesm2.1.5
+```
+
+### Setting CAM version in CESM
+
+To use this model in a CESM run you need to modify the `Externals.cfg` file in the
+main CESM directory to replace the CAM entry with:
+```toml
+[cam]
+branch = CAM-ML
+protocol = git
+repo_url = https://github.com/m2lines/CAM-ML
+local_path = components/cam
+externals = Externals_CAM.cfg
+required = True
+```
+This will pull the `CAM-ML` branch of this repo in as the CAM component.
+
+You can now run, from within the CESM root directory,
+```
+./manage_externals/checkout_externals
+```
+to fetch the external components.
+
+### Creating and running a case
+
+Details on creating a case can be found
+[here](https://ncar.github.io/CAM/doc/build/html/CAM6.0_users_guide/building-and-running-cam.html) on the NCAR website.
+For this work we are using the gate III testcase which can be set up by running:
+```
+./create_newcase --case <path_to_testcase_directory> --compset FSCAM --res T42_T42 --user-mods-dir ../../components/cam/cime_config/usermods_dirs/scam_gateIII --project NCGD0054
+```
+from `<cesm_root>/cime/scripts/`.
+
+Once this has been done then edit `user_nl_cam` for the case as detailed below.
+This is a CAM namelist generated from the default for the case.
+Add the following lines:
+
+1. `deep_scheme = 'YOG'`\
+    This will be the identifier for our new convection scheme.\
+    If running a comparison to the ZM scheme also add `run_deep_comp = 'on'`.
+3. `nn_weights = '<PATH/TO/WEIGHTS.nc>'`\
+    The path to the nn weights.
+4. `SAM_sounding = '<PATH/TO/SAM/SOUNDING.nc>'`\
+    The path to the SAM sounding for the NN.\
+    This file is generated using the `sounding_to_netcdf.py` script in the resources of the NN code.
+
+Also consider adding:
+```
+fincl2 = 'ZMDT', 'ZMDQ'
+fincl3 = 'YOGDT', 'YOGDQ'
+```
+to generate both ZM and YOG output diagnostics.
+
+We can then run `./case.setup` and `./case.build`.
+
+**Note:**  
+By default CESM will place output in `/glade/scratch/user/case/`
+and logs/restart files in `/glade/scratch/user/archive/case/`.
+To place all output with logs in `archive/case` switch 'short term archiving' on by
+editing `env_run.xml` in the case directory to change `DOUT_S` from `FALSE` to `TRUE`.
+
+## CAM Documentation
 
 CAM Documentation - https://ncar.github.io/CAM/doc/build/html/index.html