Build using pip

1. Setup

For the build via pip, you do not need to build the C++ backend manually, but you can work with python only. In order to so, you first have to setup your python environment. All Python dependencies are listed within the pyproject.toml file. They are installed automatically when you build the Python library using pip.

Note

If you do not want to modify the source code and just want to use the most recent version of pairinteraction, you can install pairinteraction directly from the GitHub repository by running pip install git+https://github.com/pairinteraction/pairinteraction.

If not stated otherwise, all commands should be executed from inside the virtual environment and the root directory of the pairinteraction repository.

2. Basic installation

After cloning the repository and creating the virtual environment, you can build and install the software by running:

pip install -e .

This will call CMake automatically to build the C++ backend, the Python library, and the graphical user interface. In order for pip to find CMake and VCPKG, make sure you have adjusted your environment variables as discussed in our section on setting up your development environment. The option -e installs the software in editable mode, which means that changes to the python source code are directly reflected in the installed package. If you don’t want this, you can omit the -e option to install the current version of the software into the virtual environment.

The graphical user interface can now be started by executing:

start_pairinteraction_gui

To use the Python library within your code, you can simply run your python code from inside the virtual environment.

3. Testing

First run

pip install .[tests]

to install the relevant packages for your python environment. Tests of the Python library and graphical user interface can be run by executing:

pytest

If you created your own test and it got skipped, you can get more information on it by running

pytest -rsx

4. Build Documentation

For building the documentation, we are using Sphinx. As the build process is highly platform dependent, detailed information is provided on our page about the documentation:

5. Advanced installation options

Advanced options for developers when building the package:

pip install --no-build-isolation -Cbuild-dir=build_pip -v -e .

--no-build-isolation: Avoid re-creations of virtual environments for building the package (to use this you first have to install all build dependencies, which are stored inside .build_requirements.txt so you can install them via uv pip install -r .build_requirements.txt).

-Cbuild-dir=build: Specify a build directory and reuse it for faster future builds.

-v: Make the output more verbose.

-e: Install the package in editable mode (i.e. changes to the python files inside pairinteraction are immediately effective).

To install all dependencies without building the package, confer the python setup.