{ "cells": [ { "cell_type": "markdown", "id": "f1be9e2f", "metadata": {}, "source": [ "# Installation\n", "\n", "## Stable Releases\n", "\n", "
\n", "Warning:\n", "\n", " \n", "We are preparing a 1.0 release. Until then, these instructions for installing a stable release will not work yet. If you enjoy living on the edge, try the development release as explained in the “Latest Git Revision” section below.\n", "
\n", "\n", "The following dependencies are required to run selector properly,\n", "\n", "* Python >= 3.6: http://www.python.org/ \n", "* NumPy >= 1.21.5: http://www.numpy.org/\n", "* SciPy >= 1.5.0: http://www.scipy.org/\n", "* PyTest >= 5.3.4: https://docs.pytest.org/\n", "* PyTest-Cov >= 2.8.0: https://pypi.org/project/pytest-cov\n", "\n", "Normally, you don’t need to install these dependencies manually. They will be installed automatically when you follow the instructions below.\n", "\n", "\n", "## Installation with Anaconda or Miniconda:\n", "\n", "1. To install selector using the conda package management system, install [miniconda](https://conda.io/miniconda.html) or [anaconda](https://www.anaconda.com/download) first, and then:\n", "\n", "```\n", "# Activate your main conda environment if it is not loaded in your .bashrc.\n", "# E.g. run the following if you have miniconda installed in e.g. ~/miniconda3\n", "source ~/miniconda3/bin/activate\n", "\n", "# Create a horton3 conda environment. (optional, recommended)\n", "conda create -n horton3\n", "source activate horton3\n", "\n", "# Install the stable release.\n", "conda install -c theochem qc-selector\n", "\n", "# Unstable releases\n", "# (Only do this if you understand the implications.)\n", "# Install the testing release. (beta)\n", "conda install -c theochem/label/test qc-selector\n", "# Install the development release. (alpha)\n", "conda install -c theochem/label/dev qc-selector\n", "```\n", "\n", "Please note, it is also possible to install use [`mamba`](https://mamba.readthedocs.io/en/latest/#) instead of `conda` for faster Python package environment management.\n", "\n", "## Installation with `pip`\n", "\n", "1. You can work in a [virtual environment](https://docs.python.org/3/tutorial/venv.html):\n", "\n", "```\n", "# Create a virtual environment in ~/horton3\n", "# Feel free to change the path.\n", "python3 -m venv ~/horton3\n", "\n", "# Activate the virtual environemnt.\n", "source ~/horton3/bin/activate\n", "\n", "# Install the stable release in the venv horton3.\n", "pip3 install qc-selector\n", "# alternative: python3 -m pip install qc-selector\n", "\n", "# For developers, install a pre-release (alpha or beta).\n", "# (Only do this if you understand the implications.)\n", "pip3 install --pre qc-selector\n", "# alternative: python3 -m pip install --pre qc-selector\n", "```\n", "\n", "\n", "2. You can install into your `{$HOME}` directory without creating a virtual environment\n", "\n", "```\n", "# Install the stable release in your home directory.\n", "pip3 install qc-selector --user\n", "# alternative: python3 -m pip install qc-selector --user\n", "\n", "# For developers, install a pre-release (alpha or beta).\n", "# (Only do this if you understand the implications.)\n", "pip3 install --pre qc-selector --user\n", "# alternative: python3 -m pip install --pre qc-selector --user\n", "```\n", "\n", "This is by far the simplest method, ideal to get started, but you have only one home directory. If the installation breaks due to some experimentation, it is harder to make a clean start in comparison to the other options.\n", " \n", "In case the `pip3` executable is not found, pip may be installed in a directory which is not included in your `${PATH}` variable. This seems to be a common issue on macOS. A simple workaround is to replace `pip3` by `python3 -m pip`.\n", "\n", "In case Python and your operating system are up to date, you may also use `pip` instead of `pip3` or `python` instead of `python3`. The `3` is only used to avoid potential confusion with Python 2. Note that the `3` is only present in names of executables, not names of \n", "Python modules.\n", "\n", "## Latest git revision\n", "\n", "This section shows how one can install the latest revision of `selector` from the git repository. This kind of installation comes with some risks (sudden API changes, bugs, …) and so be prepared to accept them when using the following installation instructions.\n", "\n", "There are two installation methods:\n", "\n", "1. **Quick and dirty.** Of this method, there are four variants, depending on the correctness of your `PATH` variable and the presence of a virtual or conda environment. These different scenarios are explained in more detail in the previous section.\n", "```\n", "# with env, correct PATH\n", "pip install git+https://github.com/theochem/Selector.git\n", "# with env, broken PATH\n", "python -m pip install git+https://github.com/theochem/Selector.git\n", "# without env, correct PATH\n", "pip install git+https://github.com/theochem/Selector.git --user\n", "# without env, broken PATH\n", "python -m pip install git+https://github.com/theochem/Selector.git --user\n", "```\n", "\n", "2. **Slow and Smart.** In addition to the four variations in the quick and dirty method, the slow and smart can be used with `pip` or just with `setup.py`. You also have the options to use SSH or HTTPS protocols to clone the git repository. Pick whichever works best for you.\n", "```\n", "# A) Clone git repo with https OR ssh:\n", "# The second one only works if you have ssh set up for Github\n", "# A1) https\n", "git clone https://github.com/theochem/Selector.git\n", "# A2) ssh\n", "git clone git@github.com:theochem/Selector.git\n", "# B) Optionally write the version string\n", "pip install roberto # or any of the three other ways of running pip, see above.\n", "rob write-version\n", "# C) Actual install, 6 different methods.\n", "# C1) setup.py, with env\n", "python setup.py install\n", "# C2) pip, with env, correct PATH\n", "pip install .\n", "# C3) pip, with env, broken PATH\n", "python -m pip install .\n", "# C4) setup.py, without env\n", "python setup.py install --user\n", "# C5) pip, without env, correct PATH\n", "pip install . --user\n", "# C6) pip, without env, broken PATH\n", "python -m pip install . --user\n", "```\n", "\n", "\n", "## Testing\n", "\n", "The tests are automatically run when we build packages with conda, but you may try them again on your own machine after installation.\n", "\n", "With Ana- or Miniconda:\n", "```\n", "# Install pytest in your conda env.\n", "conda install pytest pytest-xdist\n", "# Then run the tests.\n", "pytest --pyargs selector -n auto\n", "```\n", "\n", "With Pip:\n", "```\n", "# Install pytest in your conda env ...\n", "pip install pytest pytest-xdist\n", "# .. and refresh the virtual environment.\n", "# This is a venv quirk. Without it, pytest may not find IOData.\n", "deactivate && source ~/selector/activate\n", "\n", "# Alternatively, install pytest in your home directory.\n", "pip install pytest pytest-xdist --user\n", "\n", "# Finally, run the tests.\n", "pytest --pyargs selector -n auto\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "b52d35f6-a533-440f-b053-42d9bfbb99db", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.7" } }, "nbformat": 4, "nbformat_minor": 5 }