Installation

PIEFACE is written in pure Python. While this makes it highly transferrable between operating systems, it does require a number of other Python packages to operate.

Installing

Detailed installation instructions specific to different operating systems can be found under Windows, MAC OS X and Linux derivatives.

PIEFACE is registered on PyPI, therefore if you already have a working Python distribution, installation may be as simple as:

pip install PIEFACE

or alternatively by manually installing from sources.

Note

The PyPI version is currently exhibiting issues resolving dependencies correctly with pip. See known issues for details.

In reality, installation can sometimes be operating-system specific.

Updates

From version 1.1.0, PIEFACE now includes automatic update checking. From EllipsoidGUI go to Help ‣ Check for Updates and follow the dialogue boxes. From CIFellipsoid, type CIFellipsoid -V and follow the resulting link.

Windows

Due to problems with ensuring correct dependencies, the recommended method for obtaining PIEFACE for Windows is to download the most recent self-contained installer WinSetup_PIEFACE_1.1.0.0.exe and run it, following the on-screen prompts. This will also (optionally) add PIEFACE shortcuts to the Start Menu and Windows Desktop, as well as making the two main scripts accessible from the Windows Command Line (cmd).

The installer comes packaged with a minimal Python runtime environment, therefore this installer will work without (and not interfere with an existing) Python installation.

MAC OS X

Unfortunately PIEFACE is not currently available as a pre-built MAC distribution, as the author does not have access to that operating system!

If Python is available from the terminal, installing may be as simple as:

pip install PIEFACE

or installing from sources. If this does not work, see Known Issues.

Linux derivatives

Unix-like operating systems generally come with a version of Python included. In this case:

pip install PIEFACE

should work, but may require some manual installation of dependencies (see Known Issues).

Installation from Sources

Stable Build

PIEFACE can also be installed from the source distribution. The current release is available from the PIEFACE repository. Once downloaded, this file should be unpacked into the desired directory (tar -xzf pieface_1.0.0.tar.gz) before following the manual install instructions.

Manual Install

Once the source code has been downloaded, it is then necessary to install it using Python from within the main PIEFACE directory:

python setup.py install

This should collect all dependencies, and compile them if necessary. If this fails, it may be necessary to install dependencies manually first, before running python setup.py install again.

Development Version

The latest development version of PIEFACE can be obtained from the PIEFACE repository using git:

git clone https://github.com/jcumby/PIEFACE .

To update the repository at a later date, use:

git pull

In both cases, you should then change into the resulting directory, and follow the instruction for manual install.

Requirements

Known Issues

When installing using pip, dependencies on PyCifRW and Matplotlib are not always resolved when using:

pip install PIEFACE

In this case, there are a number of possible solutions:

  • Update pip (this can sometimes solve the problem)

  • Install the dependencies manually first:

    pip install PyCIFRW>=3.3
    pip install maplotlib>=1.4.3
    

followed by pip install PIEFACE

  • Manually download either the wheel (PIEFACE-X.X.X.whl) or compressed package (PIEFACE-X.X.X.zip or PIEFACE-X.X.X.tar.gz) from PyPI, and then install that:

    pip install PIEFACE-X.X.X.whl
    
  • Install from sources (may require compilation of other packages)

Testing

The package contains some basic unit tests, which can be run following installation either from source or using pip. Tests can be run from within the main PIEFACE directory with the command:

python setup.py test

or alternatively from within a python prompt:

import pieface
pieface.self_test()

All tests should pass without exceptions - if not, please send me a bug report.

Run It!

Once correctly installed, the easiest way to access PIEFACE is using either EllipsoidGUI or CIFellipsoid (see Tutorials).