Merge remote-tracking branch 'origin/main'

Author: alperaltuntas

README.md

@@ -1,5 +1,20 @@
 # visualCaseGen
 
-visualCaseGen is a prototype GUI that runs on JupyterLab. This tools visually guides the users through the process of creating CESM cases, e.g., choosing appropriate compsets and grids. Check out the following Quickstart guide for more information on how to work with visualCaseGen:
+Welcome to **visualCaseGen**, an intuitive graphical user interface (GUI) designed to simplify the workflow of creating Community Earth System Model v.3 (CESM3) cases. With visualCaseGen, users can effortlessly explore and define component sets (compsets), select or customize grid resolutions, and prepare their CESM cases, all through an interactive and user-friendly platform that runs on Jupyter notebooks.
 
-https://github.com/ESMCI/visualCaseGen/wiki/Quickstart
+## Key Features
+
+- **Guided Configuration**: visualCaseGen guides users through the main steps of configuring CESM cases, ensuring that all necessary components are included while preventing incompatible selections.
+  
+- **Standard and Custom Options**: Users can choose from predefined standard compsets and grids or create custom configurations tailored to specific modeling needs.
+
+- **Real-Time Compatibility Checks**: As you make selections, visualCaseGen highlights incompatible options, helping you navigate the complexities of model configurations effectively.
+
+- **Easy Navigation**: The tool breaks down the configuration process into three clear stages:
+  1. **Compset Selection**: Choose from standard or custom compsets, including all associated models and physics options.
+  2. **Grid Configuration**: Select or create grids tailored for your application, ensuring compatibility across individual component grids and compsets.
+  3. **Case Launch**: Finalize your configuration and create your CESM case with a few clicks.
+
+## User Manual
+
+For detailed instructions on how to use visualCaseGen, including setup and configuration guidance, please refer to the [User Manual](https://esmci.github.io/visualCaseGen/).

docs/assets/Stage1_10.png

@@ -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.

docs/assets/Stage1_4.png

@@ -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.
+

docs/assets/Stage1_6.png

@@ -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.

docs/assets/Stage1_7.png

@@ -0,0 +1,4 @@
+Fill Indian Ocean
+=================
+
+Instructions coming soon...

docs/assets/Stage1_8.png

@@ -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.