anyHR 1.0.1
Library implementing hit-and-run methods for sampling open bounded sets.
License: BSD
Requires Python: >=3.5

# anyHR
A collection of *hit-and-run Markov Chain Monte Carlo* algorithms for sampling of n-dimensional sets defined by arbitrary inequality constraints.


## Introduction
This tool implements some variants of the *hit and run* or *mixing* algorithms. 

Let **S** be an open bounded set in n dimensions defined by inequality constraints of the form 
f(x<sub>1</sub>,..., x<sub>n</sub>) < g(x<sub>1</sub>,..., x<sub>n</sub>), where f and g are arbitrary functions.
Let all parameters also have parameter ranges defined as intervals, so **S** is a subset of a hyperrectangle.

(As an example, one could impose ``x + y < 1`` in the two dimensional plane, with x in (0,1) and y in (0,1)).

Hit-and-run algorithms can be used to get a sample uniformly at random inside of this set **S**.

**anyHR** parses the parameters and their respective constraints and returns a number of samples that satisfy this spec, 
while being distributed uniformly on the set of allowed values. 
For more information on mixing algorithms see

## Installation
It is necessary to have a working installation of Python 3,
[pip](https://pip.pypa.io/en/stable/installing/) and [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)  for the following installation process.
Open the target installation directory in a terminal and type
```bash
pip install anyHR
```

## Use
A minimal running example for the above specification can be sampled with the following code:

````python
# Import modules
import numpy as np
import matplotlib.pyplot as plt
from anyHR.constraint.Constraint import Constraints
from anyHR.hit_and_run.hit_and_run import HitAndRun


# Define variables to use
var_names = ['x', 'y']

# Define the set of constraint
c = Constraints(var_names)
c.add_constraint('x+y < 1')

# Define the bounding hyperrectangle
x_bound = [0, 1]
y_bound = [0, 1]
bounds = [x_bound, y_bound]

# build hr object
hr = HitAndRun(constraint=c, bounding_box=bounds)

# generate samples
samples = []
total_rejections = 0
nb_samples = 100
mixing = 10
for i in range(nb_samples * mixing):
    sample, rejections = hr.next_sample()

    # do some mixing in between samples
    if i % mixing == 0:
        samples.append(sample)

xs = [sample[0] for sample in samples]
ys = [sample[1] for sample in samples]

plt.scatter(xs,ys)
plt.show()
````

## References
For more information about mixing algorithms, see:

- Smith, R. L. (1984). Efficient Monte Carlo procedures for generating points uniformly distributed over bounded regions. Operations Research, 32(6), 1296-1308.

- Kiatsupaibul, S., Smith, R. L., & Zabinsky, Z. B. (2011). An analysis of a variation of hit-and-run for uniform sampling from general regions. ACM Transactions on Modeling and Computer Simulation (TOMACS), 21(3), 1-11.

- Neal, R. M. (2003). Slice sampling. The annals of statistics, 31(3), 705-767.


We also thank Abraham Lee for his implementation of the PSO algorithms which is used here.
See https://github.com/tisimst/pyswarm for more information.