Installation¶
The fastest way of installing tensorwaves
is through PyPI:
python3 -m pip install tensorwaves
This installs the latest release that you can find on the stable branch. The latest version on the master branch can be installed as follows:
python3 -m pip install git+https://github.com/ComPWA/tensorwaves@master
but in that case, we highly recommend using the more dynamic, ‘editable mode’ instead.
Editable mode¶
tensorwaves
is an academic research project and is bound to continuously
evolve. We therefore highly recommend installing tensorwaves
from the source
code as an editable install, so
that you work with the latest version and try out your own modifications to the
source code.
Moreover, since you read as far as this, you must have an interest in particle physics, and it is researchers like you who can help bring this project further! So please, follow the following sections to set up this ‘interactive installation’.
Step 1: Get the source code¶
The source code of tensorwaves
is maintained through Git, so you need to install Git first. Once
you’ve done so, navigate to a suitable folder and run:
git clone https://github.com/ComPWA/tensorwaves.git
cd tensorwaves
After that, there should be a folder called tensorwaves
into which we
navigated just now. We’ll call this folder the local repository.
When new commits are merged into the master branch of tensorwaves, you need to update your local copy of the source code as follows:
git checkout master
git pull
It’s best to have a clean your working tree before you do a git pull.
Step 2: Create a virtual environment¶
It is safest to install tensorwaves
within a virtual environment, so that all
Python dependencies are contained within there. This is helpful in case
something goes wrong with the dependencies: you can just trash the environment
and recreate it. There are two options: Conda or Python’s venv.
Conda can be installed without administrator
rights, see instructions on this page. Once installed, navigate to the
local repository and create the Conda environment for
tensorwaves
as follows:
conda env create
This command uses the environment.yml file
and immediately installs tensorwaves
in editable mode.
After Conda finishes creating the environment, you can activate it with as follows:
conda activate tw
You need to have the environment called tw
activated whenever you want
to run tensorwaves
.
Alternatively, you can use Python’s venv, if you have that available on your system. All you have to do, is navigate into local repository and run:
python3 -m venv ./venv
This creates a folder called venv
where all Python packages will be
contained. You first have to activate the environment, and will have to do so
whenever you want to run tensorwaves
.
source ./venv/bin/activate
Now you can safely install tensorwaves
in editable mode:
pip install -e .
That’s it, now you’re all set to help develop the project!
Step 3: Test the installation¶
Once you’ve installed tensorwaves
, simply launch a Python interpreter and
run:
import tensorwaves
If you don’t get any error messages, all worked out nicely!
For more thorough testing, navigate back to the you can run the unit tests:
pip install -e .[test] # install dependencies for testing
pytest -n auto
After that, it’s worth having a look at the contribute page!
Updating to the latest version¶
When new commits are merged into the master branch, you need to update your local copy of the source code as follows:
git checkout master
git pull
pip install -e .
It’s best to have a clean your working tree before you do a git pull. We also call pip install again, because we sometimes introduce upgrades of the dependencies.
If you face any issues when calling pip install -e .
, just trash your
install Conda environment or venv and repeat from Step 2.