Merge branch 'mahf708/eamxx/pyscream-docs' into next (PR #6748)

Enables building eamxx docs on E3SM repo; adds pyscream prelim docs as well.
Add content to eamxx user and dev guide main pages.

.github/workflows/eamxx-gh-pages.yml

@@ -9,15 +9,15 @@ on:
     branches: [ master ]
     # Only if docs-related files are touched
     paths:
-      - components/eamxx/mkdocs.yaml
+      - components/eamxx/mkdocs.yml
       - components/eamxx/docs/**
       - components/eamxx/cime_config/namelist_defaults_scream.xml
   # Runs every time a PR is open against master
   pull_request:
     branches: [ master ]
     # Only if docs-related files are touched
     paths:
-      - components/eamxx/mkdocs.yaml
+      - components/eamxx/mkdocs.yml
       - components/eamxx/docs/**
       - components/eamxx/cime_config/namelist_defaults_scream.xml
 

components/eamxx/docs/developer/index.md

@@ -1 +1,16 @@
-# SCREAM Developer Guide
+# EAMxx Developer Guide
+
+### [Installation](../common/installation.md)
+### [Style Guide](style_guide.md)
+### [Kokkos and EKAT](kokkos_ekat.md)
+### [Source Tree](source_tree.md)
+### Important Data Structures
+  * [Fields](field.md)
+  * [Grids and Remappers](grid.md)
+  * [Atmosphere Processes](processes.md)
+  * [Managers](managers.md)
+### [I/O](io.md)
+### Testing
+  * [Standalone](standalone_testing.md)
+  * [Full Model](cime_testing.md)
+  * [CI and Nightly Testing](ci_nightly.md) 

components/eamxx/docs/developer/kokkos_ekat.md

@@ -56,8 +56,9 @@ where
 - `DataType`: scalar type of the view, given as `ScalarType`+`*`(x's number of
   run-time dimensions). E.g., a 2D view of doubles will have `DataType =
   double**`. There is also an ability to define compile-time dimensions by
-  using `[]`, see [Kokkos wiki section on views](<https://kokkos.org/kokkos-core->
-  wiki/API/core/view/view.html).
+  using `[]`, see
+  [Kokkos wiki section on views]
+  (<https://kokkos.org/kokkos-core-wiki/API/core/view/view.html).
 - `LayoutType`: mapping of indices into the underlying 1D memory storage. Types
   are:
   - `LayoutRight` (used in EAMxx): strides increase from the right most to the

components/eamxx/docs/developer/processes.md

@@ -54,7 +54,7 @@ of several steps:
 - After creating all fields (based on AP's requests), the AD passes a copy of
   each input and output field to the AP's. These fields will be divided in
   "required" and "computed", which differ in that the former are only passed
-  to the AP's as 'read-only' fields (see the [field](field.md#Field)
+  to the AP's as 'read-only' fields (see the [field](field.md)
   documentation for more details)
 - The AP's are queried for how much scratch memory they may need at run time.
   After all AP's communicate their needs, the AD will provide a pointer to

components/eamxx/docs/index.md

@@ -1,6 +1,6 @@
 # The E3SM Atmosphere Model in C++ (EAMxx)
 
-EAMxx 
+##EAMxx
 EAMxx is almost completely different in all ways from the atmosphere model used for E3SM versions 1-3. 
 
 

components/eamxx/docs/user/index.md

@@ -1,4 +1,4 @@
-# SCREAM User Guide
+# EAMxx User Guide
 
 This section contains documentation on how to create, setup, and run CIME cases with EAMxx as the atmosphere component.
 It is assumed that the reader has a familiarity with [CIME case
@@ -8,3 +8,14 @@ that the user knows how to create a case, and what the `case.setup`, `case.build
 
 This user guide is still under construction. In the meantime, in case you can't find the information you need,
 you may visit our public confluence [EAMxx user guide](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3858890786/EAMxx+User+s+Guide).
+
+### [EAMxx case basics](eamxx_cases.md)
+### [Model input](model_input.md)
+### [Model output](model_output.md)
+### [Nudging](nudging.md)
+### [Extra radiation calls](clean_clear_sky.md)
+### [COSP](cosp.md)
+### [Regionally Refined EAMxx](rrm_eamxx.md)
+### [Doubly Periodic EAMxx](dp_eamxx.md)
+### [PySCREAM](pyscream.md)
+

components/eamxx/docs/user/pyscream.md

@@ -0,0 +1,73 @@
+# PySCREAM
+
+PySCREAM is currently under heavy development and may contain some
+rough edges. If you encounter any issues, please report them on the
+team on
+[github discussions](https://github.com/E3SM-Project/E3SM/labels/eamxx).
+Likewise, if you have questions or would like to request features,
+please post them on the
+[github discussions](https://github.com/E3SM-Project/E3SM/labels/eamxx).
+
+## Quick Start
+
+For now, the only way to use pyscream is to either build it on your own
+or use our prebuilt conda binaries. We prefer for you to use the latter.
+In a conda environment, please use the following command to install it:
+
+```bash
+conda install -c mahf708 pyscream=0.0.2
+```
+
+It is recommended to use the latest version of pyscream, wich is
+currently 0.0.2. As you can see, it is a young package with a lot of
+potential. We do not guarantee that the API will remain stable, but we
+will try to document any changes as frequently as we could.
+
+## Examples
+
+We provide an example to demo calling the radiation process (RRTMGP).
+More examples are on the way. If you'd like to add your example,
+please feel free to submit a PR.
+
+### RRTMGP
+
+```python
+from mpi4py import MPI
+import pyscream
+
+pyscream.init()
+
+dt = 1800
+t0_str = "2020-10-10-00000"
+
+ic_file = "/lcrc/group/e3sm/public_html/inputdata/atm/scream/init/screami_unit_tests_ne2np4L72_20220822.nc"
+ncols = 218
+nlevs = 72
+pyscream.create_grids_manager(ncols,nlevs, ic_file)
+
+rad_dict = {
+    "column_chunk_size": 123,
+    "active_gases": ["h2o", "co2", "o3", "n2o", "co" , "ch4", "o2", "n2"],
+    "orbital_year": 1990,
+    "log_level": "info",
+    "do_aerosol_rad": False,
+    "rrtmgp_coefficients_file_sw": "/lcrc/group/e3sm/data/inputdata/atm/scream/init/rrtmgp-data-sw-g112-210809.nc",
+    "rrtmgp_coefficients_file_lw": "/lcrc/group/e3sm/data/inputdata/atm/scream/init/rrtmgp-data-lw-g128-210809.nc",
+    "rrtmgp_cloud_optics_file_sw": "/lcrc/group/e3sm/data/inputdata/atm/scream/init/rrtmgp-cloud-optics-coeffs-sw.nc",
+    "rrtmgp_cloud_optics_file_lw": "/lcrc/group/e3sm/data/inputdata/atm/scream/init/rrtmgp-cloud-optics-coeffs-lw.nc",
+}
+
+rad = pyscream.AtmProc(rad_dict, 'RRTMGP')
+rad.read_ic(ic_file)
+rad.initialize(t0_str)
+
+t = rad.get_field("T_mid")
+tm = t.get()
+
+print(tm[5,5], flush=True)
+
+rad.run(dt)
+rad.run(dt)
+
+print(tm[5,5], flush=True)
+```

components/eamxx/mkdocs.yaml → components/eamxx/mkdocs.yml

@@ -12,6 +12,7 @@ nav:
     - 'COSP': 'user/cosp.md'
     - 'Regionally Refined EAMxx': 'user/rrm_eamxx.md'
     - 'Doubly Periodic EAMxx': 'user/dp_eamxx.md'
+    - 'PySCREAM': 'user/pyscream.md'
   - 'Developer Guide':
     - 'Overview': 'developer/index.md'
     - 'Installation': 'common/installation.md'