Installation

IMSI and its dependencies can be installed from git or PyPI into a Python 3 virtual environment.

Note

ECCC users on U2 can access the group environment by referencing the CanESM docs.

Creating a virtual environment

You can create a virtual environment using UV (recommended):

>> uv venv imsi-venv --python=3.12   # Python 3.12+ is supported
>> source activate imsi-venv

Or, to create a virtual environment with standard python tooling (use venv):

>> python3 -m venv imsi-venv
>> source imsi-venv/bin/activate

Installing imsi into your environment from PyPI

# install IMSI directly from PyPI
>> uv pip install cimsi

Or you can use standard python tooling with pip:

>> pip install cimsi

Local installation

IMSI can be installed locally by cloning the source repository. You can use the -e flag to install in editable/development mode.

>> git clone git@gitlab.science.gc.ca:CanESM/imsi.git
>> cd imsi
>> uv pip install -e .
# or pip install -e . for standard python tooling

Testing the installation

After installation, verify IMSI is available by running:

>> imsi --version

This should print the current IMSI version.

Tab Completion

Tip

If you are using bash v >= 4.4 and Python click v >= 8.x, you can enable tab-completion for imsi CLI commands. These are not required and are simply for convenience.

Steps:

  1. Activate an imsi environment

>> source /path/to/imsi/bin/activate

You can confirm that the environment is active by entering which imsi on your command line.

  1. Generate the shell functions required, and save them to a file in a location accessible to you.

>> _IMSI_COMPLETE=bash_source imsi > ~/.imsi-complete.bash

In the example above, the file .imsi-complete.bash is saved to the user’s home directory.

  1. Source the file. You can do this on the command line or from within your profile.

# .profile
>> source ~/.imsi-complete.bash

Result:

You should now be able to use tabs to trigger suggested functions and options for imsi commands. These tab-completions are triggered using two tabs.

>> imsi <TAB><TAB>
build          config         list           save-restarts  status
chunk-manager  ensemble       log-state      set            submit
clean          iss            reload         setup
>> imsi setup -<TAB><TAB>
--runid         --ver           --model         --seq           --flow          -h
--repo          --exp           --fetch_method  --machine       --postproc      --help

The generalized instructions can also be found in the click documentation on Shell Completion