workon

Since Qaptiva version 1.10, the software supports multiple Python versions (3.10–3.14). Users can choose which Python version to use, and the use of a virtual environment is strongly recommended to ensure the software functions properly and dependencies remain isolated.

To manage these environments, Qaptiva provides the workon command. It is a command-line tool that simplifies the creation, cloning, and activation of virtual environments by acting as a wrapper around virtualenv and virtualenv-clone.

In addition, workon integrates with Environment Modules (the environment-modules package) to load the appropriate Qaptiva runtime or development environment. When an environment is activated, it automatically configures the system so the software is ready to use, including variables such as PATH and PYTHONPATH, as well as required dependencies like CUDA or ROCm.

Virtual environments

Reference Virtual Environments

We provide a set of reference virtual environments that you can clone. These reference environments come with all the necessary dependency packages pre-installed, saving you time and effort in setting up your development environment.

Creating Virtual Environments

You have the option to create either a new, empty virtual environment or to clone one of our reference environments (introduced above). The workon command supports various Python versions, allowing you to specify the version you need for your project.

To see detailed usage instructions, you can use the -h option with the workon command:

workon -h

Workon commands

Key Options

activate: -a | --activate
create: -c | --create
list: -l | --list

To see detailed usage instructions on specific options, you can use the -h along with the specific option:

workon -a -h

Listing virtual environments

To list all virtual environments in the current directory, use the workon --list command:

workon -l

To list the available reference virtual environments, use:

workon -lr

Creating an empty virtual environment

For creating an empty virtual environment, you need to specify the Python version to use. If you don’t specify any Python version the empty environment is created using Python 3.14.

workon -c myenv -p 312 -e

Cloning a reference virtual environment

For cloning a reference virtual environment, you need to specify either the name of the reference environment or the Python version.

workon -c myenv -f ref312  # or
workon -c myenv -p 312

Activating a virtual environment

To use a virtual environment, you need to activate it. When you activate a virtual environment, the workon --activate command will load the Qaptiva module. This module sets the necessary variables to find the Qaptiva software for this Python version. It is recommended to use the latest supported Python version.

workon -a myenv [--devel]

Tip

Running workon without arguments automatically activates the default virtual environment.

The default environment comes from $WORKON_DEFAULT_VENV. If unset, ref314 is used.

workon --devel

Deactivating the current virtual environment

To deactivate the current virtual environment, use the workoff command; workoff will unload the Qaptiva module to unset the variables that were set at the time of activation.

workoff

Virtual environment in JupyterLab

Every time a user starts a new kernel named qaptiva3x, the system clone the notebook3x Python environment from its matching reference environment. This environment is pre-configured with essential packages, ensuring that users can immediately begin their work without needing to set up their environment from scratch.

Managing the `notebook3x` Environment

Users have full control over the notebook3x environment under their user profile. They can perform the following actions:

Acessing and Managing Environments: The notebook3x environments can be listed using the workon -l command. All workon commands can be used to manage the notebook3x environment.
Deleting the Environment: If a user wishes to delete the notebook3x environment, they can do so. This might be useful if the environment becomes cluttered or if there is a need to reset it.
Environment Recreation: The notebook3x environment is designed to be resilient. If the environment is deleted, it will be automatically recreated the next time the user starts the corresponding qaptiva3x kernel. This ensures that users always have a clean, functional environment available without any manual intervention.