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

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.

• 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

Download CESM with visualCaseGen

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.

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

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:

cd visualCaseGen
conda env create -f environment.yml

This will create the visualCaseGen conda environment. Activate the visualCaseGen conda environment by running the following command:

conda activate visualCaseGen

Verify Installation

To verify that visualCaseGen was installed correctly, run the test suite:

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.