Installation

Using pip

HCIPy is available on PyPI, so installation can be as easy as:

pip install hcipy --upgrade

It is also possible to install the latest development version from Github, by:

git clone https://github.com/ehpor/hcipy
cd hcipy
pip install -e .

The -e flag tells pip to install HCIPy in editable mode, ie. edits to the source files in the hcipy directory will change the library. This allows for easy updates by simply pulling the git repository:

git pull
python setup.py egg_info

You can check if HCIPy is installed correctly by importing it in Python:

>>> import hcipy
>>> print(hcipy.__version__)

If you want to install the latest development verison, but do not intend to receive continuous updates (not advised), you can also install in non-editable mode:

git clone https://github.com/ehpor/hcipy
pip install ./hcipy
rm -rf hcipy

Dependencies

All Python dependencies of HCIPy will be installed automatically by the installer. These include:

  • numpy (for all numerical calculations)

  • scipy (for advanced linear algebra)

  • matplotlib (for visualisations)

  • Pillow (for gif file output)

  • pyyaml (for the configuration file)

  • astropy (for fits file reading and writing)

  • imageio (for image writing)

  • xxhash (for efficiently hashing Grids)

  • numexpr (for speedup of lengthy numerical operations)

  • asdf (for reading and writing of HCIPy objects)

However, there is one dependency that pip does not automatically install. This is FFMpeg, which is used for writing out animations to video files. Installation of FFMpeg is not necessary, unless you want to use the FFMpegWriter class in HCIPy.

Most Linux systems should have this preinstalled, but on MacOS and Windows, you need to install it yourself, either from their website or other sources. You also need to make sure that the ffmpeg binary can be found by HCIPy. You can do this by adding the ffmpeg/bin directory to the PATH environment variable, if this is not already done by the FFMpeg installer.

Running the test suite

For running the test suite, you’ll need to install the test dependencies as well:

pip install -e ".[dev]"

or

pip intall hcipy[dev]

depending on the way you originally installed HCIPy. You can then run the full test suite by running the following in the HCIPy directory.

pytest ./tests

This should execute all simple tests in around 3-5 minutes, depending on your computer. It skips the longer tests that perform more extensive verification checks. All tests, including slow ones, can be run as well

pytest ./tests --runslow

This should take about 10-20 minutes, depending on your computer.

A single submodule can be tested as well, for example:

pytest ./tests/test_atmosphere.py

Building the documentation

A pre-built version of the documentation is always available online, in fact, you’re most likely reading it from that website right now.

The HCIPy documentation uses Sphinx to build an HTML website containing the documentation. If you want to build a local copy, you’ll first have to install the documentation dependencies first:

pip install -e ".[doc]"

Building the documentation also requires FFMpeg to be installed. You can now build the documentation:

cd doc
make html

This will execute all tutorials, and compile the documentation. The first time you build the documentation, it may take 5-10 minutes, depending on your computer. Afterwards, a refresh should take about a minute. The final HTML documentation is then available in doc/_build/html.

The documentation can be rebuilt from scratch by cleaning it first.

make clean
make html