Algorithms

algorithms

Implementation of core MCMC algorithms.

Classes:

Name	Description
MCMCAlgorith	abstract base class used for all MCMCAlgorithms
pCNAlgorithm	Implementation of the pCN algorithm
MALAAlgorithm	Implementation of the MALA (pCNL) algorithm

ls_mcmc.algorithms._CachedArgs dataclass

Base class for argument caches used in MCMCAlgorithm.

clear

clear() -> None

Clear all cached arguments.

ls_mcmc.algorithms.MCMCAlgorithm

Bases: ABC

Abstract base class for MCMC algorithms.

Subclasses must implement proposal generation and the acceptance probability. This class handles the generic propose/accept-reject step and caching handoff.

Methods:

Name	Description
compute_step	Compute one step of MCMC

__init__

__init__(model: model.MCMCModel, step_width: float) -> None

Initialize MCMC algorithm.

Parameters:

Name	Type	Description	Default
model	MCMCModel	Provides potential \(\Phi\) and preconditioner actions encoding the covariance operator \(C\) and reference point \(u_0\).	required
step_width	float	The step scaling \(\delta \in (0,2)\). Smaller values give higher acceptance but slower exploration; larger values explore faster until acceptance deteriorates.	required

compute_step

compute_step(current_state: np.ndarray[tuple[int], np.dtype[np.floating]], rng: np.random.Generator) -> tuple[np.ndarray[tuple[int], np.dtype[np.floating]], bool]

Advance the Markov chain by one step.

1. Create a proposal from the current state.
2. Perform accept-reject according to the subclass criterion.
3. Swap caches on accept and clear the proposal cache.

Parameters:

Name	Type	Description	Default
current_state	np.ndarray	Current chain state.	required
rng	np.random.Generator	Random number generator.	required

Returns:

Type	Description
tuple[np.ndarray[tuple[int], np.dtype[np.floating]], bool]	tuple[np.ndarray, bool]: New state and a flag indicating acceptance.

_perform_accept_reject

_perform_accept_reject(current_state: np.ndarray[tuple[int], np.dtype[np.floating]], proposal: np.ndarray[tuple[int], np.dtype[np.floating]], rng: np.random.Generator) -> tuple[np.ndarray[tuple[int], np.dtype[np.floating]], bool]

Perform a standard Metropolis-Hastings accept/reject step.

Parameters:

Name	Type	Description	Default
current_state	np.ndarray	Current state.	required
proposal	np.ndarray	Proposed state.	required
rng	np.random.Generator	Random number generator.	required

Returns:

Type	Description
tuple[np.ndarray[tuple[int], np.dtype[np.floating]], bool]	tuple[np.ndarray, bool]: Accepted state (either proposal or current) and flag.

_create_proposal abstractmethod

_create_proposal(state: np.ndarray[tuple[int], np.dtype[np.floating]], rng: np.random.Generator) -> np.ndarray[tuple[int], np.dtype[np.floating]]

Create a proposal given the current state and RNG.

Parameters:

Name	Type	Description	Default
state	np.ndarray	Current state.	required
rng	np.random.Generator	Random number generator.	required

Returns:

Type	Description
np.ndarray[tuple[int], np.dtype[np.floating]]	np.ndarray: Proposed next state with same shape as state.

_evaluate_acceptance_probability abstractmethod

_evaluate_acceptance_probability(current_state: np.ndarray[tuple[int], np.dtype[np.floating]], proposal: np.ndarray[tuple[int], np.dtype[np.floating]]) -> float

Evaluate acceptance probability for a proposal in [0, 1].

ls_mcmc.algorithms._pCNCachedArgs dataclass

Bases: _CachedArgs

Argument cache for pCN algorithm.

ls_mcmc.algorithms.pCNAlgorithm

Bases: MCMCAlgorithm

Preconditioned Crank-Nicolson (pCN) sampler.

Implements the function-space pCN proposal for sampling from a target measure with (unnormalized) density proportional to \(\exp(-\Phi(u))\) with respect to a Gaussian reference measure \(\mu_0 = \mathcal N(u_0, C)\).

Proposal (given current state \(u\)):

\[ v = u_0 + \frac{2-\delta}{2+\delta}\, (u - u_0) + \frac{\sqrt{8\delta}}{2+\delta}\, w, \qquad w \sim \mathcal N(0, C), \]

where step_width corresponds to the parameter \(\delta \in (0,2)\). The move preserves the prior (reference) measure and therefore yields a simple Metropolis-Hastings acceptance probability

\[ \alpha(u,v) = 1 \wedge \exp\big( -\Phi(v) + \Phi(u) \big). \]

Methods:

Name	Description
compute_step	Compute one step of MCMC

Notes

The proposal leaves the Gaussian reference measure invariant; only the potential difference appears in the acceptance probability (no proposal density correction term).

References

Cotter, Roberts, Stuart, White (2013). MCMC Methods for Functions: Modifying Old Algorithms to Make Them Faster. Statistical Science 28(3).

__init__

__init__(model: model.MCMCModel, step_width: float) -> None

Initialize pCN algorithm.

Parameters:

