Descriptions of *informal interfaces*.

`explorer`

#### Description

`Pigeons.explorer`

— ConstantOrchestrate the `explore!()`

phase of Parallel Tempering. This is the part of the algorithm where each replica performs MCMC moves targeting its annealed distribution.

#### Contract

`log_potential`

#### Description

`Pigeons.log_potential`

— ConstantA `log_potential`

encodes a probability distribution, where only the un-normalized probability density function is known.

To make MyType conform to this informal interface, implement

`(log_potential::MyType)(x)`

which should return the log of the un-normalized density.

For example, we provide this behaviour for any distribution in Distributions.jl.

#### Examples of functions providing instances of this interface

`log_potentials`

#### Description

`Pigeons.log_potentials`

— ConstantAn encoding of a discrete set of probability distributions, where only the un-normalized probability density functions are known. Each distribution is allowed to have a different normalization constant.

For example, we provide this behaviour for any `Vector`

containing `log_potential`

's.

#### Contract

`pair_swapper`

#### Description

`Pigeons.pair_swapper`

— ConstantInforms `swap!()`

of how to perform a swap between a given pair of chains.

This is done in two steps:

- Use
`swap_stat()`

to extract sufficient statistics needed to make a swap decision. - Given these statistics for the two chains,
`swap_decision()`

then perform the swap.

The rationale for breaking this down into two steps is that in a distributed swap context, `swap!()`

will take care of transmitting the sufficient statistics over the network if necessary.

The function `record_swap_stats!()`

is used to record information about swapping, in particular mean swap acceptance probabilities.

A default implementation of all of `pair_swapper`

's methods is provided, where the `pair_swapper`

is assumed to follow the `log_potentials`

interface.

#### Contract

#### Examples of functions providing instances of this interface

`path`

#### Description

`Pigeons.path`

— ConstantA continuum of `log_potential`

's interpolating between two end-points. More precisely, a mapping from [0, 1] to the space of probability distributions.

The main use of this interface is to pass it to `discretize()`

.

#### Contract

#### Examples of functions providing instances of this interface

`recorder`

#### Description

`Pigeons.recorder`

— ConstantAccumulate a specific type of statistic, for example by keeping constant size sufficient statistics (via `OnlineStat`

, which conforms this interface), storing samples to a file, etc.

In addition to the contract below, a recorder should support

`Base.merge()`

`Base.empty!()`

See also `recorders`

.

#### Contract

#### Examples of functions providing instances of this interface

`recorder_builder`

#### Description

`Pigeons.recorder_builder`

— ConstantA function such that calling it returns a fresh `recorder`

.

`recorders`

#### Description

`Pigeons.recorders`

— ConstantA `NamedTuple`

containing several `recorder`

's. Each recorder is responsible for a type of statistic to be accumulated (e.g. one for swap accept prs, one for round trip info; some are in-memory, some are on file).

During PT execution, each recorders object keep track of only the statistics for one replica (for thread safety and/or distribution purpose). After a PT round, `reduce_recorders!()`

is used to do a reduction before accessing statistic values.

#### Contract

#### Examples of functions providing instances of this interface

`replicas`

#### Description

`Pigeons.replicas`

— ConstantStores the process' replicas. Since we provide MPI implementations, do not assume that this will contain all the replicas, as others can be located in other processes/machines

Implementations provided

`EntangledReplicas`

: an MPI-based implementation`Vector{Replica}`

: single-process case (above can handle that case, but the array based implementation is non-allocating)

#### Contract

#### Examples of functions providing instances of this interface

`state`

#### Description

`Pigeons.state`

— ConstantThe state held in each Parallel Tempering `Replica`

.

#### Contract

`swap_graph`

#### Description

`Pigeons.swap_graph`

— ConstantInforms `swap!()`

about which chain will interact with which.

These are instantiated by `swap_graphs`

.

Canonical example is the standard Odd and Even swap. Extension point for e.g.

- parallel parallel tempering,
- variational methods with more than 2 legs,
- PT algorithms dealing with more than one target simultaneously for the purpose of model selection.

#### Contract

`swap_graphs`

#### Description

`Pigeons.swap_graphs`

— ConstantCreates one `swap_graph`

for each communication iteration.

#### Contract

#### Examples of functions providing instances of this interface

`target`

#### Description

`Pigeons.target`

— ConstantThe probability distribution of interest.

#### Contract

#### Examples of functions providing instances of this interface

`tempering`

#### Description

`Pigeons.tempering`

— ConstantOrchestrate the `communicate!()`

phase of Parallel Tempering.

In addition to the methods in the contract below, we also assume the presence of the following fields:

#### Contract

#### Examples of functions providing instances of this interface

`variational`

#### Description

`Pigeons.variational`

— ConstantA variational family of reference distributions. Implementations should also satisfy the `log_potential`

contract and `sample_iid!()`

.