update order of conversion steps; rename step markdown files so this …

…is easier in the future

docs/conversion/step9.md → docs/conversion/back-to-cam.md

@@ -32,9 +32,9 @@ print $fh "$camsrcdir/src/atmos_phys/<parameterization>\n";
 /glade/campaign/cesm/cesmdata/tools/cprnc/cprnc
 cprnc <file1> <file2>
 ```
-- Optional step: if want to have additional testing... Once you believe it is working, repeat the [snapshot](step2.md) section to run CAM with this modified clone, generating snapshot files.
+- Optional step: if want to have additional testing... Once you believe it is working, make a [snapshot](create-snapshots.md) to run CAM with this modified clone.
     - Use the cprnc tool to compare the resulting CAM6 “after” snapshot file with your original CAM6 “after” snapshot file (from before the port). If they differ and you changed the internal calculations during your port, you will need to determine if these changes are expected and correct.  
-        - If they are different (and the changes are correct), then you will need to repeat the steps listed in the [Run CAM-SIMA](step8.md) section with the newly generated snapshot files from the modified CAM clone.
+        - If they are different (and the changes are correct), then you will need to repeat the steps listed in the [Run CAM-SIMA](run-cam-sima.md) section with the newly generated snapshot files from the modified CAM clone.
 
 ## Committing your changes
 

docs/conversion/step7.md → docs/conversion/check-metadata.md

@@ -12,7 +12,7 @@ cd <casedir>
 ```
 
 - Run `./preview_namelists` to see if the framework will generate the caps. A few possible outcomes:
-    - There are no errors and you are somehow a perfect person. Move on to the [next step](step8.md) and ultimately run the model
+    - There are no errors and you are somehow a perfect person. Move on to the [next step](run-cam-sima.md) and ultimately run the model
     - You get an error
         - Determine what the course of action should be based on the table below. Once you think you have addressed the issue, rerun `./preview_namelists` and repeat!
 
@@ -40,7 +40,7 @@ cd <casedir>
 </tr>
 <tr markdown>
    <td markdown>Variable can be traced back to a calculation in the CAM interface code</td>
-   <td markdown>Make an [interstitial](step5.md)</td>
+   <td markdown>Make an [interstitial](interstitials.md)</td>
 </tr>
 <tr markdown>
    <td markdown>None of the above criteria are met</td>
@@ -69,15 +69,15 @@ cd <casedir>
 </tbody>
 </table>
 
-Once you have validated your metadata, proceed to [8 - Run CAM-SIMA](step8.md)
+Once you have validated your metadata, proceed to [8 - Run CAM-SIMA](run-cam-sima.md)
 
 ## Procedure 1
 If the CAM variable can be traced back to a use statement, you may have to create or amend a SIMA-side metadata file.
 
 - Try to find the equivalent module and the "used" variable within it in CAM-SIMA
     - If you find it the module:
         - It already has a metadata file, move the variable in the Fortran to be with the other variables that have metadata. Then, add your variable to the appropriate place in the metadata file.
