NVIDIA · ktangsali · Oct 3, 2023 · Aug 23, 2023 · Aug 23, 2023 · Aug 23, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,7 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- Fixed an issue when loading a checkpoint which contains `scaler_state_dict`, but no `scaler` provided to update. 
+- Fixed an issue when loading a checkpoint which contains `scaler_state_dict`, but no
+    `scaler` provided to update.
 
 ### Security
 

diff --git a/Dockerfile b/Dockerfile
@@ -38,3 +38,4 @@ FROM deploy as docs
 RUN pip install "tensorflow>=2.9.0" "warp-lang>=0.6.0" "black==22.10.0" "interrogate==1.5.0" "coverage==6.5.0" "protobuf==3.20.0"
 # Install packages for Sphinx build
 RUN pip install "recommonmark==0.7.1" "sphinx==5.1.1" "sphinx-rtd-theme==1.0.0" "pydocstyle==6.1.1" "nbsphinx==0.8.9" "nbconvert==6.4.3" "jinja2==3.0.3"
+RUN wget https://github.com/jgm/pandoc/releases/download/3.1.6.2/pandoc-3.1.6.2-1-amd64.deb && dpkg -i pandoc-3.1.6.2-1-amd64.deb  
diff --git a/docs/Makefile b/docs/Makefile
@@ -18,3 +18,17 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+convert-markdown-to-rst:
+	@echo "Converting Markdown files to reStructuredText..."
+	@mkdir -p examples
+	@find ../examples -name '*.md' -type f -exec sh -c ' \
+		mkdir -p "examples/$$(dirname {})"; \
+		pandoc "{}" -o "examples/$$(dirname {})/$$(basename -s .md {}).rst"; \
+		sed -i "/:alt:/,/[^:]*:/d" "examples/$$(dirname {})/$$(basename -s .md {}).rst"; \
+		sed -i "s|.. figure:: ../../../docs/img|.. figure:: ../../../img|g" "examples/$$(dirname {})/$$(basename -s .md {}).rst" \
+	' \;
+
+html: convert-markdown-to-rst
+	@echo "Running custom commands..."
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/img/bloodflow_1d_mgn_geometries.png b/docs/img/bloodflow_1d_mgn_geometries.png
diff --git a/docs/img/bloodflow_1d_mgn_results.gif b/docs/img/bloodflow_1d_mgn_results.gif
diff --git a/docs/index.rst b/docs/index.rst
@@ -10,6 +10,48 @@ Welcome to Modulus Launch's documentation!
    api/modulus.launch.logging.rst
    api/modulus.launch.utils.rst
 
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples Summary
+   :name: Examples Summary
+
+   examples/README.rst
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples: Weather and Climate
+   :name: Examples: Weather and Climate
+
+   examples/weather/dataset_download/README.rst
+   examples/weather/fcn_afno/README.rst
+   examples/weather/fcn_sfno/README.rst
+   examples/weather/dlwp/README.rst
+   examples/weather/graphcast/README.rst
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples: CFD
+   :name: Examples: CFD
+
+   examples/cfd/ahmed_body_mgn/README.rst
+   examples/cfd/vortex_shedding_mgn/README.rst
+   examples/cfd/darcy_fno/README.rst
+   examples/cfd/darcy_nested_fnos/README.rst
+   examples/cfd/navier_stokes_rnn/README.rst
+   examples/cfd/gray_scott_rnn/README.rst
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples: Healthcare
+   :name: Examples: Healthcare
+
+   examples/healthcare/bloodflow_1d_mgn/README.rst
+
+
 Indices and tables
 ==================
 

diff --git a/examples/healthcare/bloodflow_1d_mgn/README.md b/examples/healthcare/bloodflow_1d_mgn/README.md
@@ -1,8 +1,8 @@
 # MeshGraphNet for Reduced-Order cardiovascular simulations
 
 This example implements the one-dimensional Reduced-Order model based on
-MeshGraphNet presented in the paper [`Learning Reduced-Order Models for Cardiovascular
-Simulations with Graph Neural Networks`](https://arxiv.org/abs/2303.07310)
+MeshGraphNet presented in the paper [Learning Reduced-Order Models for Cardiovascular
+Simulations with Graph Neural Networks](https://arxiv.org/abs/2303.07310)
 (Pegolotti et al, 2023).
 
 ## Problem overview

diff --git a/examples/weather/dataset_download/README.md b/examples/weather/dataset_download/README.md
@@ -1,17 +1,36 @@
 # ERA5 Data Downloader and Converter
 
-This repository provides tools for downloading ERA5 datasets via the Climate Data Store (CDS) API and processing them into formats suitable for machine learning. Users can flexibly select different meteorological variables for their training dataset.
+This repository provides tools for downloading ERA5 datasets via the Climate Data Store
+(CDS) API and processing them into formats suitable for machine learning. Users can
+flexibly select different meteorological variables for their training dataset.
 
-# Files Overview
-1. `start_mirror.py` starts by initializing the `ERA5Mirror` class, which will take care of downloading the ERA5 data and saving it in Zarr format as well as HDF5 conversion.
-2. `era5_mirror.py` - Contains the ERA5Mirror class responsible for downloading ERA5 datasets from the CDS API and storing them in Zarr format.
-3. `conf/config_tas.yaml` - Configuration file for `start_mirror.py`, which dictates the parameters for downloading and processing. This config file will just download the surface temperature variable however if you would like a more complete dataset such as the one used to train [FourCastNet](https://arxiv.org/abs/2202.11214), please use `conf/config_34var.yaml`.
+## Files Overview
 
-# How to Use
-1. Make sure you have the CDS API key setup following [these instructions](https://cds.climate.copernicus.eu/api-how-to).
-2. Run the main script, `python start_mirror.py`. This will perform all actions to generate HDF5 files needed for training. First it will download and save all variables as Zarr arrays. This may take a substantial amount of time. If the process gets interrupted, it saves the state of the download process, and you can restart. Restarting while changing date ranges for download may cause issues. Therefore, restarting should be done while keeping the same date configs. After the download is complete, the desired variables will be saved as HDF5 files in a standardized format that can be used by the datapipes seen in forecast training recipes such as `fcn_afno`.
+1. `start_mirror.py` starts by initializing the `ERA5Mirror` class, which will take care
+    of downloading the ERA5 data and saving it in Zarr format as well as HDF5 conversion.
+2. `era5_mirror.py` - Contains the ERA5Mirror class responsible for downloading ERA5
+    datasets from the CDS API and storing them in Zarr format.
+3. `conf/config_tas.yaml` - Configuration file for `start_mirror.py`, which dictates the
+    parameters for downloading and processing. This config file will just download the
+    surface temperature variable however if you would like a more complete dataset such
+    as the one used to train [FourCastNet](https://arxiv.org/abs/2202.11214),
+    please use `conf/config_34var.yaml`.
 
-# Configuration File
+## How to Use
+
+1. Make sure you have the CDS API key setup following
+    [these instructions](https://cds.climate.copernicus.eu/api-how-to).
+2. Run the main script, `python start_mirror.py`. This will perform all actions to
+    generate HDF5 files needed for training. First it will download and save all
+    variables as Zarr arrays. This may take a substantial amount of time. If the process
+    gets interrupted, it saves the state of the download process, and you can restart.
+    Restarting while changing date ranges for download may cause issues. Therefore,
+    restarting should be done while keeping the same date configs. After the download is
+    complete, the desired variables will be saved as HDF5 files in a standardized format
+    that can be used by the datapipes seen in forecast training recipes such as
+    `fcn_afno`.
+
+## Configuration File
 
 The config files contain several configurations you can modify,
 
@@ -25,5 +44,7 @@ The config files contain several configurations you can modify,
 - `compute_mean_std`: Whether or not to compute global mean and standard deviation.
 - `variables`: ERA5 variables to be downloaded.
 
-# Note
-Make sure to handle your CDS API key with care. Always keep it confidential and avoid pushing it to public repositories.
+## Note
+
+Make sure to handle your CDS API key with care. Always keep it confidential and avoid
+pushing it to public repositories.
diff --git a/examples/weather/dlwp/data_curation/README.md b/examples/weather/dlwp/data_curation/README.md
@@ -6,14 +6,49 @@
 ## Note
 
 To run the `post_processing.py` script, you need the map files.
-These map files can be generated using [TempestRemap](https://github.com/ClimateGlobalChange/tempestremap) library.
-Once the library is installed, the below sequence of commands can be run to generate the map files.
+These map files can be generated using
+[TempestRemap](https://github.com/ClimateGlobalChange/tempestremap) library.
+Once the library is installed, the below sequence of commands can be run to generate the
+map files.
 
 ```bash
-GenerateRLLMesh --lat 721 --lon 1440 --file out_latlon.g --lat_begin 90 --lat_end -90 --out_format Netcdf4
-GenerateCSMesh --res <desired-res> --file out_cubedsphere.g --out_format Netcdf4
-GenerateOverlapMesh --a out_latlon.g --b out_cubedsphere.g --out overlap_latlon_cubedsphere.g --out_format Netcdf4
-GenerateOfflineMap --in_mesh out_latlon.g --out_mesh out_cubedsphere.g --ov_mesh overlap_latlon_cubedsphere.g --in_np 1 --in_type FV --out_type FV --out_map map_LL_CS.nc --out_format Netcdf4
-GenerateOverlapMesh --a out_cubedsphere.g --b out_latlon.g --out overlap_cubedsphere_latlon.g --out_format Netcdf4
-GenerateOfflineMap --in_mesh out_cubedsphere.g --out_mesh out_latlon.g --ov_mesh overlap_cubedsphere_latlon.g --in_np 1 --in_type FV --out_type FV --out_map map_CS_LL.nc --out_format Netcdf4
+GenerateRLLMesh \
+    --lat 721 \
+    --lon 1440 \
+    --file out_latlon.g \
+    --lat_begin 90 \
+    --lat_end -90 \
+    --out_format Netcdf4
+GenerateCSMesh \
+    --res <desired-res> \
+    --file out_cubedsphere.g \
+    --out_format Netcdf4
+GenerateOverlapMesh \
+    --a out_latlon.g \
+    --b out_cubedsphere.g \
+    --out overlap_latlon_cubedsphere.g \
+    --out_format Netcdf4
+GenerateOfflineMap \
+    --in_mesh out_latlon.g \
+    --out_mesh out_cubedsphere.g \
+    --ov_mesh overlap_latlon_cubedsphere.g \
+    --in_np 1 \
+    --in_type FV \
+    --out_type FV \
+    --out_map map_LL_CS.nc \
+    --out_format Netcdf4
+GenerateOverlapMesh \
+    --a out_cubedsphere.g \
+    --b out_latlon.g \
+    --out overlap_cubedsphere_latlon.g \
+    --out_format Netcdf4
+GenerateOfflineMap \
+    --in_mesh out_cubedsphere.g \
+    --out_mesh out_latlon.g \
+    --ov_mesh overlap_cubedsphere_latlon.g \
+    --in_np 1 \
+    --in_type FV \
+    --out_type FV \
+    --out_map map_CS_LL.nc \
+    --out_format Netcdf4
 ```
diff --git a/examples/weather/fcn_afno/README.md b/examples/weather/fcn_afno/README.md
@@ -35,8 +35,8 @@ different lead times.](../../../docs/img/FourCastNet.gif)
 
 ## Dataset
 
-The model is trained on a 20-channel subset of the ERA5 reanalysis data on single levels and
-pressure levels that is pre-processed and stored into HDF5 files.
+The model is trained on a 20-channel subset of the ERA5 reanalysis data on single levels
+and pressure levels that is pre-processed and stored into HDF5 files.
 The subset of the ERA5 training data that FCN was trained on is hosted at the
 National Energy Research Scientific Computing Center (NERSC). For convenience
 [it is available to all via Globus](https://app.globus.org/file-manager?origin_id=945b3c9e-0f8c-11ed-8daf-9f359c660fbd&origin_path=%2F~%2Fdata%2F).
@@ -83,10 +83,10 @@ If you find this work useful, cite it using:
 
 ```text
 @article{pathak2022fourcastnet,
-  title={Fourcastnet: A global data-driven high-resolution weather model 
+  title={Fourcastnet: A global data-driven high-resolution weather model
          using adaptive fourier neural operators},
-  author={Pathak, Jaideep and Subramanian, Shashank and Harrington, Peter 
-          and Raja, Sanjeev and Chattopadhyay, Ashesh and Mardani, Morteza 
+  author={Pathak, Jaideep and Subramanian, Shashank and Harrington, Peter
+          and Raja, Sanjeev and Chattopadhyay, Ashesh and Mardani, Morteza
           and Kurth, Thorsten and Hall, David and Li, Zongyi and Azizzadenesheli, Kamyar
           and Hassanzadeh, Pedram and Kashinath, Karthik and Anandkumar, Animashree},
   journal={arXiv preprint arXiv:2202.11214},
@@ -99,7 +99,7 @@ Climate Data Store.
 
 ```text
 Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., Muñoz Sabater, J.,
-Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C., 
+Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C.,
 Dee, D., Thépaut, J-N. (2018): ERA5 hourly data on pressure levels from 1959 to present.
 Copernicus Climate Change Service (C3S) Climate Data Store (CDS). 10.24381/cds.bd0915c6
 

diff --git a/examples/weather/fcn_sfno/README.md b/examples/weather/fcn_sfno/README.md
@@ -29,8 +29,8 @@ our response to climate change.
 
 ## Dataset
 
-The model is trained on a 73-channel subset of the ERA5 reanalysis data on single levels and
-pressure levels that is pre-processed and stored into HDF5 files.
+The model is trained on a 73-channel subset of the ERA5 reanalysis data on single levels
+and pressure levels that is pre-processed and stored into HDF5 files.
 A 20-channel subset of the ERA5 training data is hosted at the
 National Energy Research Scientific Computing Center (NERSC). For convenience
 [it is available to all via Globus](https://app.globus.org/file-manager?origin_id=945b3c9e-0f8c-11ed-8daf-9f359c660fbd&origin_path=%2F~%2Fdata%2F).
@@ -120,7 +120,7 @@ Climate Data Store.
 
 ```text
 Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., Muñoz Sabater, J.,
-Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C., 
+Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C.,
 Dee, D., Thépaut, J-N. (2018): ERA5 hourly data on pressure levels from 1959 to present.
 Copernicus Climate Change Service (C3S) Climate Data Store (CDS). 10.24381/cds.bd0915c6