epyc: Python computational experiment management
================================================

.. image:: https://badge.fury.io/py/epyc.svg
    :target: https://pypi.org/project/epyc/

.. image:: https://readthedocs.org/projects/epyc/badge/?version=latest
    :target: https://epyc.readthedocs.io/en/latest/index.html

.. image:: https://github.com/simoninireland/epyc/actions/workflows/ci.yaml/badge.svg
    :target: https://github.com/simoninireland/epyc/actions

.. image:: https://zenodo.org/badge/63255319.svg
   :target: https://zenodo.org/badge/latestdoi/63255319

.. image:: https://joss.theoj.org/papers/10.21105/joss.03764/status.svg
   :target: https://doi.org/10.21105/joss.03764

.. image:: https://www.gnu.org/graphics/gplv3-88x31.png
    :target: https://www.gnu.org/licenses/gpl-3.0.en.html

Overview
--------

``epyc`` is a Python module for controlling a long-running series of
computational experiments, as is often found when writing simulations
of complex networks and other such domains. There is often a need to
perform a computation across a multi-dimensional parameter space,
varying the parameters, performing and aggregating multiple
repetitions, and wrangling results for analysis and
presentation. Often the experiments being performed are on such a
scale as to require the use of a computing cluster to perform multiple
experiments simultaneously.

Managing all these tasks is complicated, so ``epyc`` tries to automate
it. It provides a way to define a "laboratory" performing a collection
of "experiments" whose parameters and results are collected togethr into "result
sets" and recorded in a "lab
notebook" for later retrieval. Laboratories can be sequential (for a
single machine) or parallel (to use a multicore or cluster of
machines); lab notebooks can be persistent to allow experiments to be
fired-off and their results retrieved later -- handy if you use a
laptop. Notebooks store all the data and metadata in a portable format
to improve the reproducibility of computational experiments.

``epyc`` also includes a small number of "experiment combinators" that
separate the logic of a single experiment from the logic of performing
multiple repetitions and other structuring tasks. This means that
any experiment can be repeated and statistically summarised, for
example.


Installation
------------

``epyc`` works with Python 3.6 and above, and with PyPy3. You can install
it directly from PyPi using ``pip``:

::

   pip install epyc

The master distribution of ``epyc`` is hosted on GitHub. To obtain a
copy, just clone the repo:

::

    git clone git@github.com:simoninireland/epyc.git
    cd epyc
    pip install .


Examples
--------

See `the examples directory <https://github.com/simoninireland/epyc/tree/master/doc/examples>`_ for code examples.


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

API documentation for ``epyc`` can be found on `ReadTheDocs <https://epyc.readthedocs.io/en/latest/>`_.
You can also read a Jupyter notebook describing several ``epyc`` use
cases online `here <https://github.com/simoninireland/epyc/blob/master/doc/epyc.ipynb>`_.


Author and license
------------------

Copyright (c) 2016-2022, Simon Dobson <simoninireland@gmail.com>

Licensed under the `GNU General Public Licence v3 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_.
