deploy: 374fa53

ESMCI · Nov 12, 2024 · 3f1278b · 3f1278b
commit 3f1278b
Show file tree

Hide file tree

Showing 127 changed files with 8,182 additions and 0 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: f04cbfbf88c1ac50790a022afc295dd6
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.doctrees/basics.doctree b/.doctrees/basics.doctree
diff --git a/.doctrees/compset.doctree b/.doctrees/compset.doctree
diff --git a/.doctrees/creating_case.doctree b/.doctrees/creating_case.doctree
diff --git a/.doctrees/environment.pickle b/.doctrees/environment.pickle
diff --git a/.doctrees/fillindian.doctree b/.doctrees/fillindian.doctree
diff --git a/.doctrees/grid.doctree b/.doctrees/grid.doctree
diff --git a/.doctrees/index.doctree b/.doctrees/index.doctree
diff --git a/.doctrees/installation.doctree b/.doctrees/installation.doctree
diff --git a/.doctrees/launch.doctree b/.doctrees/launch.doctree
diff --git a/.doctrees/open.doctree b/.doctrees/open.doctree
diff --git a/.doctrees/ridge.doctree b/.doctrees/ridge.doctree
diff --git a/.doctrees/troubleshooting.doctree b/.doctrees/troubleshooting.doctree
diff --git a/.nojekyll b/.nojekyll
diff --git a/_images/Stage1_10.png b/_images/Stage1_10.png
diff --git a/_images/Stage1_4.png b/_images/Stage1_4.png
diff --git a/_images/Stage1_6.png b/_images/Stage1_6.png
diff --git a/_images/Stage1_7.png b/_images/Stage1_7.png
diff --git a/_images/Stage1_8.png b/_images/Stage1_8.png
diff --git a/_images/Stage1_9.png b/_images/Stage1_9.png
diff --git a/_images/Stage2_1.png b/_images/Stage2_1.png
diff --git a/_images/Stage2_2.png b/_images/Stage2_2.png
diff --git a/_images/Stage2_3.png b/_images/Stage2_3.png
diff --git a/_images/Stage2_4.png b/_images/Stage2_4.png
diff --git a/_images/Stage2_5.png b/_images/Stage2_5.png
diff --git a/_images/Stage2_6.png b/_images/Stage2_6.png
diff --git a/_images/Stage2_7.png b/_images/Stage2_7.png
diff --git a/_images/Stage3_1.png b/_images/Stage3_1.png
diff --git a/_images/Stage3_2.png b/_images/Stage3_2.png
diff --git a/_images/Stage3_3.png b/_images/Stage3_3.png
diff --git a/_images/demo3.gif b/_images/demo3.gif
diff --git a/_images/launch1.png b/_images/launch1.png
diff --git a/_images/launch2.png b/_images/launch2.png
diff --git a/_images/launch3.png b/_images/launch3.png
diff --git a/_images/launch4.png b/_images/launch4.png
diff --git a/_images/launch5.png b/_images/launch5.png
diff --git a/_images/ridge1.png b/_images/ridge1.png
diff --git a/_images/ridge2.png b/_images/ridge2.png
diff --git a/_images/ridge3.png b/_images/ridge3.png
diff --git a/_images/stage1_1.png b/_images/stage1_1.png
diff --git a/_images/stage1_2.png b/_images/stage1_2.png
diff --git a/_images/stage1_3.png b/_images/stage1_3.png
diff --git a/_images/stage1_5.png b/_images/stage1_5.png
diff --git a/_sources/basics.rst.txt b/_sources/basics.rst.txt
@@ -0,0 +1,54 @@
+visualCaseGen Basics
+====================
+
+This section defines key concepts in visualCaseGen that will be referenced throughout the documentation.
+
+
+Configuration Variable
+-----------------------
+
+Configuration variables are essential CESM settings that must be defined before creating a case.
+These include choices like the model, model physics, resolution, and grid options that are set in
+CESM XML and user namelist files. visualCaseGen provides an intuitive, form-based interface for
+configuring these variables, ensuring compatibility and completeness. Only the variables required
+for case instantiation are included in visualCaseGen; other settings that can be adjusted after
+case creation, such as simulation duration, are not included in the GUI.
+
+Stage
+-----
+
+In visualCaseGen, a stage represents a group of related CESM configuration variables that can be
+set together. Examples of stages include models, physics options, and resolutions. Stages introduce
+a logical hierarchy, where those listed earlier hold higher precedence. For instance, model selection
+is a prerequisite for defining model physics, so the model stage takes precedence. visualCaseGen
+guides users through each stage in the proper order, ensuring that configurations are compatible
+at each step.
+
+A stage is deemed complete when all of its configuration variables have been set. When a stage is
+complete, visualCaseGen will automatically advance to the next stage. Users can also navigate
+between stages by clicking the `Revert` button on the top bar of each Stage to return to the previous
+stage or the `Proceed` button to advance to the next stage, but if there are any incomplete configuration
+variables, visualCaseGen will prompt users to fill them in before proceeding. The `Defaults` button on 
+the top bar of each stage allows users to quickly set all configuration variables to their default
+values, if available. The `Info` button provides additional information about the stage and its 
+configuration variables.
+
+Standard vs Custom
+------------------
+
+During configuration, users can choose between standard and custom options for certain settings,
+like compsets, resolutions, and model grids. Standard options are predefined CESM configurations
+that are generally easier and safer to use, while custom options allow for greater flexibility.
+visualCaseGen assists users through the custom configuration process to maximize compatibility,
+but custom setups may require additional troubleshooting. For any issues with custom configurations,
+please refer to the Troubleshooting section of this guide.
+
+
+Resolution vs Grid vs Model Grid
+--------------------------------
+
+In CESM terminology, *resolution* and *grid* are often used interchangeably,
+both referring to the combination of model grids used in a CESM simulation. Unless 
+specifically noted as a *model grid* (i.e., a grid unique to a particular component,
+such as the ocean grid), the term *grid* in the context of visualCaseGen should be understood as
+*resolution*, meaning the full collection of *model grids* used in a particular CESM case.
diff --git a/_sources/compset.rst.txt b/_sources/compset.rst.txt
@@ -0,0 +1,121 @@
+Stage 1/3: Compset
+==================
+
+In this stage, the component set (compset), i.e., the collection of models (`cam`, `clm`, `mom`, etc), physics 
+(`CAM70`, `CLM50`, `MOM6`, etc), and component options. e.g., `LT` (low top), `SP` (satellite phenology), `MARBL-BIO`,
+etc. are determined.
+You'll start by choosing between the `Standard` compset mode, which provides predefined and stable CESM configurations,
+and the `Custom` compset mode, which allows for more tailored combinations for unique experiments. 
+
+.. image:: assets/stage1_1.png
+
+Standard Compsets
+------------------
+
+- **Support Level:** You can select from a list of all standard compsets or only those that are scientifically
+  supported. `Supported` compsets have been validated by CESM developers, ensuring they produce 
+  scientifically vetted results. These are typically recommended for production runs. The `All` option,
+  however, includes experimental compsets that may not be validated but can be useful for testing and
+  development. Selecting a supported compset ensures that you are working with configurations approved
+  for stability and accuracy, while the `All` option offers broader but potentially unstable options for
+  specialized needs.
+
+  .. image:: assets/stage1_2.png
+
+- **Models to Include:** If you choose the `Supported` option, a list of scientifically validated
+  compsets will appear for you to choose from. However, if you choose the `All` option, you'll be
+  presented with a *model matrix* to refine the list of compsets displayed. This matrix allows you
+  to specify which model components you want to include. For instance, if you select `cam` as the
+  atmosphere model and `mom` as the ocean model, the list will filter down to include only those
+  compsets that incorporate both. If you're flexible with certain components, you can select `any`
+  for those classes, or click the `Defaults` button in the Stage top bar to apply typical defaults
+  for all components, streamlining your selection. This feature is particularly useful if you're
+  unsure about specific settings or wish to adhere to commonly used configurations.
+
+  .. image:: assets/stage1_3.png
+
+- **Standard Compsets List:** After refining your options, visualCaseGen will display a list of
+  matching compsets. Each compset is labeled with an alias and incorporates an initialization time
+  and a short description of the included models, providing a snapshot of each configuration.
+  To narrow down the list further, you can use the search box above the list. Typing keywords
+  in the search box will display all compsets containing one or more of the search terms. For
+  precise filtering, use double quotes around terms for exact matches. This flexibility makes
+  it easy to locate specific compsets or explore different configurations to find the most
+  suitable one for your simulation needs.
+
+  .. image:: assets/Stage1_4.png
+
+After selecting a compset, visualCaseGen will guide you to the next primary stage, `Grid`, where
+you'll select a model resolution compatible with your chosen compset.
+
+Custom Compsets
+------------------
+
+.. note::
+  If you initially selected the `Standard` compset mode, the `Custom` compset stages will not
+  display, and instead visualCaseGen will proceed directly to the `Grid` stage. To switch to the `Custom`
+  compset mode after already completing the `Standard` compset stages, you can click `Revert`
+  buttons to navigate back to the selection of configuration mode.
+
+If you prefer to build a custom compset, visualCaseGen provides a step-by-step process,
+starting with the initialization time for your experiment. This choice impacts the initial
+conditions and forcings for your simulation. You can choose from:
+
+- 1850: Represents pre-industrial conditions and is suitable for fixed-time-period runs, such as for model spin-ups.
+- 2000: Represents modern-day conditions, also appropriate for fixed-period simulations.
+- HIST: Represents a historical run setup, which covers transient simulations (e.g., from 1850 through 2015) that evolve with changing conditions over time.
+
+  .. image:: assets/stage1_5.png
+
+Once you've selected the initialization time, visualCaseGen will prompt you to select the
+models for each component class. You'll see options that include active models, data models
+(prefixed with d, like `datm`), and stub models (prefixed with s, like `sice`). Data models
+perform the basic function of reading preexisting forcing data, modifying that data, and then
+sending it to active models via the coupler. Stub models act as placeholders required by the CESM
+coupler infrastructure but have no impact on the simulation. This variety allows you to 
+configure a custom compset that includes as many or as few active components as desired,
+depending on the specific goals of your simulation.
+
+  .. image:: assets/Stage1_6.png
+
+As you make selections in this stage and elsewhere, visualCaseGen will guide you by crossing
+out incompatible options, helping to prevent invalid configurations. For example, if you select
+`cam` for the atmosphere and `mom` for the ocean, the GUI will disable several other model
+options that are incompatible with this combination. This real-time feedback keeps your
+configuration process streamlined and ensures that all selected options work together compatibly.
+
+   .. image:: assets/Stage1_7.png
+
+At any stage, you can click on any crossed-out option to view a brief explanation of
+why it's incompatible with your current selections for additional guidance.
+
+   .. image:: assets/Stage1_8.png
+
+After choosing your models, you'll proceed to select the physics options for each. The physics
+settings determine the complexity of each model component and impact computational requirements.
+Higher version numbers indicate newer and more complex physics for a given model. Depending on
+the model, you may have multiple physics options available. For example, `cam` and 
+`clm` have multiple physics options, while other models may offer only one, in which case it
+will be selected by default. Since each physics option provides different levels of model complexity,
+the selection should be based on the specific requirements of your simulation. Refer to 
+the individual model documentations for more information on the available physics options.
+
+   .. image:: assets/Stage1_9.png
+
+The final part of custom compset creation is selecting optional physics modifiers.
+Modifiers allow additional adjustments to physics and parameter settings, offering
+further customization to meet modeling requirements and goals. Each component class
+is represented in individual tabs within this stage. You can switch between tabs to
+select modifiers or opt out of a modifier by choosing `(none)`. Tabs with available
+modifiers will display a red question mark until a selection is made. While you can
+select multiple modifiers for a single component class, be cautious: visualCaseGen
+does not verify compatibility between multiple modifiers within a single component,
+so it's advisable to consult CESM documentation or model experts if you're using complex
+modifier combinations.
+
+   .. image:: assets/Stage1_10.png
+
+Once you've completed the selection of models, physics, and optional modifiers,
+visualCaseGen will automatically advance to the next main stage, `Grid`, where
+you'll select a model resolution compatible with your chosen compset.
+
diff --git a/_sources/creating_case.rst.txt b/_sources/creating_case.rst.txt
@@ -0,0 +1,10 @@
+Stages of Creating a Case 
+==========================
+
+The workflow for creating a CESM case using visualCaseGen is divided into three main stages:
+
+1. **Compset**: In this stage, the user will select the compset, i.e., the set of models, physics, and options that will be used in the simulation.
+2. **Resolution**: In this stage, the user will select the resolution of the simulation, i.e., the collection of model grids.
+3. **Launch**: In this final stage, the user will create and configure the case.
+
+Proceed to the following sections to learn more about each stage.
diff --git a/_sources/fillindian.rst.txt b/_sources/fillindian.rst.txt
@@ -0,0 +1,4 @@
+Fill Indian Ocean
+=================
+
+Instructions coming soon...
diff --git a/_sources/grid.rst.txt b/_sources/grid.rst.txt
@@ -0,0 +1,95 @@
+Stage 2/3: Grid
+===============
+
+The second major step in configuring your CESM case is choosing a resolution, which
+is a specific set of grids for each active and data model in the compset. You may 
+select either a standard, out-of-the-box resolution or create a custom one by combining
+existing model grids. In `Custom` mode, you can also generate custom model grids for CLM and/or MOM6
+using auxiliary tools included in visualCaseGen. Begin by selecting between `Standard`
+and `Custom` grid modes.
+
+.. image:: assets/Stage2_1.png
+
+.. note:: In CESM terminology, *resolution* and *grid* are often used interchangeably,
+   both referring to the combination of model grids used in a CESM simulation. Unless 
+   specifically noted as a *model grid* (i.e., a grid unique to a particular component,
+   such as the ocean grid), the term *grid* in this context should be understood as
+   *resolution*, meaning the full collection of *model grids* used in a particular CESM case.
+
+Standard Grids
+------------------
+
+Select from the available list of resolutions (combinations of model grids) below.
+Resolutions known to be incompatible with your chosen compset have been omitted 
+from this list. Use the search box to refine the list further. For exact matches,
+use double quotes; otherwise, the search will display all grids containing one 
+or more of the search terms.
+
+.. image:: assets/Stage2_2.png
+
+After selecting a grid, visualCaseGen will advance to the `Launch` stage, where
+you can create your CESM case using the chosen compset and grid configuration.
+
+Custom Grids
+------------------
+
+In Custom Grid mode, you can build a custom grid by mixing and matching standard 
+model grids or generating new MOM6 and/or CLM grids with specialized tools that come with visualCaseGen.
+Start by specifying a path to save the new grid files and a name to refer to this
+new grid in the configuration process and beyond.
+
+.. image:: assets/Stage2_3.png
+
+After clicking `Select`, a file browser will open to help you locate your preferred
+directory for saving the new grid files. Once the directory is selected, enter the
+new grid name in the text box at the top right and click `Select` to proceed.
+
+.. image:: assets/Stage2_4.png
+
+Atmosphere Grid
+~~~~~~~~~~~~~~~
+
+Next, choose an atmosphere grid from the list of compatible options based on the
+compset you selected in the `Compset` stage. Use the search box to filter options if needed.
+This chosen atmosphere grid will be integrated with other model grids to form your custom CESM grid (resolution).
+
+.. image:: assets/Stage2_5.png
+
+Ocean Grid
+~~~~~~~~~~
+
+For the ocean grid, if MOM6 is selected as the ocean model, you can either select a standard
+ocean grid or create a new MOM6 grid. When creating a new MOM6 grid, you'll specify parameters
+such as grid extent and resolution, after which you'll be directed to a separate notebook that
+uses the `mom6_bathy` tool to generate the new grid and bathymetry.
+
+If using a standard ocean grid, select one from the list compatible with your chosen compset
+and atmosphere grid. If creating a new MOM6 grid, complete the required parameters, then proceed
+to launch the `mom6_bathy` tool for final customization.
+
+.. image:: assets/Stage2_6.png
+
+After specifying all ocean grid parameters, click `Launch mom6_bathy`. This will open an 
+auto-generated Jupyter notebook where you can fine-tune the ocean grid bathymetry and generate
+all necessary input files. For more details on mom6_bathy, refer to its documentation: https://ncar.github.io/mom6_bathy/
+
+.. note:: If the `mom6_bathy` notebook doesn't open automatically, make sure that your browser allows
+  pop-ups from visualCaseGen. If the notebook still doesn't open, you can manually launch it by
+  navigating to the `mom6_bathy_notebooks/` directory in your visualCaseGen installation and opening
+  the notebook corresponding to your custom grid.
+
+
+Land Grid
+~~~~~~~~~
+
+Following ocean grid selection or creation, you'll move to land grid selection. If CLM is chosen
+as the land model, you can also modify an existing CLM grid. If so, select a base land grid for
+customization.
+
+.. image:: assets/Stage2_7.png
+
+.. note:: Detailed instructions on customizing an existing CLM grid will be added here shortly.
+
+Once atmosphere, ocean, and land grids have been chosen or created, custom grid setup is complete.
+visualCaseGen will guide you to the final stage, `Launch`, where you can create a CESM case based on
+the specified compset and grid.
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,62 @@
+.. visualCaseGen documentation master file, created by
+   sphinx-quickstart on Sun Oct 27 13:59:27 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to visualCaseGen!
+=========================================
+
+visualCaseGen is a Jupyter-based graphical user interface (GUI) designed to streamline
+the creation and configuration of Community Earth System Model v.3 (CESM3) cases.
+The visualCaseGen GUI allows users to:
+
+- **Browse Standard CESM Configurations:** Easily explore and select from available CESM compsets
+  and resolutions.
+- **Create Custom Configurations**: Rapidly customize CESM experiments with advanced options for component
+  selection, grid generation, and configuration.
+
+Key Features
+------------
+
+- **Easy Case Setup:** Intuitive interface for configuring experiments.
+- **Hierarchical Modeling:** Combine different complexity levels across components.
+- **Flexible Configurations:** Mix and match models and grids with compatibility guidance.
+- **Automated Case Creation:** Generates input files and handles XML/namelist adjustments.
+- **Modify CLM Inputs:** Easily adjust land masks and surface datasets with a form-based interface.
+- **MOM6 Grid & Bathymetry Customization:** Create or modify grids and bathymetries with a point-and-click tool.
+
+.. image:: assets/demo3.gif
+
+Typical Workflow
+----------------
+
+- **Launch:** Open the visualCaseGen GUI within your Jupyter notebook environment.
+- **Select Compset:** Choose from available standard CESM compsets or create a custom one by selecting
+  models, physics options, and other settings for each component (e.g., atmosphere, ocean, land, ice).
+- **Define Resolution:** Select a compatible standard resolution or create a custom one by combining
+  different grids for each model component or generating new ones.
+- **Generate Case:** Once your compset and resolution are set, visualCaseGen will create the CESM case,
+  automatically generating required input files and making all necessary modifications to CESM XML and
+  user namelist files.
+
+For more information on each step, please refer to the corresponding sections in this user guide.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: User Manual:
+
+   installation
+   open
+   basics
+   creating_case
+   compset
+   grid
+   launch
+   troubleshooting
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Examples:
+
+   ridge
+   fillindian