-        - It doesn't have a metadata file, create one and add your variable. You'll also have to add the ["html" tags](step1.md#1b-add-required-htmlinclude-lines) and potentially rearrange module-level variables so the only variable(s) under the tags are the ones you're providing metadata for.
+        - It doesn't have a metadata file, create one and add your variable. You'll also have to add the ["html" tags](convert-portable-layer.md#1b-add-required-htmlinclude-lines) and potentially rearrange module-level variables so the only variable(s) under the tags are the ones you're providing metadata for.
            - Then add the path to the metadata file to the `metadata_file` section of `$CAM-SIMA/src/data/registry.xml`
     - If you can't find the module, consult with the other CAM SEs
 

docs/conversion/conversion-background.md

@@ -101,4 +101,4 @@ git push -u <your_github_userid> <physics_branch_name>
 - If you want to see changes in the atmospheric_physics repo, make sure you are in src/physics/ncar_ccpp before you issue the “git status” command.
 - All other git commands will be relative to your current working directory as well.
 
-Congratulations! You've set up your sandbox! Proceed to [1 - Convert the "portable" layer](./step1.md)
+Congratulations! You've set up your sandbox! Proceed to [1 - Convert the "portable" layer](convert-portable-layer.md)

docs/conversion/step1.md → docs/conversion/convert-portable-layer.md

@@ -1,3 +1,7 @@
+---
+title: 1 - Convert the "portable" layer
+---
+
 # 1 - Convert the "portable" layer
 
 ## Move the portable layer to atmospheric_physics
@@ -20,7 +24,7 @@ Many CAM schemes have more than one "run" or "tend" method contained within them
 - If there is shared, module-level data or shared subroutines which are called internally, put these all in a <scheme_name>_common.F90 module.
 
 ## 1a - Change routine names
-Convert the original routines (except readnl - we'll get to that [later](step4.md)!) in the file(s) you copied over to $CAM-SIMA/src/physics/ncar_ccpp to one or more of the following 5 subroutines:
+Convert the original routines (except readnl - we'll get to that [later](create-namelist-xml.md)!) in the file(s) you copied over to $CAM-SIMA/src/physics/ncar_ccpp to one or more of the following 5 subroutines:
 !!! note "`<parameterization>` should be the full name of your module"
 
     For example, if you are converting the `tj2016` `precip_tend` function, then `<parameterization>` would be `tj2016_precip_tend`.
@@ -76,7 +80,7 @@ Remove all “use” statements and have the data appear in the calling list (th
 - If a use statement is bringing in an external routine (not part of the parameterization package), you have a few options (consult with the other CAM SEs on how to proceed):
     1. If the routine already exists in the core CAM-SIMA code tree (not in `ncar_ccpp`), ask another CAM SE about how and where to call the routine within the CAM-SIMA run loop and set a variable to be passed into the physics (variable will need to be added to the registry)
     1. CCPP-ize the external routine and/or module and add it to the suite definition file before or after the parameterization
-    1. Postpone CCPP-zing the external routine and add it as a dependency (we'll revisit this in [create metadata](step3.md))
+    1. Postpone CCPP-zing the external routine and add it as a dependency (we'll revisit this in [create metadata](create-metadata.md))
 - Comment out `outfld`, `addfld` use statements for now
     - Also comment out the `addfld` and `outfld` calls within the module(s)
 
@@ -167,4 +171,4 @@ print $fh "$camsrcdir/src/atmos_phys/<schemename>\n";
 - Modify code as needed until this modified code compiles and runs properly.
 - If you want to benchmark your development to this point, you will need to open PRs to both NCAR/atmospheric_physics and ESCOMP/CAM.
 
-Proceed to [2 - Create snapshots of CAM](step2.md)
+Proceed to [2 - Create metadata](create-metadata.md)

docs/conversion/step3.md → docs/conversion/create-metadata.md

@@ -1,4 +1,4 @@
-# 3 - Create metadata
+# 2 - Create metadata
 
 ## Create template
 To create a template metadata file based on the parameterization, run the following command in the directory with the routine you are converting (<parameterization>.F90):
@@ -8,7 +8,7 @@ python $CAM-SIMA/ccpp_framework/scripts/ccpp_fortran_to_metadata.py <parameteriz
 
 If you get errors:
 
-1. Confirm you included the [argtable lines](step1.md#1b-add-required-htmlinclude-lines) above each routine
+1. Confirm you included the [argtable lines](convert-portable-layer.md#1b-add-required-htmlinclude-lines) above each routine
 1. If you see a message "Missing local variables" and the variable is there, it may be missing its intent attribute
 1. Hopefully other errors will be easy to address; consult other CAM SEs if there's any remaining confusion/errors
 
@@ -71,4 +71,4 @@ Replace all `enter_*` sections with appropriate information (standard_name, unit
 - constituents: see [constituent usage](../design/constituents.md/#constituent-usage)
     - you can tell a variable is a constituent if it is in the `state%q` array in CAM (may have to trace back in the code a bit)
 
-Once you have created your metadata, proceed to [4 - Create namelist XML file](step4.md)
+Once you have created your metadata, proceed to [3 - Create namelist XML file](create-namelist-xml.md)

docs/conversion/step4.md → docs/conversion/create-namelist-xml.md

@@ -1,4 +1,4 @@
-# 4 - Create namelist XML file
+# 3 - Create namelist XML file
 If your scheme has a `readnl` scheme, create an .xml file with the same name as the scheme which uses the namelist (place it in the same location as the parameterization in `ncar_ccpp`.
 
 - The filename should be `<scheme>_namelist.xml`
@@ -54,6 +54,6 @@ The CCPP Framework will autogenerate the namelist reader based on the elements i
 </entry_id_pg>
 ```
 !!!Note "namelist values"
-    When populating the value fields, you don't need to port all of them at this time.  You need to put in the value that was used in making the snapshot file, but the rest will be ported once all schemes have been ported.
+    When populating the value fields, you don't need to port all of them at this time.  You need to put in the value that is used by default by CAM, but the rest will be ported once all schemes have been ported.
 
-Once you have made your namelist file, proceed to [5 - Interstitials](step5.md)
+Once you have made your namelist file, proceed to [4 - Interstitials](interstitials.md)

docs/conversion/step6.md → docs/conversion/create-sdf.md

@@ -1,4 +1,4 @@
-# 6 - Create an SDF
+# 5 - Create an SDF
 The **Suite Definition File (SDF)** tells the CCPP-Framework which schemes will be run in what order. For more, see [CCPP in CAM-SIMA](../design/ccpp-in-cam-sima.md)
 
 - In `$CAM-SIMA/src/physics/ncar_ccpp`, create `suite_<parameterization>.xml`. This is your SDF!
@@ -27,4 +27,4 @@ For example: if your parameterization requires dry water vapor, you'll want to a
 - `<scheme>wet_to_dry_water_vapor</scheme>` before your core parameterization scheme to convert water vapor to a dry mixing ratio (CAM-SIMA has "wet")
 - `<scheme>dry_to_wet_water_vapor</scheme>` after your parameterization scheme to convert back to a wet mixing ratio to return to CAM-SIMA
 
-Once you have created your SDF, proceed to [7 - Check metadata](step7.md)
+Once you have created your SDF, proceed to [6 - Create snapshots of CAM](create-snapshots.md)

docs/conversion/step2.md → docs/conversion/create-snapshots.md

@@ -1,7 +1,7 @@
-# 2 - Create snapshots of CAM
+# 6 - Create snapshots of CAM
 
 ## Configure and set-up CAM snapshot
-Make a normal CAM run using cam_snapshot to capture before and after files using a compset which exercises the parameterization being converted.
+Make a normal **CAM** (not CAM-SIMA) run using cam_snapshot to capture before and after files using a compset which exercises the parameterization being converted.
 
 - The cam_snapshot feature dumps the entire state/tend/pbuf/cnst arrays to netCDF files.
     - The variables `cam_snapshot_before_num` and `cam_snapshot_after_num` are the output file numbers (offset by 1 as they are in CAM).
@@ -120,4 +120,4 @@ On **izumi**, save your converted snapshot files in:
     - However, if you decide not to, then do make sure that all of your other CAM runs also have debug flags off, as otherwise you can get differences in the results that are solely due to compiler settings, and not your code changes.
 1. You should generate at least one set of snapshot files using GNU on derecho with DEBUG=TRUE, as these will be saved for use in the CAM-SIMA physics testbed to prevent unexpected answer changes.
 
-Once you have created your snapshot files, proceed to [3 - Create metadata](step3.md)
+Once you have created your snapshot files, proceed to [7 - Run CAM-SIMA](run-cam-sima.md)

docs/conversion/step5.md → docs/conversion/interstitials.md

@@ -1,4 +1,4 @@
-# 5 - Interstitials
+# 4 - Interstitials
 ## Overview
 An **interstitial** is a scheme that does calculations or variable modifications to connect what the host model has to what the scheme requires and vice versa.
 
@@ -67,7 +67,7 @@ An example of how this is done can be found ~line 276 in:
 $CAM/src/physics/simple/kessler_cam.F90
 ```
 
-Proceed to [6 - Create an SDF](step6.md). 
+Proceed to [5 - Create an SDF](create-sdf.md). 
 
 !!! Warning
     You may have to revisit this step as you debug your code.

docs/conversion/step8.md → docs/conversion/run-cam-sima.md

@@ -34,7 +34,7 @@ if (DEBUG)
 endif()
 ```
 
-Once you have successfully run CAM-SIMA and all answer changes have either accepted or fixed, proceed to [9 - Bring back into CAM](step9.md)
+Once you have successfully run CAM-SIMA and all answer changes have either accepted or fixed, proceed to [9 - Bring back into CAM](back-to-cam.md)
 
 ## Tips for uncovering unexpected answer changes
 

mkdocs.yml

@@ -1,4 +1,37 @@
 site_name: CAM-SIMA
+nav:
+  - Home: index.md
+  - Conversion:
+    - conversion/conversion-background.md
+    - conversion/convert-portable-layer.md
+    - conversion/create-metadata.md
+    - conversion/create-namelist-xml.md
+    - conversion/interstitials.md
+    - conversion/create-sdf.md
+    - conversion/create-snapshots.md
+    - conversion/check-metadata.md
+    - conversion/run-cam-sima.md
+    - conversion/back-to-cam.md
+    - conversion/walkthrough.md
+  - Design:
+    - design/cam-build-process.md
+    - design/cam-run-process.md
+    - design/ccpp-in-cam-sima.md
+    - design/constituents.md
+    - design/history.md
+    - design/sima-design-goals.md
+  - Development:
+    - development/cam-coding-standards.md
+    - development/cam-testing.md
+    - development/debugging.md
+    - development/git-basics.md
+    - development/git-faq.md
+    - development/git-fleximod.md
+    - development/tool-recommendations.md
+  - Usage:
+    - usage/creating-a-case.md
+    - usage/history.md
+
 plugins:
   - search
 theme: