<commit_before>Boltzmann Brain [![Build
Status](https://travis-ci.org/maciej-bendkowski/boltzmann-brain.svg?branch=master)](https://travis-ci.org/maciej-bendkowski/boltzmann-brain)
[![Hackage](https://img.shields.io/badge/hackage-v1.6-blue.svg)](http://hackage.haskell.org/package/boltzmann-brain)
[![License](https://img.shields.io/badge/license-BSD--3-orange.svg)](https://tldrlegal.com/license/bsd-3-clause-license-(revised))
---------------

*Boltzmann Brain* is a [Haskell](https://www.haskell.org/) library and set of
standalone applications meant for random generation of combinatorial structures.
Using an **easy** and **intuitive** context-free text input representing a
combinatorial specification of rational or algebraic objects, *Boltzmann Brain*
allows its users to:

- **sample** random structures following the given input specification, and
- **compile** a self-contained, dedicated analytic sampler for **optimal sampling efficiency**.

Remarkably, using *Boltzmann Brain* it is possible to **control the outcome
distribution** of generated objects and, in particular, skew it to one needs.
You provide the target distribution, we handle the sampling process for you!

**If you can specify it, you can sample it!**

![Random tree](https://github.com/maciej-bendkowski/boltzmann-brain/blob/master/examples/images/tree-large.png)

1. [Overview](#overview)
2. [Sampler tuning](#sampler-tuning)
3. [Basic usage](#basic-usage)
4. [Advanced usage](#advanced-usage)
5. [Installation](#installation)
6. [References](#references)

### Citing Boltzmann Brain
If you use *Boltzmann Brain* or its components for published work,  we encourage you to cite the accompanying paper:

*<NAME>, <NAME>, <NAME>*

[Polynomial tuning of multiparametric combinatorial
samplers](https://epubs.siam.org/doi/10.1137/1.9781611975062.9)

### Overview

*Boltzmann Brain* (*bb* for short) is an open-source analytic sampler compiler.
Given a textual representation of the combinatorial system, *bb* constructs a
dedicated **analytic sampler**. The sampler itself is a self-contained, and
reusable [Haskell](https://www.haskell.org/) module which, by construction, is
**guaranteed** to sample random objects following the given, feasible target
distribution. Using state-of-the-art optimization techniques, *bb* compiles an
**efficient** sampler implementation which can be further modified, incorporated<commit_msg>Include full paper in README<commit_after>Boltzmann Brain [![Build
Status](https://travis-ci.org/maciej-bendkowski/boltzmann-brain.svg?branch=master)](https://travis-ci.org/maciej-bendkowski/boltzmann-brain)
[![Hackage](https://img.shields.io/badge/hackage-v1.6-blue.svg)](http://hackage.haskell.org/package/boltzmann-brain)
[![License](https://img.shields.io/badge/license-BSD--3-orange.svg)](https://tldrlegal.com/license/bsd-3-clause-license-(revised))
---------------

*Boltzmann Brain* is a [Haskell](https://www.haskell.org/) library and set of
standalone applications meant for random generation of combinatorial structures.
Using an **easy** and **intuitive** context-free text input representing a
combinatorial specification of rational or algebraic objects, *Boltzmann Brain*
allows its users to:

- **sample** random structures following the given input specification, and
- **compile** a self-contained, dedicated analytic sampler for **optimal sampling efficiency**.

Remarkably, using *Boltzmann Brain* it is possible to **control the outcome
distribution** of generated objects and, in particular, skew it to one needs.
You provide the target distribution, we handle the sampling process for you!

**If you can specify it, you can sample it!**

![Random tree](https://github.com/maciej-bendkowski/boltzmann-brain/blob/master/examples/images/tree-large.png)

1. [Overview](#overview)
2. [Sampler tuning](#sampler-tuning)
3. [Basic usage](#basic-usage)
4. [Advanced usage](#advanced-usage)
5. [Installation](#installation)
6. [References](#references)

### Citing Boltzmann Brain
If you use *Boltzmann Brain* or its components for published work,  we encourage you to
cite the accompanying papers:

*<NAME>, <NAME>, <NAME>*

- [Tuning as convex optimisation: a polynomial tuner for multi-parametric combinatorial samplers](https://www.cambridge.org/core/journals/combinatorics-probability-and-computing/article/abs/tuning-as-convex-optimisation-a-polynomial-tuner-for-multiparametric-combinatorial-samplers/2A79BF69E8CC80011E6AADF81BFC0291)

- [Polynomial tuning of multiparametric combinatorial samplers](https://epubs.siam.org/doi/10.1137/1.9781611975062.9)

### Overview

*Boltzmann Brain* (*bb* for short) is an open-source analytic sampler compiler.
Given a textual representation of the combinatorial system, *bb* constructs a
dedicated **analytic sampler**. The sampler itself is a self-contained, and
reusable [Haskell](https://www.haskell.org/) module which, by construction, is
**guaranteed** to sample random objects following the given, feasible target
distribution. Using state-of-the-art optimization techniques, *bb* compiles an
**efficient** sampler implementation which can be further modified, incorporated
{'fraction_non_alphanumeric': 0.12779614860922, 'fraction_numerical': 0.015561174868702588, 'mean_word_length': 5.57544757033248, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 19, 'lorem ipsum': 0, 'www.': 5, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '156408', 'n_tokens_mistral': 1683, 'n_tokens_neox': 1456, 'n_words': 464}