Metadata-Version: 2.1
Name: anyHR
Version: 1.0.0
Summary: Library implementing hit-and-run methods for sampling open bounded sets.
Home-page: https://github.com/figlerg/anyHR
Author: Felix Gigler, Dejan Nickovic, Cristinel Mateis, Nicolas Basset, Thao Dang
Author-email: felix.gigler.fl@ait.ac.at, dejan.nickovic@ait.ac.at
License: BSD
Platform: UNKNOWN
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: z3-solver
Requires-Dist: antlr4-python3-runtime
Requires-Dist: numpy

# 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.

