Skip to content

Commit 374fa53

Browse files
committed
Merge remote-tracking branch 'origin/main'
2 parents 55ef921 + 108d16c commit 374fa53

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+702
-28
lines changed

README.md

+17-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,20 @@
11
# visualCaseGen
22

3-
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:
3+
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.
44

5-
https://github.com/ESMCI/visualCaseGen/wiki/Quickstart
5+
## Key Features
6+
7+
- **Guided Configuration**: visualCaseGen guides users through the main steps of configuring CESM cases, ensuring that all necessary components are included while preventing incompatible selections.
8+
9+
- **Standard and Custom Options**: Users can choose from predefined standard compsets and grids or create custom configurations tailored to specific modeling needs.
10+
11+
- **Real-Time Compatibility Checks**: As you make selections, visualCaseGen highlights incompatible options, helping you navigate the complexities of model configurations effectively.
12+
13+
- **Easy Navigation**: The tool breaks down the configuration process into three clear stages:
14+
1. **Compset Selection**: Choose from standard or custom compsets, including all associated models and physics options.
15+
2. **Grid Configuration**: Select or create grids tailored for your application, ensuring compatibility across individual component grids and compsets.
16+
3. **Case Launch**: Finalize your configuration and create your CESM case with a few clicks.
17+
18+
## User Manual
19+
20+
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

88 KB
Loading

docs/assets/Stage1_4.png

115 KB
Loading

docs/assets/Stage1_6.png

57.4 KB
Loading

docs/assets/Stage1_7.png

68.4 KB
Loading

docs/assets/Stage1_8.png

90 KB
Loading

docs/assets/Stage1_9.png

68.3 KB
Loading

docs/assets/Stage2_1.png

23.6 KB
Loading

docs/assets/Stage2_2.png

150 KB
Loading

docs/assets/Stage2_3.png

33.4 KB
Loading

docs/assets/Stage2_4.png

81.6 KB
Loading

docs/assets/Stage2_5.png

72.5 KB
Loading

docs/assets/Stage2_6.png

88.8 KB
Loading

docs/assets/Stage2_7.png

83.7 KB
Loading

docs/assets/Stage3_1.png

50.2 KB
Loading

docs/assets/Stage3_2.png

80.9 KB
Loading

docs/assets/Stage3_3.png

170 KB
Loading

docs/assets/demo3.gif

9.62 MB
Loading

docs/assets/launch1.png

152 KB
Loading

docs/assets/launch2.png

164 KB
Loading

docs/assets/launch3.png

371 KB
Loading

docs/assets/launch4.png

623 KB
Loading

docs/assets/launch5.png

56.8 KB
Loading

docs/assets/ridge1.png

96.3 KB
Loading

docs/assets/ridge2.png

71.6 KB
Loading

docs/assets/ridge3.png

108 KB
Loading

docs/assets/stage1_1.png

25.9 KB
Loading

docs/assets/stage1_2.png

30.3 KB
Loading

docs/assets/stage1_3.png

64.3 KB
Loading

docs/assets/stage1_5.png

26.1 KB
Loading

