1. Installing PyPop¶
1.1. Installation (end user)¶
TBA. For the end-user, we are currently working on making PyPop
installable via pip
from downloadable packages (that will include
pre-compiled binary extensions, to avoid the need to download
development tools). Eventually it will be available on
PyPi. However, for the time being, you will need
to follow the developer installation instructions, below.
1.2. Installation (developer)¶
There are four main steps to the developer installation:
install a build environment
clone the repository
build
run tests
For most casual users and developers, we recommend using the miniconda approach described below.
1.2.1. Install the build environment¶
To install the build environment, you should choose either conda
or
system packages. Once you have chosen and installed the build
environment, you should follow the instructions related to the option
you chose here in all subsequent steps.
1.2.1.1. Install build environment via miniconda (recommended)¶
Visit https://docs.conda.io/en/latest/miniconda.html to download the miniconda installer for your platform, and follow the instructions to install.
In principle, the rest of the PyPop miniconda installation process should work on any platform that is supported by miniconda, but only Linux and MacOS have been tested in standalone mode, at this time.
Once miniconda is installed, create a new conda environment, using the following commands:
conda create -n pypop3 gsl swig python=3
This will download and create a self-contained build-environment that uses of Python to the system-installed one, along with other requirements. You will need to use this this environment for the build, installation and running of PyPop. The conda environment name, above,
pypop3
, can be replaced with your own name.When installing on MacOS, before installing
conda
, you should first to ensure that the Apple Command Line Developer Tools (XCode) are installed, so you have the compiler (clang
, the drop-in replacement forgcc
),git
etc.conda
is unable to include the full development environment forclang
as a conda package for legal reasons.Activate the environment, and set environments variables needed for compilation:
conda activate pypop3 conda env config vars set CPATH=${CONDA_PREFIX}/include:${CPATH} conda env config vars set LIBRARY_PATH=${CONDA_PREFIX}/lib:${LIBRARY_PATH} conda env config vars set LD_LIBRARY_PATH=${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH}
To ensure that the environment variables are saved, reactivate the environment:
conda activate pypop3
Skip ahead to Clone the repository
1.2.1.2. Install build environment via system packages (advanced)¶
1.2.1.2.1. Unix/Linux:¶
Ensure Python 3 version of
pip
is installed:python3 -m ensurepip --user --no-default-pip
Note the use of the
python3
- you may find this to be necessary on systems which parallel-install both Python 2 and 3, which is typically the case. On newer systems you may find thatpython
andpip
are, by default, the Python 3 version of those tools.Install packages system-wide:
Fedora/Centos/RHEL
sudo dnf install git swig gsl-devel python3-devel
Ubuntu
sudo apt install git swig libgsl-dev python-setuptools
1.2.1.2.2. MacOS X¶
Install developer command-line tools: https://developer.apple.com/downloads/ (includes
git
,gcc
)Visit http://macports.org and follow the instructions there to install the latest version of MacPorts for your version of MacOS X.
Set environment variables to use macports version of Python and other packages, packages add the following to
~/.bash_profile
export PATH=/opt/local/bin:$PATH export LIBRARY_PATH=/opt/local/lib/:$LIBRARY_PATH export CPATH=/opt/local/include:$CPATH
Rerun your bash shell login in order to make these new exports active in your environment. At the command line type:
exec bash -login
Install dependencies via MacPorts and set Python version to use (FIXME: currently untested!)
sudo port install swig-python gsl py39-numpy py39-lxml py39-setuptools py39-pip py39-pytest sudo port select --set python python39 sudo port select --set pip pip39
Check that the MacPorts version of Python is active by typing:
which python
, if it is working correctly you should see/opt/local/bin/python
.
1.2.1.3. Windows¶
(Currently untested in standalone-mode)
1.2.2. Clone the repository¶
git clone https://github.com/alexlancaster/pypop.git
cd pypop
1.2.3. Build PyPop¶
You should choose either of the following two approaches. Don’t try to mix-and-match the two. The build-and-install approach is recommended for end-users, or you if don’t plan to make any modifications to the code locally.
1.2.3.1. Build-and-install (recommended for end-users)¶
Once you have setup your environment and cloned the repo, you can use
the following one-liner to examine the setup.py
and pull all the
required dependencies from pypi.org
and build and install the
package.
Note that if you use this method and install the package, it will be available to run anywhere on your system, by running
pypop.py
.
If you use this installation method, changes you make to the code, locally, or via subsequent ``git pull`` requests will not be available in the installed version until you repeat the ``pip install`` command.
if you installed the conda development environment, use:
pip install .[test]
(the
[test]
keyword is included to make sure that any package requirements for the test suite are installed as well).if you installed a system-wide environment, the process is slightly different, because we install into the user’s
$HOME/.local
rather than the conda environment:pip install --user .[test]
PyPop is ready-to-use, skip to Run the test suite.
if you later decide you want to switch to using the developer approach, below, follow the Uninstalling PyPop and cleaning up before starting.
1.2.3.2. Build-and-run-from-checkout (recommended for developers)¶
First manually install the dependencies via
pip
, note that if you are running on Python <= 3.8, you will need to also addimportlib-resources
to the list of packages, below.conda
pip install numpy lxml psutil pytest
system-wide
pip install --user numpy lxml psutil pytest
Run the build
./setup.py build
You will run PyPop, directly out of the
src/bin
subdirectory (e.g../src/bin/pypop.py
).
1.2.4. Run the test suite¶
You should first check that the build worked, by running the test suite,
via pytest
:
pytest tests
If you run into errors, please first carefully repeat and/or check your
installation steps above. If you still get errors, file a bug (as per
Support, below), and include the output of pytest
run in verbose
mode and capturing the output
pytest -s -v tests
1.2.5. Uninstalling PyPop and cleaning up¶
If you installed using the end-user approach in Build-and-install (recommended for end-users), above, you can remove the installed version:
conda:
pip uninstall pypop
system-wide:
pip uninstall --user pypop
To clean-up any compiled files and force a recompilation from scratch,
run the clean
command:
./setup clean --all
1.3. Examples¶
These are examples of how to use PyPop. Specify the --help
option to
see an explanation of the options available.
1.3.1. Run a minimal dataset:¶
pypop.py -c tests/data/minimal.ini tests/data/USAFEL-UchiTelle-small.pop
replace
pypop.py
, by./src/bin/pypop.py
if you installed using Build-and-run-from-checkout (recommended for developers), i.e running locally from within the uninstalled checkout of the repository
This will generate the following two files, an XML output file and a plain text version:
USAFEL-UchiTelle-small-out.xml
USAFEL-UchiTelle-small-out.txt
1.4. Support¶
Please submit any bug reports,feature requests or questions, via our GitHub issue tracker:
Please do not report via private email to developers.
1.4.1. Bug reporting¶
When reporting bugs, especially during installation, please run the following and include the output:
echo $CPATH
echo $LIBRARY_PATH
echo $PATH
which python
If you are running on MacOS, and you used the MacPorts installation method, please also run and include the output of:
port installed
1.4.2. Development¶
The development of the code for PyPop is via our GitHub project: