Dionysus 2
==========

Dionysus is a computational topology package focused on
persistent homology. It is written in C++, with Python bindings.
The second version (`previous version <http://mrzv.org/software/dionysus/>`_)
is re-written from scratch, which helps it accomplish a few goals:

  * `Modified BSD license <https://github.com/mrzv/dionysus/blob/master/LICENSE.txt>`_ (because GPL causes too many problems in academic software).
  * No dependency on Boost.Python; Dionysus 2 uses (and includes) `PyBind11 <https://github.com/pybind/pybind11>`_ instead, which greatly simplifies installation.
  * Cleaner, more consistent internal design (for example, all algorithms support arbitrary fields).
  * Some new algorithms, e.g., `omni-field persistence <http://mrzv.org/software/dionysus2/tutorial/omni-field.html#omni-field>`_ and Wasserstein and bottleneck `distance computation <http://mrzv.org/software/dionysus2/tutorial/basics.html#diagram-distances>`_ from `Hera <https://bitbucket.org/grey_narn/hera>`_.
  * A few `plotting <http://mrzv.org/software/dionysus2/tutorial/plotting.html#plotting>`_ routines, based on `Matplotlib <https://matplotlib.org/>`_.
  * Better integration with `NumPy <http://www.numpy.org/>`_.

Features that haven't (yet) made it over from `Dionysus 1 <http://mrzv.org/software/dionysus>`_ include vineyards.
Alpha shape filtrations are available via `DioDe <https://github.com/mrzv/diode>`_.

**Dependencies:**
  * `Boost <http://www.boost.org/>`_, although Dionysus 2 doesn't link any of its libraries, so it's considerably easier to build the project.
  * (Optional) `SciPy <https://www.scipy.org/>`_ for the LSQR routine used in `circular coordinates <http://mrzv.org/software/dionysus2/tutorial/cohomology.html#circular>`_.
  * (Optional) `Maplotlib <https://matplotlib.org/>`_ for plotting.

**Requirements:**
  * Boost needs to be at least version 1.55.
  * If you are using GCC, the oldest supported version is 5.4.

**Contact:**
  * please use the `dionysus mailing list <https://groups.io/g/dionysus/>`_
    for all questions and discussion related to the library;
  * GitHub's `issue tracker <https://github.com/mrzv/dionysus/issues>`_
    is a central location for bug reports and feature requests.

Get, Build, Install
-------------------

The simplest way to install Dionysus, as a Python package, is from `PyPI <https://pypi.org/project/dionysus/>`_:

.. parsed-literal::

    pip install --verbose dionysus

Pass ``--upgrade`` to ``pip``, if you have already installed some version of Dionysus.

Alternatively, you can install it directly from the development repository (this gives you the latest version):

.. parsed-literal::

    pip install --verbose `git+https://github.com/mrzv/dionysus.git <https://github.com/mrzv/dionysus.git>`_

Alternatively, you can clone and build everything by hand.
To get Dionysus 2, either clone its `repository <https://github.com/mrzv/dionysus>`_:

.. parsed-literal::

    git clone `<https://github.com/mrzv/dionysus.git>`_

or download it as a `Zip archive <https://github.com/mrzv/dionysus/archive/master.zip>`_.

To build the project::

    mkdir build
    cd build
    cmake ..
    make

To use the Python bindings, either launch Python from ``.../build/bindings/python`` or add this directory to your ``PYTHONPATH`` variable, by adding::

    export PYTHONPATH=.../build/bindings/python:$PYTHONPATH

to your ``~/.bashrc`` or ``~/.zshrc``.

Documentation
-------------

Documentation for Dionysus can be found `here <http://mrzv.org/software/dionysus2/>`_.
