major additions to the sphinx documentation

docs/basics.rst

@@ -0,0 +1,45 @@
+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.
+

docs/compset.rst

@@ -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 primary stage, `Grid`, where
+you'll select a model resolution compatible with your chosen compset.
+

docs/creating_case.rst

@@ -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/grid.rst

@@ -0,0 +1,15 @@
+Stage 2/3: Grid
+===============
+
+In this stage, ...
+
+Standard Grids
+------------------
+
+lorem ipsum
+
+Custom Grids
+------------------
+
+lorem ipsum
+

docs/index.rst

@@ -3,15 +3,56 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to visualCaseGen's documentation!
+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: 2
+   :maxdepth: 3
    :caption: Contents:
 
    installation
-
+   open
+   basics
+   creating_case
+   compset
+   grid
+   launch
+   troubleshooting
 
 
 Indices and tables

docs/installation.rst

@@ -1,42 +1,74 @@
 Installation
 ======================================
 
+visualCaseGen is presently bundled with a CESM distribution (fork) based on cesm3_0_beta03. The following
+instructions guide you through obtaining and installing this specific CESM distribution with visualCaseGen.
+
 Prerequisite
 -------------
 
-* conda: Make sure that you have conda installed (either via Miniconda or Anaconda). See the following link for installing miniconda on your local machine:
+.. warning::
+  The key prerequisite for installing visualCaseGen is that CESM cesm3_0_beta03 or a newer version is already
+  ported on your machine. If this version (or later) is not yet ported, follow the CESM documentation
+  instructions to port it first. Without this, visualCaseGen will not launch.
 
-https://docs.conda.io/en/latest/miniconda.html
+- Verify CESM port: Ensure CESM cesm3_0_beta03 or newer is ported on your machine. If not, follow the CESM
+  documentation to port the required version.
+- Conda Installation: Confirm that Conda is installed, either via Miniconda or Anaconda. You can install Miniconda
+  from the following link:
+  https://docs.conda.io/en/latest/miniconda.html
 
-Instructions
--------------
+Download CESM with visualCaseGen
+--------------------------------
 
-First, clone the `mom6_bathy` GitHub repository as follows:
+To download the specific CESM distribution bundled with visualCaseGen, clone the CESM GitHub repository and
+use the `git-fleximod` script that comes with CESM as a package manager, as follows. Note that downloading
+CESM may take some time.
 
 .. code-block:: bash
 
-    git clone --recursive https://github.com/NCAR/mom6_bathy.git
+    git clone https://github.com/alperaltuntas/cesm.git -b cesm3_0_beta03_gui cesm3_0_beta03_gui
+    cd cesm3_0_beta03_gui
+    ./bin/git-fleximod update
+
+This will download the required CESM version, including visualCaseGen.
+
+Create the visualCaseGen conda environment
+------------------------------------------
 
-Then, `cd` into your newly checked out `mom6_bathy` clone and run the
-following command to install `mom6_bathy` and all dependencies.
+.. warning::
+  If you are using a machine other than one of the supported systems (e.g., derecho, casper), you may need
+  to modify the ccs_config/machines XML files in the newly downloaded CESM distribution. This may be required
+  even if CESM cesm3_0_beta03 or a newer version is already ported on your machine. These modifications
+  should match the adjustments made previously for the ported CESM version. For guidance on updating the
+  ccs_config/machines XML files, refer to the CESM documentation, consult CESM support through the CESM forum,
+  or submit an issue on the visualCaseGen GitHub repository. Users on supported machines can ignore this warning,
+  as no changes are needed.
+
+To create the `visualCaseGen` conda environment, navigate to the `visualCaseGen` directory and run the following
+commands:
 
 .. code-block:: bash
 
-    cd mom6_bathy
+    cd visualCaseGen
     conda env create -f environment.yml
 
-The above command creates a new conda environment called `mom6_bathy_env`. You can
-activate this environment by running:
+This will create the `visualCaseGen` conda environment. Activate the `visualCaseGen` conda environment by running
+the following command:
 
 .. code-block:: bash
 
-    conda activate mom6_bathy_env
+    conda activate visualCaseGen
+
+Verify Installation
+------------------------------------------
 
-To confirm that the installation was successful, execute the following command:
+To verify that visualCaseGen was installed correctly, run the test suite:
 
 .. code-block:: bash
 
-    python -c "import mom6_bathy"
+    pytest tests/
+
+If the test suite completes successfully, visualCaseGen is ready for use. If any tests fail, please open an
+issue on the visualCaseGen GitHub repository, including error messages and the installation steps you followed.
 
-If no error message is displayed, then the installation is successful. Note that
-you will need to activate the `mom6_bathy_env` environment before every use.

docs/launch.rst

@@ -0,0 +1,5 @@
+Stage 3/3: Launch
+=================
+
+lorem ipsum
+