Metadata-Version: 2.1
Name: layg
Version: 0.0.1.dev0
Summary: Learn-as-you-go emulator with error estimation
Home-page: https://github.com/auckland-cosmo/LearnAsYouGoEmulator
Author: Nathan Musoke, Layne Price
Author-email: n.musoke@aucland.ac.nz, layne.c.price@gmail.com
License: Apache Licence (2.0)
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: numpydoc
Requires-Dist: torch
Requires-Dist: scipy
Requires-Dist: sphinx
Requires-Dist: sphinx-rtd-theme
Requires-Dist: emcee (<3,>=2)
Requires-Dist: gif (==1.0.3)

LearnAsYouGoEmulator
====================

Python implementation of the Learn As You Go algorithm published in http://arxiv.org/abs/arXiv:1506.01079.
TODO: reference ICLR paper

.. image:: https://github.com/auckland-cosmo/LearnAsYouGoEmulator/workflows/pytest/badge.svg

.. image:: https://github.com/auckland-cosmo/LearnAsYouGoEmulator/workflows/doc/badge.svg

.. image:: https://github.com/auckland-cosmo/LearnAsYouGoEmulator/workflows/lints/badge.svg



The package defines a decorator that can be applied to functions to convert them to functions which learn outputs as they go and emulate the true function when expected errors are low.
Two emulators are included: the `k`-nearest neighbors Monte Carlo accelerator described there, and a simple neural network.

The basic usage of the emulator code is something like this::

    @emulate(CholeskyNnEmulator)
    def loglike(x):
        """
        Your complex and expensive function here
        """
        return -np.dot(x,x)

This decorates the function ``loglike`` so that it is an instance of the ``Learner`` class.
It can be used similarly to the original function: just call it as ``loglike(x)``.
The ``__call__(x)`` method hides some extra complexity: it uses the Learn As You Go emulation scheme.

It learns both the output of ``loglike(x)`` and the difference between the emulator and the true value of ``loglike(x)`` so that we can make a prediction for the error residuals.
We then put a cutoff on the amount of error that one will allow for any local evaluation of the target function.
Any call to the emulator that has a too-large error will be discarded and the actual function ``loglike(x)`` defined above will be evaluated instead.

The logic for generating training sets and returning a value from either the true function or the emulated function are contained in the ``Learner`` class.
The ``Learner`` class relies on an emulator class to do the emulation.

You can define you own emulator.
Define a class that inherits from ``BaseEmulator`` and define two methods on it: ``set_emul_func(self, x_train: np.ndarray, y_train: np.ndarray)`` and ``set_emul_error_func(self, x_train: np.ndarray, y_train: np.ndarray)`` that set functions for, respectively, ``self.emul_func`` and ``self.emul_error_func``.
An example of this definition is provided.


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

There are a small number of python dependencies.
If you use anaconda you can create an appropriate environment and install to your python path by running ::

    conda env create --file environment.yml
    pip install -e .

from this directory.

The ``pytorch`` dependency is only needed if you are using the neural network emulator or running the associated tests.


