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:

  1. install a build environment

  2. clone the repository

  3. build

  4. 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.2. Install build environment via system packages (advanced)

1.2.1.2.1. Unix/Linux:
  1. 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 that python and pip are, by default, the Python 3 version of those tools.

  2. Install packages system-wide:

    1. Fedora/Centos/RHEL

      sudo dnf install git swig gsl-devel python3-devel
      
    2. Ubuntu

      sudo apt install git swig libgsl-dev python-setuptools
      
1.2.1.2.2. MacOS X
  1. Install developer command-line tools: https://developer.apple.com/downloads/ (includes git, gcc)

  2. Visit http://macports.org and follow the instructions there to install the latest version of MacPorts for your version of MacOS X.

  3. 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
    
  4. Rerun your bash shell login in order to make these new exports active in your environment. At the command line type:

    exec bash -login
    
  5. 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
    
  6. 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.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:

  1. conda:

    pip uninstall pypop
    
  2. 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: