Extended installation notes¶
05/11/20
ePSproc is available on PyPi, which is the simplest means of installing the latest stable release. For testing and/or development updates, use the Github repo source. Details for these, and other options, are given below.
General notes¶
Requirements/prerequisites¶
ePSproc has been tested mainly with Python = 3.7, and various package versions to date. Currently (v1.3.0, 12th August 2021), up-to-date packages are working apart from Xarray (>=0.12, <=0.15.0) and Seaborn (==0.9.0) - this will be fixed in future. (Note that packages in requirements.txt are currently unversioned apart from these, see notes below for more details.)
The main requirements are Xarray (>=0.12, <=0.15.0), and Moble’s spherical functions (quaternion based) . See the individual package docs for full details.
The usual SciPy stack is also used (numpy, matplotlib etc.) - see requirements.txt file for full list - plus some optional packages for additional functionality. In the current release (v1.3.0), package versions are not specified in the main requirements.txt file, but specific versioned build environments are also available .
Virtual environments¶
In all cases, you might want to use a virtual environment, e.g.:
With Anaconda
conda create --name epsProc python=3.7
conda activate epsProc
With venv (see https://docs.python.org/3/library/venv.html)
python -m venv /path/to/new/virtual/environment
From PyPi (releases)¶
Pip only¶
The simplest method, this will pull the latest packaged release, and dependencies. (There is currently no Conda packaged version.)
pip install ePSproc
Note that some versions may not pull dependencies (not set in setup.py
in some cases, should be OK for versions ePSproc>=1.3.0-dev), these can be additionally installed from the requirements.txt file:
pip install -r requirements.txt
Or manually… adding a couple of core packages should cover most dependencies:
pip install xarray==0.15.0
pip install git+git://github.com/moble/spherical_functions
Conda¶
Either as pip case above, plus Conda for the dependencies (as below); or from source - see source options for more details.
conda install -c conda-forge xarray=0.15.0
conda install -c conda-forge spherical_functions
From source + local pip install¶
For up-to-date version and alternative branches, use the Github repo.
Using pip¶
git clone https://github.com/phockett/ePSproc.git
pip install -e epsproc
This should install all dependencies (for ePSproc>=1.3.0-dev), although spherical_functions
are currently giving issues with pip+PyPi (tested 12th August 2021), so may need to be installed separately from source with pip install git+git://github.com/moble/spherical_functions
(this is Moble’s spherical functions library, but will be updated to the newer spherical package in future).
To install with specific dependencies, just run pip install -e epsproc -r ePSproc/requirements.txt
From setup.py
git clone https://github.com/phockett/ePSproc.git
cd ePSproc
python setup.py install
Note this currently installs without dependencies for ePSproc<1.3.0-dev.
Notes
- For a single branch use
git clone --single-branch --branch <branchname> https://github.com/phockett/ePSproc.git
- The repo can be passed directly to pip, e.g.
pip install git+https://github.com/phockett/ePSproc.git
, see notes in the pip docs. - Note that
pip -e
is for ‘editable’, and requires the source dir to remain, but the installation is also editable, see notes here. Drop the-e
for a normal installation. - As of v1.3.0 (12/08/21),
setup.py
contains a rough pkg requirements list, identical to the baserequirements.txt
file, but this may change in future (see discussion here.)
Assuming a fresh environment, you might also need to install some requirements manually:
With pip (this is for Moble’s spherical functions library):
pip install git+git://github.com/moble/quaternion
pip install git+git://github.com/moble/spherical_functions
Using Conda¶
git clone https://github.com/phockett/ePSproc.git
conda create --name ePSproc --file ePSproc/requirements.txt --channel default --channel conda-forge
pip install -e epsproc
However… this may fail if any of the packages are missing or give issues. A quick fix is to iterate over lines
conda create --name epsProc python=3.7
conda activate epsProc
while read requirement; do conda install --yes $requirement --channel default --channel conda-forge; done < ePSproc/requirements.txt
pip install -e epsproc
Note that the python version is optional here, and the latest version will be pulled on install if not specified.
With specific (working) package versions: select from the various *.yml files under /notes/envs. These correspond to tested working environments - see notes below for more details.
Other options¶
A few other options…
- Some development envs are available as Conda .yml files in
/notes/envs
, these can be used to clone a known-working env.- E.g.
conda env create -f environment_epsdev_v1.3.0_040821_no-builds.yml
for the current v1.3.0 environment. - Note that these envs may included extra packages and/or platform specific packages.
- Note that the envs are currently a bit of a mess, but will be cleared up soon.
- See the Conda docs for more details on .yml env files
- E.g.
- Similarly, there are some alternative Pip requirement.txt files in
/notes/envs
, corresponding to some specific development envs.- E.g.
pip install -r requirements_epsdev_v1.3.0_040821.txt
for the current v1.3.0 environment. - Note that these envs may included extra packages and/or platform specific packages.
- Note that the envs are currently a bit of a mess, but will be cleared up soon.
- E.g.
- If using nb_conda_kernels:
conda install ipykernel
Docker¶
A basic Docker build is available in /docker, see the Docker notes for more details.