diff --git a/README.md b/README.md index 03855a4..ecd847e 100644 --- a/README.md +++ b/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/). diff --git a/docs/assets/Stage1_10.png b/docs/assets/Stage1_10.png new file mode 100644 index 0000000..e0ff736 Binary files /dev/null and b/docs/assets/Stage1_10.png differ diff --git a/docs/assets/Stage1_4.png b/docs/assets/Stage1_4.png new file mode 100644 index 0000000..34f1f67 Binary files /dev/null and b/docs/assets/Stage1_4.png differ diff --git a/docs/assets/Stage1_6.png b/docs/assets/Stage1_6.png new file mode 100644 index 0000000..0baf0d7 Binary files /dev/null and b/docs/assets/Stage1_6.png differ diff --git a/docs/assets/Stage1_7.png b/docs/assets/Stage1_7.png new file mode 100644 index 0000000..5b69210 Binary files /dev/null and b/docs/assets/Stage1_7.png differ diff --git a/docs/assets/Stage1_8.png b/docs/assets/Stage1_8.png new file mode 100644 index 0000000..0bc7733 Binary files /dev/null and b/docs/assets/Stage1_8.png differ diff --git a/docs/assets/Stage1_9.png b/docs/assets/Stage1_9.png new file mode 100644 index 0000000..19ebf3a Binary files /dev/null and b/docs/assets/Stage1_9.png differ diff --git a/docs/assets/Stage2_1.png b/docs/assets/Stage2_1.png new file mode 100644 index 0000000..c4e36c0 Binary files /dev/null and b/docs/assets/Stage2_1.png differ diff --git a/docs/assets/Stage2_2.png b/docs/assets/Stage2_2.png new file mode 100644 index 0000000..e16b544 Binary files /dev/null and b/docs/assets/Stage2_2.png differ diff --git a/docs/assets/Stage2_3.png b/docs/assets/Stage2_3.png new file mode 100644 index 0000000..c864254 Binary files /dev/null and b/docs/assets/Stage2_3.png differ diff --git a/docs/assets/Stage2_4.png b/docs/assets/Stage2_4.png new file mode 100644 index 0000000..125b00a Binary files /dev/null and b/docs/assets/Stage2_4.png differ diff --git a/docs/assets/Stage2_5.png b/docs/assets/Stage2_5.png new file mode 100644 index 0000000..c30690e Binary files /dev/null and b/docs/assets/Stage2_5.png differ diff --git a/docs/assets/Stage2_6.png b/docs/assets/Stage2_6.png new file mode 100644 index 0000000..5f9fc4b Binary files /dev/null and b/docs/assets/Stage2_6.png differ diff --git a/docs/assets/Stage2_7.png b/docs/assets/Stage2_7.png new file mode 100644 index 0000000..5e4ebb5 Binary files /dev/null and b/docs/assets/Stage2_7.png differ diff --git a/docs/assets/Stage3_1.png b/docs/assets/Stage3_1.png new file mode 100644 index 0000000..a5d74b0 Binary files /dev/null and b/docs/assets/Stage3_1.png differ diff --git a/docs/assets/Stage3_2.png b/docs/assets/Stage3_2.png new file mode 100644 index 0000000..caea380 Binary files /dev/null and b/docs/assets/Stage3_2.png differ diff --git a/docs/assets/Stage3_3.png b/docs/assets/Stage3_3.png new file mode 100644 index 0000000..a8e528c Binary files /dev/null and b/docs/assets/Stage3_3.png differ diff --git a/docs/assets/demo3.gif b/docs/assets/demo3.gif new file mode 100644 index 0000000..b29676c Binary files /dev/null and b/docs/assets/demo3.gif differ diff --git a/docs/assets/launch1.png b/docs/assets/launch1.png new file mode 100644 index 0000000..b1057ec Binary files /dev/null and b/docs/assets/launch1.png differ diff --git a/docs/assets/launch2.png b/docs/assets/launch2.png new file mode 100644 index 0000000..28dd57b Binary files /dev/null and b/docs/assets/launch2.png differ diff --git a/docs/assets/launch3.png b/docs/assets/launch3.png new file mode 100644 index 0000000..3e35c13 Binary files /dev/null and b/docs/assets/launch3.png differ diff --git a/docs/assets/launch4.png b/docs/assets/launch4.png new file mode 100644 index 0000000..756581b Binary files /dev/null and b/docs/assets/launch4.png differ diff --git a/docs/assets/launch5.png b/docs/assets/launch5.png new file mode 100644 index 0000000..4a1868b Binary files /dev/null and b/docs/assets/launch5.png differ diff --git a/docs/assets/ridge1.png b/docs/assets/ridge1.png new file mode 100644 index 0000000..903a2b7 Binary files /dev/null and b/docs/assets/ridge1.png differ diff --git a/docs/assets/ridge2.png b/docs/assets/ridge2.png new file mode 100644 index 0000000..561adb3 Binary files /dev/null and b/docs/assets/ridge2.png differ diff --git a/docs/assets/ridge3.png b/docs/assets/ridge3.png new file mode 100644 index 0000000..d9c7169 Binary files /dev/null and b/docs/assets/ridge3.png differ diff --git a/docs/assets/stage1_1.png b/docs/assets/stage1_1.png new file mode 100644 index 0000000..3456124 Binary files /dev/null and b/docs/assets/stage1_1.png differ diff --git a/docs/assets/stage1_2.png b/docs/assets/stage1_2.png new file mode 100644 index 0000000..476a8ef Binary files /dev/null and b/docs/assets/stage1_2.png differ diff --git a/docs/assets/stage1_3.png b/docs/assets/stage1_3.png new file mode 100644 index 0000000..59e259c Binary files /dev/null and b/docs/assets/stage1_3.png differ diff --git a/docs/assets/stage1_5.png b/docs/assets/stage1_5.png new file mode 100644 index 0000000..fd5e68f Binary files /dev/null and b/docs/assets/stage1_5.png differ diff --git a/docs/basics.rst b/docs/basics.rst new file mode 100644 index 0000000..6051d31 --- /dev/null +++ b/docs/basics.rst @@ -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. \ No newline at end of file diff --git a/docs/compset.rst b/docs/compset.rst new file mode 100644 index 0000000..972ba34 --- /dev/null +++ b/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 main stage, `Grid`, where +you'll select a model resolution compatible with your chosen compset. + diff --git a/docs/creating_case.rst b/docs/creating_case.rst new file mode 100644 index 0000000..e1ec180 --- /dev/null +++ b/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. diff --git a/docs/fillindian.rst b/docs/fillindian.rst new file mode 100644 index 0000000..4f056be --- /dev/null +++ b/docs/fillindian.rst @@ -0,0 +1,4 @@ +Fill Indian Ocean +================= + +Instructions coming soon... \ No newline at end of file diff --git a/docs/grid.rst b/docs/grid.rst new file mode 100644 index 0000000..f18cef4 --- /dev/null +++ b/docs/grid.rst @@ -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. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 247e65c..e714c6c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,20 +3,60 @@ 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! ========================================= -.. toctree:: - :maxdepth: 2 - :caption: Contents: +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: - installation +- **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. -Indices and tables -================== +.. toctree:: + :maxdepth: 3 + :caption: User Manual: + + installation + open + basics + creating_case + compset + grid + launch + troubleshooting + +.. toctree:: + :maxdepth: 3 + :caption: Examples: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + ridge + fillindian \ No newline at end of file diff --git a/docs/installation.rst b/docs/installation.rst index fb32a10..58c0b44 100644 --- a/docs/installation.rst +++ b/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. diff --git a/docs/launch.rst b/docs/launch.rst new file mode 100644 index 0000000..15422b8 --- /dev/null +++ b/docs/launch.rst @@ -0,0 +1,56 @@ +Stage 3/3: Launch +================= + +The final main stage of visualCaseGen is the `Launch` stage, where you bring your CESM case to +life with the selected compset and grid configuration. In this stage, you'll find tools to +select the case directory, choose a target machine, and initiate case creation. + +.. image:: assets/Stage3_1.png + +Chosing the case directory +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To begin, open the file browser widget by clicking the `Select` button to set the directory for +the new case. Navigate to your desired location, then enter a unique name for the case in the +text box at the top right of the browser. Click `Select` to confirm your directory and case name. + +.. image:: assets/Stage3_2.png + +Selecting the target machine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Next, choose the machine where the case will run. If CESM has already been ported to the machine, +this selection should populate automatically. If not, confirm that CESM is properly ported to the +machine you intend to use and that the correct machine is selected. For some systems, a PROJECT ID +is required; if so, you'll be prompted to enter it here. + +.. note:: + If you're using a machine that shares a file system with another, you have the flexibility + to select a different machine for running the case. For example, if you are working within + visualCaseGen on *casper* but intend to run the case on *derecho*, simply change the machine selection + to *derecho* at this stage. This allows you to configure the case on one machine while specifying + execution on another within the shared system environment. + +Creating the case +~~~~~~~~~~~~~~~~~ + +When all selections are finalized, you can click `Create Case` to initiate case creation or +`Show Commands` to view the terminal commands that will be executed. Below, you'll see an +example of the interface after clicking `Create Case`. Notice how visualCaseGen handles the +case setup process, including modifying CESM XML files, executing the create_newcase tool, +running the `case.setup` script, and applying any XML and namelist changes needed. + +.. image:: assets/Stage3_3.png + +The completion log provides confirmation of a successful case creation, including the path to +the new case directory, where you can proceed with case customization, building, and execution. + +Congratulations! +~~~~~~~~~~~~~~~~ + +You've successfully created a CESM case using visualCaseGen, bringing together the models, +grid, and configurations tailored to your scientific goals. With the case directory set up, +you're ready to move forward with any additional customizations, building, and executing your +case. Great job, and happy modeling! + + diff --git a/docs/open.rst b/docs/open.rst new file mode 100644 index 0000000..6b71b9e --- /dev/null +++ b/docs/open.rst @@ -0,0 +1,139 @@ +.. _Open: + +Opening the GUI +=============================== + +Once the conda environment is installed, you can launch visualCaseGen by opening the `GUI.ipynb` notebook +in the `visualCaseGen/` directory. Below are several common methods for launching the notebook. If you are +using NCAR machines, the JupyterHub interface is recommended. + +.. contents:: Launch Options: + :depth: 2 + :local: + + +From the Command Line +--------------------------------------- + +.. warning:: + The command-line launch is possible only if you’re running on a local machine or have SSH tunneling + enabled. For remote access, set up SSH tunneling (described in the next section). + +Ensure the `visualCaseGen` Conda environment is activated. If not, activate it with: + +.. code-block:: bash + + conda activate visualCaseGen + +Launch the notebook from the command line by navigating to the `visualCaseGen/` directory +where `GUI.ipynb` notebook is located and running: + +.. code-block:: bash + + jupyter-lab GUI.ipynb + +This will open the Jupyter notebook in your default web browser, displaying a cell with the following code: + +.. code-block:: python + + from visualCaseGen import gui; gui + +To start the GUI, execute the cell by clicking the **Run** button or pressing `Shift + Enter`. You should +see the following welcome dialog. Click **Start** to begin using the GUI: + +.. image:: assets/launch5.png + +- Once the `Start` button is clicked, a loadbar will appear, indicating that the GUI is initializing. When the + GUI is ready, the main interface will be displayed. If the loadbar hangs, click the `Help` button on the top + right corner of the welcome dialog to see if any error messages are displayed. If you encounter any issues, + please refer to the Troubleshooting section of this documentation. + +On a Remote Machine +------------------------------------- + +To access the GUI on a remote machine, set up SSH tunneling with port forwarding. + +- Establish an SSH connection with port forwarding (the exact command may vary depending on your system): + +.. code-block:: bash + + ssh -L 8888:localhost:8888 username@remote_host + +- After connecting, activate the `visualCaseGen` Conda environment, navigate to the `visualCaseGen/` directory, and run: + +.. code-block:: bash + + conda activate visualCaseGen + cd [PATH_TO_visualCaseGen] # e.g., ~/cesm3_0_beta03_gui/visualCaseGen + jupyter-lab GUI.ipynb --no-browser + +If the above steps are successful, the command line will display a URL that you can copy and paste into your web browser +to access the Jupyter notebook. The URL will look similar to: + +.. code-block:: bash + + http://localhost:8888/lab/?token=1234567890abcdef1234567890abcdef1234567890abcdef + +Paste the url **shown in your own terminal** into your web browser to access the visualCaseGen GUI. A Jupyter +notebook with the following cell will be displayed: + +.. code-block:: python + + from visualCaseGen import gui; gui + +To start the GUI, execute the cell by clicking the **Run** button or pressing `Shift + Enter`. You should +see the following welcome dialog. Click **Start** to begin using the GUI: + +.. image:: assets/launch5.png + +- Once the `Start` button is clicked, a loadbar will appear, indicating that the GUI is initializing. When the + GUI is ready, the main interface will be displayed. If the loadbar hangs, click the `Help` button on the top + right corner of the welcome dialog to see if any error messages are displayed. If you encounter any issues, + please refer to the Troubleshooting section of this documentation. + +NCAR JupyterHub +------------------------------------- + +.. warning:: + This method is available only to users with access to NCAR systems like `derecho` or `casper`. + +- Go to NCAR JupyterHub in your web browser: + +.. code-block:: bash + + https://jupyterhub.hpc.ucar.edu/ + +- Log in by selecting "Production" under "Available NCAR Resources," then enter your NCAR credentials. + +- Start a JupyterHub server by clicking the **"start"** button under the Actions column. + +.. image:: assets/launch1.png + +- When prompted, select a resource. Although any resource is acceptable, "Casper Login" is recommended, as visualCaseGen does not require significant computational power. + +.. image:: assets/launch2.png + +- After the resource starts, navigate to the `visualCaseGen/` directory from the File Browser tab on the left. + +.. tip:: + Create a symbolic link to your CESM directory in your home directory for easier access. + +- Open the `GUI.ipynb` notebook by double clicking on it, + +.. image:: assets/launch3.png + +- When prompted, select the visualCaseGen Conda kernel from the dropdown menu. (If not prompted, select the kernel by clicking + the kernel name in the top right corner of the notebook.) + +.. image:: assets/launch4.png + +- To start the GUI, execute the first cell (with `from visualCaseGen import gui; gui`) by clicking the **Run** button + or pressing `Shift + Enter`. You should see the following welcome dialog. Click **Start** to begin using the GUI: + +.. image:: assets/launch5.png + +- Once the `Start` button is clicked, a loadbar will appear, indicating that the GUI is initializing. When the + GUI is ready, the main interface will be displayed. If the loadbar hangs, click the `Help` button on the top + right corner of the welcome dialog to see if any error messages are displayed. If you encounter any issues, + please refer to the Troubleshooting section of this documentation. + diff --git a/docs/ridge.rst b/docs/ridge.rst new file mode 100644 index 0000000..6e7fad6 --- /dev/null +++ b/docs/ridge.rst @@ -0,0 +1,78 @@ +Ridge World +============================== + +This example provides step-by-step guidance on how to generate a coupled idealized +configuration that consists of an aquaplanet with land caps at the pole and a narrow +land ridge extending between the two poles, similar to the configuration used in `Wu et al (2021) `_ . +In the example given below, the visualCaseGen GUI is used to guide users through choosing +their CESM components, setting up all the ocean input files, setting up all the land input +files, and finally setting up and configuring their case. + +Here we are not running a standard case with CESM. We are modifying the configuration substantially by changing the ocean grid, ocean bathymetry, continental geometry and land surface properties, so you should select "Custom" here. + + +Stage 0: Open visualCaseGen +-------------------------- + +Follow the instructions in the :ref:`Open` to open visualCaseGen in your Jupyter notebook environment. + +Stage 1: Select Compset +---------------------- + +After having executed the cell with the command `from visualCaseGen import gui; gui`, +and clicking the **Start** button, you will see the main interface of visualCaseGen. + +Click the **Custom** button to proceed with creating a custom compset for our idealized +Ridge World configuration. + +.. image:: assets/stage1_1.png + +Initialization time +~~~~~~~~~~~~~~~~~~~ + +Once the `Custom` button is clicked, you will be prompted to select the initialization time. +For this example, we will select `1850`` as the initialization time. + +.. image:: assets/stage1_5.png + + +Models +~~~~~~ + +Once you've selected the initialization time, visualCaseGen will prompt you to select the +models for each component class. In this ridge world case we select the following component options: +`cam` as the atmosphere; +`clm`` as the land component; `cice`` as the ice component; `mom`` as the ocean component, `srof`` +(i.e., stub run off) as the river component; `sglc`` (i.e., stub land ice) as the land ice component; +and, `swav` (i.e. stub wave) as the wave component. After all the selections are made, the +model matrix should look like: + +.. image:: assets/ridge1.png + +Model Physics +~~~~~~~~~~~~~ + +Having selected the models, you will proceed to select the physics options for each. The physics +settings determine the complexity of each model component and impact computational requirements. +For this example, we will select the following physics options which are based on the selections +made in `Wu et al (2021) `_ : + +.. image:: assets/ridge2.png + +Component Options (Modifiers) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We are now ready to finalize the compset by selecting optional physics modifiers. For this example, +we will select `(none)` for all the components except for the `clm` component where we will select +the satellite phenology (SP) mode for the land which means that aspects of the land model such as +leaf-area index are prescribed as opposed to being prognosed interactively by the land biogeochemistry. + +.. image:: assets/ridge3.png + +Stage 2: Grid +---------------------- +Having completed the compset configuration, you will now proceed to the `Grid` stage ... + +Further instructions will be added as the example is developed... + + diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 0000000..ae6cc23 --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,30 @@ +Troubleshooting +====================================== + +Below are some common issues that users may encounter while using visualCaseGen and their solutions. +If the suggested solutions do not resolve the issue, or if you encounter a different problem, please +open an issue on the visualCaseGen GitHub repository: https://github.com/ESMCI/visualCaseGen/issues/new + +Commonly Encountered Issues +--------------------------- + +- **Error displaying widget: model not found:** + This message generally appears when a previously run + `GUI.ipynb` notebook is re-opened. This error message doesn't generally indicate a problem with the GUI, + and should dissapear after running the cell with the `from visualCaseGen import gui; gui` code. + +- **ModuleNotFoundError:** No module named `z3`, `ipyfilechooser`, etc.: This error indicates that either + the `visualCaseGen`` conda environment is not installed correctly, it was not chosen as the active environment, + or it was not chosen as the kernel in the Jupyter notebook. To resolve this issue, ensure that the `visualCaseGen` + conda environment is installed correctly and activated. If the issue persists, try restarting the Jupyter notebook + kernel and selecting the `visualCaseGen` environment as the kernel. + +- **Hanging Loadbar:** If the loadbar hangs after clicking the `Start` button, click the `Help` button on the top + right corner of the welcome dialog to see if any error messages are displayed. If so, submit an issue on the + visualCaseGen GitHub repository with the error messages. + +- **mom6_bathy notebook doesn't open automatically:** 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. \ No newline at end of file