Install¶
To get the latest stable release of orbithunter running locally, the package can either be installed locally via the Python package installation manager pip or can be accessed via a Docker container.
Docker installation¶
To facilitate scientific developments outside of the core development, the latest release has been used to create a Docker image. To the uninitated, Docker is a platform for containerizing applications, which, broadly speaking, makes it so the Python dependencies and issues arising from differences in operating systems can be avoided. The Docker image itself runs a jupyter notebook kernel, allowing the jupyter notebook GUI to be used in the local machine’s browser. Crudely speaking, the containing is acting as a server/virtual machine, serving the jupyter notebook application, saving all local files and code to the Docker container.
Important notes: the port opened to allow the local machine to interact with the container is hard-coded to be 8887, meaning that trying to run two containers on the same machine won’t work currently. This is simply because I’m new to Docker and haven’t learned how to do anything else yet.
Acquiring the Docker image¶
In exchange for avoiding the local installation of Python, orbithunter and its requirements the user must install the Docker application . During the installation process, Docker is going to ask for permissions multiple times and might require the installation of WSL 2 files (linux compatibility) if not already present.
Once the application is installed, the Docker image can be pulled from the remote repository by opening command line and typing:
docker pull orbithunter/orbithunter:latest
At which point, the image will be downloaded. This image will be displayed in the Docker application under the Local portion of the Images tab.
Running the Docker image¶
The easiest way to instantiate the container is to run the following in command line, replacing <container name> with whatever is the desired name.:
docker run --name <container name> -p 8887:8887 orbithunter/orbithunter:latest
The -p switch opens the local port 8887 allowing for the jupyter notebook GUI to be opened in a browser. This prints output, the last bit of which will look like the following. The notebook accomplished by copying the last (for some reason it has to be the latter) URL to a browser (only ever been tested on chrome + windows).
Or copy and paste one of these URLs:
http://e3954f15092d:8887/?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
or http://127.0.0.1:8887/?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Once the jupyter GUI is open, it can be utilized as per usual. All computations and output data will be saved to the container; which will be randomly named if no name was provided. To restart the container after it has been turned off, run the command:
docker start <container_name>
Installation via pip¶
orbithunter requires Python 3.7, 3.8, or 3.9. If you do not already have a Python environment configured on your computer, please see the instructions for installing the full scientific Python stack.
It is assumed that the default Python environment already configured on
your computer and you intend to install orbithunter
inside of it. If you want
to create and work with Python virtual environments, please follow instructions
on venv and virtual
environments.
First, make sure you have the latest version of pip
(the Python package manager)
installed. If you do not, refer to the Pip documentation and install pip
first.
Install the current release of orbithunter
with pip
:
pip install orbithunter
To upgrade to a newer release use the --upgrade
flag:
pip install --upgrade orbithunter
If you do not have permission to install software systemwide, you can
install into your user directory using the --user
flag:
pip install --user orbithunter
Alternatively, you can manually download orbithunter
from
GitHub or
PyPI.
To install one of these versions, unpack it and run the following from the
top-level source directory using the Terminal:
pip install .
Extra packages¶
Note
Some optional packages are required for full functionality of all orbithunter modules.
The two modules which are not supported by the default install are orbithunter.persistent_homology
and orbithunter.machine_learning
. These act as an API that allows interaction with
gudhi
, scikit-learn
, and tensorflow
packages.
The following extra packages provide additional functionality. See the
files in the requirements/
directory for information about specific
version requirements.
Gudhi and Python optimal transport for topological data analysis
To install orbithunter
and extra packages, do:
pip install orbithunter[extra]
To explicitly install all optional packages, do:
pip install ipykernel jupyterlab ipython gudhi pot scikit-learn tensorflow
Or, install any optional package (e.g., gudhi
) individually:
pip install gudhi
Warning
To get POT to install correctly, you need to have cython and numpy BEFORE you run:
pip install pot
Testing¶
Orbithunter uses the Python pytest
testing package. You can learn more
about pytest on their homepage.
Test a source distribution¶
After navigating to the downloaded source directory, the tests can be evaluated by the following commands:
pytest .
or for more control, pytest arguments can be included
pytest –pyargs .
or for individual files e.g. test_basic.py
pytest –pyargs test_basic.py
For those that are unaware .
is synonymous with “evaluate in the current directory”. Pytest will automatically
search for the tests folder and any file that begins with the prefix “test”.