1. Getting Started with Python

Installed versions of the OpenBT Python package contain and wrap a dedicated set of OpenBT C++ command line tools. In particular, the package is hard-coded to use only its internal set of tools.

Typically, nontrivial Python packages are pre-built into binary wheels by developers so that each wheel is dedicated to a specific operating system and a particular Python version. Users install the particular wheel that matches their setup. However, OpenBT wheels would also have to be built with respect to a particular MPI implementation, which is outside of how the Python packaging system works. As a result, the software is distributed only as a source distribution and is built on demand for each case with the compiler suite and matching MPI implementation provided by the user.

The building of the command line tools is done automatically during the Python package build/install process by invoking under-the-hood the tools’ Meson build system. While both Meson and its build backend ninja are used internally to build the Python package, they are installed automatically and temporarily just for building the package.

1.1. Dependencies

Before building and installing the openbt Python package, users must provide

  • a compiler suite that includes a C++ compiler that supports the C++14 standard,

  • an MPI installation that is compatible with the compiler suite, and

  • optionally the Eigen software package.

Note that if installing MPI using a package manager, related developer library packages such as libopenmpi-dev or libmpich-dev might need to be installed in addition to the base MPI packages such as openmpi-bin or mpich.

Our GitHub actions presently test OpenBT with both Open MPI and MPICH. In particular, the actions test the package with these MPI implementations installed

  • via package managers such as Ubuntu’s Advanced Packaging Tool (apt) and homebrew on macOS as well as

  • using pip to install Python packages prepared by mpi4py that contain a single MPI implementation.

In addition, we have successfully run tests manually with the Intel MPI implementation as installed by experts on a cluster and made available as a module.

While our set of GitHub actions currently test Anaconda installations, the setup of those tests within the action runner is less than desirable. In particular, the action no longer succeeds to build OpenBT if an MPI implementation is installed using Conda. Rather, the action installs an MPI implementation from PyPI using pip, which is less clean than a Conda installation. Users who prefer to use Conda should proceed with extra caution.

1.2. Install from PyPI

This OpenBT Python package is not currently distributed on PyPI since a PyPI OpenBT project already exists. That PyPI project space will eventually be transferred to this project so that distribution of this package will be enabled by PyPI under the name openbt.

1.3. Install from clone

After setting up and activating a virtual environment, users can build and install the package from a clone of the OpenBT repository by executing

$ cd /path/to/OpenBT/openbt_pypkg
$ python -m pip install .

The package can be installed in developer/editable mode by executing

$ cd /path/to/OpenBT/openbt_pypkg
$ python -m pip install -v -e .

In this latter case, the command line tools are built automatically and installed at /path/to/OpenBT/openbt_pypkg/src/openbt/bin.

1.4. Testing

The OpenBT package contains an integrated test suite, which can be used to minimally test an installation by executing

$ python
>>> import openbt
>>> openbt.__version__
'<version>'
>>> openbt.test()

Of course, users should test their installation and the package further to confirm that it satisfies their requirements.