Installing Caelus Python Library (CPL)

CPL is a python package for use with OpenFOAM or Caelus CML. Therefore, it is assumed that users have a properly functioning OpenFOAM installation on their system. In addition to OpenFoAM/Caelus CML and python, it also requires several scientific python libraries:

The quickest way to install CPL is to install through Anaconda Python Distribution. This distribution provides a comprehensive set of python packages necessary to get up and running with CPL. Once installed, please proceed to Check installation to learn how to use CPL.

For users wishing to install CPL from the git repository, this user guide recommends the use of Anaconda. An alternate approach using Python virtualenv is described at the end of this section, but will require some Python expertise on the part of the user.

The default installation instructions use Python v2.7. However, CPL is designed to work with both Python v2.7 and Python v3.x versions.

Installing CPL with Anaconda Python Distribution

Install Anaconda

  1. Download the Anaconda installer for your operating system.

  2. Execute the downloaded file and follow the installation instructions. It is recommended that you install the default packages.

  3. Update the anaconda environment according to installation instructions

Note

Make sure that you answer yes when the installer asks to add the installation location to your default PATH locations. Or else the following commands will not work. It might be necessary to open a new shell for the environment to be updated.

Install using pip

pip install py-caelus

Install CPL from source

  1. Obtain the CPL source from the public Git repository.

    # Change to directory where you want to develop/store sources
git clone https://github.com/sayerhs/cpl
cd cpl

  2. Create a custom conda environment

    # Ensure working directory is CPL
conda env create -f etc/caelus3.yml

    Note

    1. Developers interested in developing CPL might want to install the development environment available in etc/caelus3-dev.yml. This installs additional packages like sphinx for document generation, and pytest for running the test suite.

    2. By default, the environment created is named caelus when using etc/caelus3.yml and caelus-dev when using etc/caelus3-dev.yml. The user can change the name of the environment by using -n <env_name> option in the previous command.

  3. Activate the custom environment and install CPL within this environment

    source activate caelus
pip install .

    For editable development versions of CPL use pip install -e . instead.

After completing this steps, please proceed to Check installation to test that your installation is working properly.

Alternate Installation – Virtualenv

This method is suitable for users who prefer to use the existing python installations in their system (e.g., from apt-get for Linux systems). A brief outline of the installation process is described here. Users are referred to the virtual environments docs for more information.

Install CPL

  1. Obtain the CPL source from the public Git repository.

    # Change to directory where you want to develop/store sources
git clone https://github.com/sayerhs/cpl
cd cpl

  2. Create a virtual environment with all dependencies for CPL

    # Create virtual environment
python3 -m venv --system-site-packages .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
python3 -m pip install -r requirements.txt

  3. Activate virtual environment and install CPL into it

    # Ensure that we are in the right environment
source .venv/bin/activate
pip install . # Install CPL within this environment

Check installation

After installing CPL, please open a command line terminal, activate the right python environment, and execute caelus -h to check if the installation process was completed succesfully. If everything was installed and configured successfully, users should see a detailed help message summarizing the usage of caelus. At this stage, you can either learn about building documentation and executing unit tests (provided with CPL) in the next sections or skip to Configuring Caelus Python Library to learn how to configure and use CPL.

Building documentation

A local version of this documentation can be built using sphinx. See Install CPL from source for more details on installing the developer environment and sources.

# Change working directory to CPL
cd docs/

# Build HTML documentation
make html
# View in browser
open build/html/index.html

# Build PDF documentation
make latexpdf
open build/latex/CPL.pdf

Running tests

The unit tests are written using py.test. To run the tests executing py.test tests from the top-level CPL directory. Note that this will require the user to have initialized the environment using etc/caelus3-dev.yml.