Name	Type	Description	Default
model	MCMCModel	Provides potential \(\Phi\) and preconditioner actions encoding the covariance operator \(C\) and reference point \(u_0\).	required
step_width	float	The proposal scaling \(\delta \in (0,1)\). Smaller values give higher acceptance but slower exploration; larger values explore faster until acceptance deteriorates.	required

_cache_args

_cache_args(potential_current: float | None = None, potential_proposal: float | None = None) -> None

Cache potential values for reuse if already computed.

Parameters:

Name	Type	Description	Default
potential_current	float | None	Potential at current state.	None
potential_proposal	float | None	Potential at proposed state.	None

_create_proposal

_create_proposal(state: np.ndarray[tuple[int], np.dtype[np.floating]], rng: np.random.Generator) -> np.ndarray[tuple[int], np.dtype[np.floating]]

Generate a pCN proposal state.

The proposal preserves the Gaussian reference measure. Implementation uses the model's preconditioner square root action to draw correlated noise.

Parameters:

Name	Type	Description	Default
state	np.ndarray	Current state.	required
rng	np.random.Generator	Random number generator.	required

Returns:

Type	Description
np.ndarray[tuple[int], np.dtype[np.floating]]	np.ndarray: Proposed state with same shape as state.

_evaluate_acceptance_probability

_evaluate_acceptance_probability(current_state: np.ndarray[tuple[int], np.dtype[np.floating]], proposal: np.ndarray[tuple[int], np.dtype[np.floating]]) -> float

Compute acceptance probability for pCN.

For pCN the proposal ratio cancels, yielding min(1, exp(-Phi(v) + Phi(u))).

Parameters:

Name	Type	Description	Default
current_state	np.ndarray	Current state u.	required
proposal	np.ndarray	Proposed state v.	required

Returns:

Name	Type	Description
float	float	Acceptance probability in [0, 1].

ls_mcmc.algorithms._MALACachedArgs dataclass

Bases: _CachedArgs

Cache container for MALA intermediate quantities.

Attributes:

Name	Type	Description
potential	float | None	Potential value \(\Phi(u)\).
gradient	np.ndarray | None	Gradient \(\nabla\Phi(u)\).
sqrt_action_gradient	np.ndarray | None	Action of preconditioner square root on gradient.
action_gradient	np.ndarray | None	Action of full preconditioner on gradient.

ls_mcmc.algorithms.MALAAlgorithm

Bases: MCMCAlgorithm

Preconditioned Crank-Nicolson Langevin (pCNL / MALA) sampler.

Implements the function-space MALA variant (Cotter et al., 2013) using a Gaussian reference prior with covariance operator \(C\).

Proposal (given current state \(u\)):

\[ v = \frac{2-\delta}{2+\delta}\,u - \frac{2\delta}{2+\delta}\,C \nabla \Phi(u) + \frac{\sqrt{8\delta}}{2+\delta}\,w,\qquad w \sim \mathcal N(0, C). \]

Methods:

Name	Description
compute_step	Compute one step of MCMC

Notes

The preconditioner implicitly encodes the covariance operator \(C\) of the reference Gaussian prior.

References

Cotter, Roberts, Stuart, White (2013). "MCMC Methods for Functions: Modifying Old Algorithms to Make Them Faster." Statistical Science 28(3).

__init__

__init__(model: model.DifferentiableMCMCModel, step_width: float) -> None

Initialize MALA Sampling.

Parameters:

Name	Type	Description	Default
model	DifferentiableMCMCModel	Provides potential \(\Phi\), its gradient, and preconditioner actions (embodying \(C\)).	required
step_width	float	Step size \(\delta > 0\). Smaller values increase acceptance; larger values explore faster until stability or acceptance deteriorates.	required

_populate_cache

_populate_cache(cache: _MALACachedArgs, state: np.ndarray[tuple[int], np.dtype[np.floating]]) -> None

Populates cache with necessary arguments for the proposal and accept-reject step.

Parameters:

Name	Type	Description	Default
cache	MALACachedArgs	description	required
state	np.ndarray[tuple[int], np.dtype[np.floating]]	description	required

_create_proposal

_create_proposal(state: np.ndarray[tuple[int], np.dtype[np.floating]], rng: np.random.Generator) -> np.ndarray[tuple[int], np.dtype[np.floating]]

Creates new proposal based on the current state.

Parameters:

Name	Type	Description	Default
state	np.ndarray[tuple[int], np.dtype[np.floating]]	current state	required
rng	np.random.Generator	random number generator used for random increment	required

Returns:

Type	Description
np.ndarray[tuple[int], np.dtype[np.floating]]	np.ndarray: proposal

_evaluate_acceptance_probability

_evaluate_acceptance_probability(current_state: np.ndarray[tuple[int], np.dtype[np.floating]], proposal: np.ndarray[tuple[int], np.dtype[np.floating]]) -> float

Calculates the acceptance probability for the proposal based on the current state.

Parameters:

Name	Type	Description	Default
current_state	np.ndarray[tuple[int], np.dtype[np.floating]]	current state	required
proposal	np.ndarray[tuple[int], np.dtype[np.floating]]	proposed state	required

Returns:

Name	Type	Description
float	float	acceptance probability