docs/basics.rst

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
visualCaseGen Basics
2+
====================
3+
4+
This section defines key concepts in visualCaseGen that will be referenced throughout the documentation.
5+
6+
7+
Configuration Variable
8+
-----------------------
9+
10+
Configuration variables are essential CESM settings that must be defined before creating a case.
11+
These include choices like the model, model physics, resolution, and grid options that are set in
12+
CESM XML and user namelist files. visualCaseGen provides an intuitive, form-based interface for
13+
configuring these variables, ensuring compatibility and completeness. Only the variables required
14+
for case instantiation are included in visualCaseGen; other settings that can be adjusted after
15+
case creation, such as simulation duration, are not included in the GUI.
16+
17+
Stage
18+
-----
19+
20+
In visualCaseGen, a stage represents a group of related CESM configuration variables that can be
21+
set together. Examples of stages include models, physics options, and resolutions. Stages introduce
22+
a logical hierarchy, where those listed earlier hold higher precedence. For instance, model selection
23+
is a prerequisite for defining model physics, so the model stage takes precedence. visualCaseGen
24+
guides users through each stage in the proper order, ensuring that configurations are compatible
25+
at each step.
26+
27+
A stage is deemed complete when all of its configuration variables have been set. When a stage is
28+
complete, visualCaseGen will automatically advance to the next stage. Users can also navigate
29+
between stages by clicking the `Revert` button on the top bar of each Stage to return to the previous
30+
stage or the `Proceed` button to advance to the next stage, but if there are any incomplete configuration
31+
variables, visualCaseGen will prompt users to fill them in before proceeding. The `Defaults` button on
32+
the top bar of each stage allows users to quickly set all configuration variables to their default
33+
values, if available. The `Info` button provides additional information about the stage and its
34+
configuration variables.
35+
36+
Standard vs Custom
37+
------------------
38+
39+
During configuration, users can choose between standard and custom options for certain settings,
40+
like compsets, resolutions, and model grids. Standard options are predefined CESM configurations
41+
that are generally easier and safer to use, while custom options allow for greater flexibility.
42+
visualCaseGen assists users through the custom configuration process to maximize compatibility,
43+
but custom setups may require additional troubleshooting. For any issues with custom configurations,
44+
please refer to the Troubleshooting section of this guide.
45+
46+
47+
Resolution vs Grid vs Model Grid
48+
--------------------------------
49+
50+
In CESM terminology, *resolution* and *grid* are often used interchangeably,
51+
both referring to the combination of model grids used in a CESM simulation. Unless
52+
specifically noted as a *model grid* (i.e., a grid unique to a particular component,
53+
such as the ocean grid), the term *grid* in the context of visualCaseGen should be understood as
54+
*resolution*, meaning the full collection of *model grids* used in a particular CESM case.

docs/compset.rst

+121
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
Stage 1/3: Compset
2+
==================
3+
4+
In this stage, the component set (compset), i.e., the collection of models (`cam`, `clm`, `mom`, etc), physics
5+
(`CAM70`, `CLM50`, `MOM6`, etc), and component options. e.g., `LT` (low top), `SP` (satellite phenology), `MARBL-BIO`,
6+
etc. are determined.
7+
You'll start by choosing between the `Standard` compset mode, which provides predefined and stable CESM configurations,
8+
and the `Custom` compset mode, which allows for more tailored combinations for unique experiments.
9+
10+
.. image:: assets/stage1_1.png
11+
12+
Standard Compsets
13+
------------------
14+
15+
- **Support Level:** You can select from a list of all standard compsets or only those that are scientifically
16+
supported. `Supported` compsets have been validated by CESM developers, ensuring they produce
17+
scientifically vetted results. These are typically recommended for production runs. The `All` option,
18+
however, includes experimental compsets that may not be validated but can be useful for testing and
19+
development. Selecting a supported compset ensures that you are working with configurations approved
20+
for stability and accuracy, while the `All` option offers broader but potentially unstable options for
21+
specialized needs.
22+
23+
.. image:: assets/stage1_2.png
24+
25+
- **Models to Include:** If you choose the `Supported` option, a list of scientifically validated
26+
compsets will appear for you to choose from. However, if you choose the `All` option, you'll be
27+
presented with a *model matrix* to refine the list of compsets displayed. This matrix allows you
28+
to specify which model components you want to include. For instance, if you select `cam` as the
29+
atmosphere model and `mom` as the ocean model, the list will filter down to include only those
30+
compsets that incorporate both. If you're flexible with certain components, you can select `any`
31+
for those classes, or click the `Defaults` button in the Stage top bar to apply typical defaults
32+
for all components, streamlining your selection. This feature is particularly useful if you're
33+
unsure about specific settings or wish to adhere to commonly used configurations.
34+
35+
.. image:: assets/stage1_3.png
36+
37+
- **Standard Compsets List:** After refining your options, visualCaseGen will display a list of
38+
matching compsets. Each compset is labeled with an alias and incorporates an initialization time
39+
and a short description of the included models, providing a snapshot of each configuration.
40+
To narrow down the list further, you can use the search box above the list. Typing keywords
41+
in the search box will display all compsets containing one or more of the search terms. For
42+
precise filtering, use double quotes around terms for exact matches. This flexibility makes
43+
it easy to locate specific compsets or explore different configurations to find the most
44+
suitable one for your simulation needs.
45+
46+
.. image:: assets/Stage1_4.png
47+
48+
After selecting a compset, visualCaseGen will guide you to the next primary stage, `Grid`, where
49+
you'll select a model resolution compatible with your chosen compset.
50+
51+
Custom Compsets
52+
------------------
53+
54+
.. note::
55+
If you initially selected the `Standard` compset mode, the `Custom` compset stages will not
56+
display, and instead visualCaseGen will proceed directly to the `Grid` stage. To switch to the `Custom`
57+
compset mode after already completing the `Standard` compset stages, you can click `Revert`
58+
buttons to navigate back to the selection of configuration mode.
59+
60+
If you prefer to build a custom compset, visualCaseGen provides a step-by-step process,
61+
starting with the initialization time for your experiment. This choice impacts the initial
62+
conditions and forcings for your simulation. You can choose from:
63+
64+
- 1850: Represents pre-industrial conditions and is suitable for fixed-time-period runs, such as for model spin-ups.
65+
- 2000: Represents modern-day conditions, also appropriate for fixed-period simulations.
66+
- HIST: Represents a historical run setup, which covers transient simulations (e.g., from 1850 through 2015) that evolve with changing conditions over time.
67+
68+
.. image:: assets/stage1_5.png
69+
70+
Once you've selected the initialization time, visualCaseGen will prompt you to select the
71+
models for each component class. You'll see options that include active models, data models
72+
(prefixed with d, like `datm`), and stub models (prefixed with s, like `sice`). Data models
73+
perform the basic function of reading preexisting forcing data, modifying that data, and then
74+
sending it to active models via the coupler. Stub models act as placeholders required by the CESM
75+
coupler infrastructure but have no impact on the simulation. This variety allows you to
76+
configure a custom compset that includes as many or as few active components as desired,
77+
depending on the specific goals of your simulation.
78+
79+
.. image:: assets/Stage1_6.png
80+
81+
As you make selections in this stage and elsewhere, visualCaseGen will guide you by crossing
82+
out incompatible options, helping to prevent invalid configurations. For example, if you select
83+
`cam` for the atmosphere and `mom` for the ocean, the GUI will disable several other model
84+
options that are incompatible with this combination. This real-time feedback keeps your
85+
configuration process streamlined and ensures that all selected options work together compatibly.
86+
87+
.. image:: assets/Stage1_7.png
88+
89+
At any stage, you can click on any crossed-out option to view a brief explanation of
90+
why it's incompatible with your current selections for additional guidance.
91+
92+
.. image:: assets/Stage1_8.png
93+
94+
After choosing your models, you'll proceed to select the physics options for each. The physics
95+
settings determine the complexity of each model component and impact computational requirements.
96+
Higher version numbers indicate newer and more complex physics for a given model. Depending on
97+
the model, you may have multiple physics options available. For example, `cam` and
98+
`clm` have multiple physics options, while other models may offer only one, in which case it
99+
will be selected by default. Since each physics option provides different levels of model complexity,
100+
the selection should be based on the specific requirements of your simulation. Refer to
101+
the individual model documentations for more information on the available physics options.
102+
103+
.. image:: assets/Stage1_9.png
104+
105+
The final part of custom compset creation is selecting optional physics modifiers.
106+
Modifiers allow additional adjustments to physics and parameter settings, offering
107+
further customization to meet modeling requirements and goals. Each component class
108+
is represented in individual tabs within this stage. You can switch between tabs to
109+
select modifiers or opt out of a modifier by choosing `(none)`. Tabs with available
110+
modifiers will display a red question mark until a selection is made. While you can
111+
select multiple modifiers for a single component class, be cautious: visualCaseGen
112+
does not verify compatibility between multiple modifiers within a single component,
113+
so it's advisable to consult CESM documentation or model experts if you're using complex
114+
modifier combinations.
115+
116+
.. image:: assets/Stage1_10.png
117+
118+
Once you've completed the selection of models, physics, and optional modifiers,
119+
visualCaseGen will automatically advance to the next main stage, `Grid`, where
120+
you'll select a model resolution compatible with your chosen compset.
121+

docs/creating_case.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Stages of Creating a Case
2+
==========================
3+
4+
The workflow for creating a CESM case using visualCaseGen is divided into three main stages:
5+
6+
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.
7+
2. **Resolution**: In this stage, the user will select the resolution of the simulation, i.e., the collection of model grids.
8+
3. **Launch**: In this final stage, the user will create and configure the case.
9+
10+
Proceed to the following sections to learn more about each stage.

docs/fillindian.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Fill Indian Ocean
2+
=================
3+
4+
Instructions coming soon...

docs/grid.rst

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Stage 2/3: Grid
2+
===============
3+
4+
The second major step in configuring your CESM case is choosing a resolution, which
5+
is a specific set of grids for each active and data model in the compset. You may
6+
select either a standard, out-of-the-box resolution or create a custom one by combining
7+
existing model grids. In `Custom` mode, you can also generate custom model grids for CLM and/or MOM6
8+
using auxiliary tools included in visualCaseGen. Begin by selecting between `Standard`
9+
and `Custom` grid modes.
10+
11+
.. image:: assets/Stage2_1.png
12+
13+
.. note:: In CESM terminology, *resolution* and *grid* are often used interchangeably,
14+
both referring to the combination of model grids used in a CESM simulation. Unless
15+
specifically noted as a *model grid* (i.e., a grid unique to a particular component,
16+
such as the ocean grid), the term *grid* in this context should be understood as
17+
*resolution*, meaning the full collection of *model grids* used in a particular CESM case.
18+
19+
Standard Grids
20+
------------------
21+
22+
Select from the available list of resolutions (combinations of model grids) below.
23+
Resolutions known to be incompatible with your chosen compset have been omitted
24+
from this list. Use the search box to refine the list further. For exact matches,
25+
use double quotes; otherwise, the search will display all grids containing one
26+
or more of the search terms.
27+
28+
.. image:: assets/Stage2_2.png
29+
30+
After selecting a grid, visualCaseGen will advance to the `Launch` stage, where
31+
you can create your CESM case using the chosen compset and grid configuration.
32+
33+
Custom Grids
34+
------------------
35+
36+
In Custom Grid mode, you can build a custom grid by mixing and matching standard
37+
model grids or generating new MOM6 and/or CLM grids with specialized tools that come with visualCaseGen.
38+
Start by specifying a path to save the new grid files and a name to refer to this
39+
new grid in the configuration process and beyond.
40+
41+
.. image:: assets/Stage2_3.png
42+
43+
After clicking `Select`, a file browser will open to help you locate your preferred
44+
directory for saving the new grid files. Once the directory is selected, enter the
45+
new grid name in the text box at the top right and click `Select` to proceed.
46+
47+
.. image:: assets/Stage2_4.png
48+
49+
Atmosphere Grid
50+
~~~~~~~~~~~~~~~
51+
52+
Next, choose an atmosphere grid from the list of compatible options based on the
53+
compset you selected in the `Compset` stage. Use the search box to filter options if needed.
54+
This chosen atmosphere grid will be integrated with other model grids to form your custom CESM grid (resolution).
55+
56+
.. image:: assets/Stage2_5.png
57+
58+
Ocean Grid
59+
~~~~~~~~~~
60+
61+
For the ocean grid, if MOM6 is selected as the ocean model, you can either select a standard
62+
ocean grid or create a new MOM6 grid. When creating a new MOM6 grid, you'll specify parameters
63+
such as grid extent and resolution, after which you'll be directed to a separate notebook that
64+
uses the `mom6_bathy` tool to generate the new grid and bathymetry.
65+
66+
If using a standard ocean grid, select one from the list compatible with your chosen compset
67+
and atmosphere grid. If creating a new MOM6 grid, complete the required parameters, then proceed
68+
to launch the `mom6_bathy` tool for final customization.
69+
70+
.. image:: assets/Stage2_6.png
71+
72+
After specifying all ocean grid parameters, click `Launch mom6_bathy`. This will open an
73+
auto-generated Jupyter notebook where you can fine-tune the ocean grid bathymetry and generate
74+
all necessary input files. For more details on mom6_bathy, refer to its documentation: https://ncar.github.io/mom6_bathy/
75+
76+
.. note:: If the `mom6_bathy` notebook doesn't open automatically, make sure that your browser allows
77+
pop-ups from visualCaseGen. If the notebook still doesn't open, you can manually launch it by
78+
navigating to the `mom6_bathy_notebooks/` directory in your visualCaseGen installation and opening
79+
the notebook corresponding to your custom grid.
80+
81+
82+
Land Grid
83+
~~~~~~~~~
84+
85+
Following ocean grid selection or creation, you'll move to land grid selection. If CLM is chosen
86+
as the land model, you can also modify an existing CLM grid. If so, select a base land grid for
87+
customization.
88+
89+
.. image:: assets/Stage2_7.png
90+
91+
.. note:: Detailed instructions on customizing an existing CLM grid will be added here shortly.
92+
93+
Once atmosphere, ocean, and land grids have been chosen or created, custom grid setup is complete.
94+
visualCaseGen will guide you to the final stage, `Launch`, where you can create a CESM case based on
95+
the specified compset and grid.

0 commit comments

Comments
 (0)