DifferentialEvolutionMetropolis Documentation

deMC(model_wrapper, n_its; kwargs...)

Run the Differential Evolution Markov Chain (DE-MC) sampler proposed by ter Braak (2006).

This sampler uses differential evolution updates with optional switching between two scaling factors (γ₁ and γ₂) to enable mode switching.

This implementation varies slightly from the original: updates within a population occur based on the previous positions to enable easy parallelization.

See doi.org/10.1007/s11222-006-8769-1 for more information.

The algorithm runs for a fixed number of iterations with optional burn-in.

Arguments

• model_wrapper: LogDensityModel containing the target log-density function
• n_its: Number of sampling iterations per chain

Keyword Arguments

• rng: Random number generator. Defaults to default_rng().

• n_burnin: Number of burn-in iterations. Defaults to n_its * 5.

• save_burnt: Save burn-in samples in output. Defaults to false.

• γ₁: Primary scaling factor. Defaults to 2.38 / sqrt(2 * dim).

• γ₂: Secondary scaling factor for mode switching. Defaults to 1.0.

• p_γ₂: Probability of using γ₂. Defaults to 0.1.

• chain_type: Type of chain to return (e.g., Any, DifferentialEvolutionOutput, MCMCChains.Chains, or FlexiChains.VNChain). Defaults to DifferentialEvolutionOutput.

• save_final_state: Whether to return the final state along with samples, if true the output will be (samples::chaintype, finalstate). Defaults to false.

Generic DE Arguments

• n_chains: Number of parallel chains. Defaults to max(2 * dimension, 3) for adequate mixing.
• adapt: Whether to enable adaptive behavior during warm-up (if the sampler supports it). Defaults to true.
• initial_position: Starting positions for chains. Can be nothing (random initialization), or a vector of parameter vectors. If the provided vector is smaller than n_chains + n_hot_chains, it will be expanded; if larger and memory=true, excess positions become initial memory. Defaults to nothing.
• parallel: Whether to evaluate initial log-densities in parallel. Useful for expensive models. Defaults to false.
• n_preallocated_indices: This package provides fast sampling-without-replacement by pre-allocating indices, defaults to 3 (which the most asked for by the implemented samplers). Consider increasing it if you implement your own proposal that calls pick_chains with n_chains > 3.
• silent: Suppress informational logging during initialization (e.g., initial position adjustments and memory setup) when true. Defaults to false.

Memory-based Sampling Arguments

• memory: Whether to use memory-based sampling that stores past positions. Memory-based samplers can be more efficient for high-dimensional problems. Defaults to false.
• N₀: Initial memory size for memory-based samplers. Should be ≥ n_chains + n_hot_chains. Defaults to 2 * n_chains + n_hot_chains.
• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Overwrites memory options given at initialization, generally should only be of use if calling step directly.
• memory_refill: Whether to refill memory when full instead of extending the memory, will replace from the start. Defaults to false.
• memory_size: Maximum number of positions preallocated per chain in memory. The effective number stored positions is memory_size * (n_chains + n_hot_chains). Defaults to 1001 or 2*num_warmup if that is provided here or via sample. If memory_refill = true this is the maximum number stored before refilling, if memory_refill = false once the memory is full, the array is extended by another memory_size worth of positions. Set with consideration of available RAM and expected run length.
• memory_thin_interval: Thinning interval for memory updates. If > 0, only every memory_thin_interval-th position is stored in memory.

Parallel Tempering and Simulated Annealing Arguments

• n_hot_chains: Number of hot chains for parallel tempering. Defaults to 0 (no parallel tempering).
• max_temp_pt: Maximum temperature for parallel tempering. Defaults to 2*sqrt(dimension).
• max_temp_sa: Maximum temperature for simulated annealing. Defaults to max_temp_pt.
• α: Temperature ladder spacing parameter. Controls the geometric spacing between temperatures. Defaults to 1.0.
• annealing: Whether to use simulated annealing (temperature decreases over time). Defaults to false.
• annealing_steps: Number of annealing steps. Defaults to annealing ? num_warmup : 0.
• temperature_ladder: Pre-defined temperature ladder as a vector of vectors. If provided, overrides automatic temperature ladder creation. Defaults to create_temperature_ladder(n_chains, n_hot_chains, α, max_temp_pt, max_temp_sa, annealing_steps).

• kwargs...: Additional keyword arguments passed to AbstractMCMC.sample (e.g., memory_refill, memory_thin_interval, silent). See AbstractMCMC documentation.

Returns

• depends on chain_type, and save_final_state

Example

using DifferentialEvolutionMetropolis, Random, Distributions

# Define a simple log-density function
model_wrapper(θ) = logpdf(MvNormal([0.0, 0.0], I), θ)

# Run differential evolution MCMC
result = deMC(model_wrapper, 1000; n_chains = 10, parallel = false)

Notes

• For non-memory samplers, n_chains should typically be ≥ dimension for good mixing
• Memory-based samplers can work effectively with fewer chains than the problem dimension
• Initial log-densities are computed automatically for all starting positions
• When using parallel tempering (n_hot_chains > 0), only the cold chains (first n_chains) are returned in the sample, but all chains participate in the sampling process
• Memory-based samplers with parallel tempering will issue warnings since hot chains typically aren't necessary when using memory

See also deMCzs, DREAMz, setup_de_update.

deMCzs(model_wrapper, n_its; kwargs...)

Run the Differential Evolution Markov Chain with snooker update and historic sampling (DE-MCzs) sampler.

It combines DE updates with optional snooker moves and uses memory-based sampling to efficiently handle high-dimensional problems with fewer chains.

Proposed by ter Braak and Vrugt (2008), see doi.org/10.1007/s11222-008-9104-9.

The algorithm runs for a fixed number of iterations with optional burn-in.

Arguments

• model_wrapper: LogDensityModel containing the target log-density function
• n_its: Number of sampling iterations per chain

Keyword Arguments

• rng: Random number generator. Defaults to default_rng().

• n_burnin: Number of burn-in iterations. Defaults to n_its * 5.

• γ: Scaling factor for DE updates. Defaults to 2.38 / sqrt(2 * dim).

• γₛ: Scaling factor for snooker updates. Defaults to 2.38 / sqrt(2).

• p_snooker: Probability of snooker moves. Defaults to 0.1.

• β: Noise distribution for DE updates. Defaults to Uniform(-1e-4, 1e-4).

• chain_type: Type of chain to return (e.g., Any, DifferentialEvolutionOutput, MCMCChains.Chains, or FlexiChains.VNChain). Defaults to DifferentialEvolutionOutput.

• save_final_state: Whether to return the final state along with samples, if true the output will be (samples::chaintype, finalstate). Defaults to false.

Generic DE Arguments

• n_chains: Number of parallel chains. Defaults to max(2 * dimension, 3) for adequate mixing.
• adapt: Whether to enable adaptive behavior during warm-up (if the sampler supports it). Defaults to true.
• initial_position: Starting positions for chains. Can be nothing (random initialization), or a vector of parameter vectors. If the provided vector is smaller than n_chains + n_hot_chains, it will be expanded; if larger and memory=true, excess positions become initial memory. Defaults to nothing.
• parallel: Whether to evaluate initial log-densities in parallel. Useful for expensive models. Defaults to false.
• n_preallocated_indices: This package provides fast sampling-without-replacement by pre-allocating indices, defaults to 3 (which the most asked for by the implemented samplers). Consider increasing it if you implement your own proposal that calls pick_chains with n_chains > 3.
• silent: Suppress informational logging during initialization (e.g., initial position adjustments and memory setup) when true. Defaults to false.

Memory-based Sampling Arguments

• memory: Whether to use memory-based sampling that stores past positions. Memory-based samplers can be more efficient for high-dimensional problems. Defaults to true.
• N₀: Initial memory size for memory-based samplers. Should be ≥ n_chains + n_hot_chains. Defaults to 2 * n_chains + n_hot_chains.
• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Overwrites memory options given at initialization, generally should only be of use if calling step directly.
• memory_refill: Whether to refill memory when full instead of extending the memory, will replace from the start. Defaults to false.
• memory_size: Maximum number of positions preallocated per chain in memory. The effective number stored positions is memory_size * (n_chains + n_hot_chains). Defaults to 1001 or 2*num_warmup if that is provided here or via sample. If memory_refill = true this is the maximum number stored before refilling, if memory_refill = false once the memory is full, the array is extended by another memory_size worth of positions. Set with consideration of available RAM and expected run length.
• memory_thin_interval: Thinning interval for memory updates. If > 0, only every memory_thin_interval-th position is stored in memory.

Parallel Tempering and Simulated Annealing Arguments

• n_hot_chains: Number of hot chains for parallel tempering. Defaults to 0 (no parallel tempering).
• max_temp_pt: Maximum temperature for parallel tempering. Defaults to 2*sqrt(dimension).
• max_temp_sa: Maximum temperature for simulated annealing. Defaults to max_temp_pt.
• α: Temperature ladder spacing parameter. Controls the geometric spacing between temperatures. Defaults to 1.0.
• annealing: Whether to use simulated annealing (temperature decreases over time). Defaults to false.
• annealing_steps: Number of annealing steps. Defaults to annealing ? num_warmup : 0.
• temperature_ladder: Pre-defined temperature ladder as a vector of vectors. If provided, overrides automatic temperature ladder creation. Defaults to create_temperature_ladder(n_chains, n_hot_chains, α, max_temp_pt, max_temp_sa, annealing_steps).

• kwargs...: Additional keyword arguments passed to AbstractMCMC.sample (e.g., memory_refill, memory_thin_interval, silent). See AbstractMCMC documentation.

Returns

• depends on chain_type, and save_final_state

Example

using DifferentialEvolutionMetropolis, Random, Distributions

# Define a simple log-density function
model_wrapper(θ) = logpdf(MvNormal([0.0, 0.0], I), θ)

# Run differential evolution MCMC
result = deMCzs(model_wrapper, 1000; n_chains = 3)

Notes

• For non-memory samplers, n_chains should typically be ≥ dimension for good mixing
• Memory-based samplers can work effectively with fewer chains than the problem dimension
• Initial log-densities are computed automatically for all starting positions
• When using parallel tempering (n_hot_chains > 0), only the cold chains (first n_chains) are returned in the sample, but all chains participate in the sampling process
• Memory-based samplers with parallel tempering will issue warnings since hot chains typically aren't necessary when using memory

See also deMC, DREAMz.

DREAMz(model_wrapper, n_its; kwargs...)

Run the Differential Evolution Adaptive Metropolis (DREAMz) sampler.

This advanced adaptive sampler uses subspace sampling with adaptive crossover probabilities. It can switch between scaling factors and includes outlier chain detection/replacement. The algorithm adapts during warm-up and can use memory-based sampling for efficiency.

Based on Vrugt et al. (2009), see doi.org/10.1515/IJNSNS.2009.10.3.273.

The algorithm runs for a fixed number of iterations with optional burn-in.

Arguments

• model_wrapper: LogDensityModel containing the target log-density function
• n_its: Number of sampling iterations per chain

Keyword Arguments

• rng: Random number generator. Defaults to default_rng().

• n_burnin: Number of burn-in iterations. Defaults to n_its * 5.

• γ₁: Primary scaling factor for subspace updates. Defaults to adaptive.

• γ₂: Secondary scaling factor. Defaults to 1.0.

• p_γ₂: Probability of using γ₂. Defaults to 0.2.

• n_cr: Number of crossover probabilities for adaptation. Defaults to 3.

• cr₁: Crossover probability for γ₁. Defaults to adaptive.

• cr₂: Crossover probability for γ₂. Defaults to adaptive.

• ϵ: Additive noise distribution. Defaults to Uniform(-1e-4, 1e-4).

• e: Multiplicative noise distribution. Defaults to Normal(0.0, 1e-2).

• chain_type: Type of chain to return (e.g., Any, DifferentialEvolutionOutput, MCMCChains.Chains, or FlexiChains.VNChain). Defaults to DifferentialEvolutionOutput.

• save_final_state: Whether to return the final state along with samples, if true the output will be (samples::chaintype, finalstate). Defaults to false.

Generic DE Arguments

• n_chains: Number of parallel chains. Defaults to max(2 * dimension, 3) for adequate mixing.
• adapt: Whether to enable adaptive behavior during warm-up (if the sampler supports it). Defaults to true.
• initial_position: Starting positions for chains. Can be nothing (random initialization), or a vector of parameter vectors. If the provided vector is smaller than n_chains + n_hot_chains, it will be expanded; if larger and memory=true, excess positions become initial memory. Defaults to nothing.
• parallel: Whether to evaluate initial log-densities in parallel. Useful for expensive models. Defaults to false.
• n_preallocated_indices: This package provides fast sampling-without-replacement by pre-allocating indices, defaults to 3 (which the most asked for by the implemented samplers). Consider increasing it if you implement your own proposal that calls pick_chains with n_chains > 3.
• silent: Suppress informational logging during initialization (e.g., initial position adjustments and memory setup) when true. Defaults to false.

Memory-based Sampling Arguments

• memory: Whether to use memory-based sampling that stores past positions. Memory-based samplers can be more efficient for high-dimensional problems. Defaults to true.
• N₀: Initial memory size for memory-based samplers. Should be ≥ n_chains + n_hot_chains. Defaults to 2 * n_chains + n_hot_chains.
• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Overwrites memory options given at initialization, generally should only be of use if calling step directly.
• memory_refill: Whether to refill memory when full instead of extending the memory, will replace from the start. Defaults to false.
• memory_size: Maximum number of positions preallocated per chain in memory. The effective number stored positions is memory_size * (n_chains + n_hot_chains). Defaults to 1001 or 2*num_warmup if that is provided here or via sample. If memory_refill = true this is the maximum number stored before refilling, if memory_refill = false once the memory is full, the array is extended by another memory_size worth of positions. Set with consideration of available RAM and expected run length.
• memory_thin_interval: Thinning interval for memory updates. If > 0, only every memory_thin_interval-th position is stored in memory.

Parallel Tempering and Simulated Annealing Arguments

• n_hot_chains: Number of hot chains for parallel tempering. Defaults to 0 (no parallel tempering).
• max_temp_pt: Maximum temperature for parallel tempering. Defaults to 2*sqrt(dimension).
• max_temp_sa: Maximum temperature for simulated annealing. Defaults to max_temp_pt.
• α: Temperature ladder spacing parameter. Controls the geometric spacing between temperatures. Defaults to 1.0.
• annealing: Whether to use simulated annealing (temperature decreases over time). Defaults to false.
• annealing_steps: Number of annealing steps. Defaults to annealing ? num_warmup : 0.
• temperature_ladder: Pre-defined temperature ladder as a vector of vectors. If provided, overrides automatic temperature ladder creation. Defaults to create_temperature_ladder(n_chains, n_hot_chains, α, max_temp_pt, max_temp_sa, annealing_steps).

• kwargs...: Additional keyword arguments passed to AbstractMCMC.sample (e.g., memory_refill, memory_thin_interval, silent). See AbstractMCMC documentation.

Returns

• depends on chain_type, and save_final_state

Example

using DifferentialEvolutionMetropolis, Random, Distributions

# Define a simple log-density function
model_wrapper(θ) = logpdf(MvNormal([0.0, 0.0], I), θ)

# Run DREAM with subspace sampling
result = DREAMz(model_wrapper, 1000; n_chains = 10, memory = false)

Notes

• For non-memory samplers, n_chains should typically be ≥ dimension for good mixing
• Memory-based samplers can work effectively with fewer chains than the problem dimension
• Initial log-densities are computed automatically for all starting positions
• When using parallel tempering (n_hot_chains > 0), only the cold chains (first n_chains) are returned in the sample, but all chains participate in the sampling process
• Memory-based samplers with parallel tempering will issue warnings since hot chains typically aren't necessary when using memory

See also deMC, deMCzs, setup_subspace_sampling.

Create a composite sampler scheme from multiple differential evolution update steps.

The update method used in each iteration for each chain is randomly selected from the provided update steps according to their weights. This allows combining different sampling strategies (e.g., DE updates with snooker updates) in a single sampler.

Arguments

• updates...: One or more differential evolution sampler objects created by functions like setup_de_update, setup_snooker_update, setup_subspace_sampling.

Keyword Arguments

• w: Vector of weights for each update step. If not provided, all updates are chosen with equal probability. Weights must be non-negative and will be automatically normalized.

Returns

• A DifferentialEvolutionCompositeSampler that can be used with AbstractMCMC.sample.

Examples

using DifferentialEvolutionMetropolis

# Only snooker updates
sampler1 = setup_sampler_scheme(setup_snooker_update())

# DE and Snooker with equal probability
sampler2 = setup_sampler_scheme(setup_de_update(), setup_snooker_update())

# Snooker 10% of the time, DE 90% of the time
sampler3 = setup_sampler_scheme(setup_de_update(), setup_snooker_update(); w = [0.9, 0.1])

See also setup_de_update, setup_snooker_update, setup_subspace_sampling.

Set up a Differential Evolution (DE) update step for MCMC sampling.

Creates a sampler that proposes new states by adding scaled difference vectors between randomly selected chains plus small noise. This is the core update mechanism from the original DE-MC algorithm by ter Braak (2006).

See doi.org/10.1007/s11222-006-8769-1 for more information.

Keyword Arguments

• γ: Scaling factor for the difference vector. Can be a Real (fixed value), a UnivariateDistribution (random scaling), or nothing (automatic based on n_dims). Defaults to nothing.
• β: Distribution for small noise added to proposals. Must be a univariate continuous distribution. Defaults to Uniform(-1e-4, 1e-4).
• n_dims: Problem dimension used for automatic γ selection. If > 0 and γ is nothing, sets γ to the theoretically optimal 2.38 / sqrt(2 * n_dims). If ≤ 0, uses Uniform(0.8, 1.2). Defaults to 0.
• check_args: Whether to validate input distributions. Defaults to true.

Returns

• A DifferentialEvolutionSampler that can be used with setup_sampler_scheme or step or sample from AbstractMCMC.

Example

using DifferentialEvolutionMetropolis, Distributions

# Setup differential evolution update with custom parameters
de_update = setup_de_update(γ = 1.0, β = Normal(0.0, 0.01))

See also setup_snooker_update, setup_subspace_sampling, setup_sampler_scheme.

Set up a Snooker update step for MCMC sampling.

Creates a sampler that proposes moves along the line connecting the current position to a projection point, scaled by the difference between two other randomly selected chains. This update can help with sampling from distributions with complex geometries by making larger moves in effective directions.

See doi.org/10.1007/s11222-008-9104-9 for more information.

Keyword Arguments

• γ: Scaling factor for the projection. Can be a Real (fixed value), a UnivariateDistribution (random scaling), or nothing (automatic based on deterministic_γ). Defaults to nothing.
• deterministic_γ: When γ is nothing, determines the automatic value. If true, uses the theoretically optimal 2.38 / sqrt(2). If false, uses Uniform(0.8, 1.2). Defaults to true.
• check_args: Whether to validate input distributions. Defaults to true.

Returns

• A DifferentialEvolutionSnookerSampler that can be used with setup_sampler_scheme or step or sample from AbstractMCMC.

Example

using DifferentialEvolutionMetropolis, Distributions

# Setup snooker update with custom gamma distribution
snooker_update = setup_snooker_update(γ = Uniform(0.1, 2.0))

See also setup_de_update, setup_subspace_sampling, setup_sampler_scheme.

Set up a Subspace Sampling (DREAM-like) update step for MCMC sampling.

Creates a sampler that updates only a random subset of parameters in each iteration, using multiple scaled difference vectors. The crossover probability determines which parameters to update and can be adapted during warm-up for improved efficiency.

See doi.org/10.1515/IJNSNS.2009.10.3.273 for more information.

Keyword Arguments

• γ: Scaling factor for the difference vector sum. If nothing (default), uses the adaptive formula 2.38 / sqrt(2 * δ * d) where d is the number of updated dimensions. If a Real is provided, uses that fixed value throughout sampling.
• cr: Crossover probability for parameter selection. Can be a Real (fixed probability), nothing (adaptive using n_cr values), or a UnivariateDistribution. If cr is a DiscreteNonParametric then it those values can also be adapted. Defaults to nothing.
• n_cr: Number of crossover probabilities to adapt between when cr is nothing. Higher values allow more fine-tuned adaptation. Defaults to 3.
• δ: Number of difference vectors to sum. Can be an Integer (fixed) or a DiscreteUnivariateDistribution (random). Defaults to DiscreteUniform(1, 3).
• ϵ: Distribution for small additive noise in the selected subspace. Defaults to Uniform(-1e-4, 1e-4).
• e: Distribution for multiplicative noise (1 + e) applied to the difference vector sum. Defaults to Normal(0.0, 1e-2).
• check_args: Whether to validate input distributions. Defaults to true.

Returns

• A subspace sampler that can be used with setup_sampler_scheme or step or sample from AbstractMCMC.

Example

using DifferentialEvolutionMetropolis, Distributions

# Setup subspace sampling with custom crossover rate and delta
subspace_config = setup_subspace_sampling(cr = Beta(1, 2), δ = 2)

See also setup_de_update, setup_snooker_update, setup_sampler_scheme.

step(rng, model_wrapper, sampler, state; parallel=false, update_memory=true, kwargs...)

Perform a single MCMC step using differential evolution sampling.

This is the core sampling function that proposes new states for all chains and accepts or rejects them according to the Metropolis criterion. For adaptive samplers, the function automatically fixes adaptive parameters before sampling.

Arguments

• rng: Random number generator
• model_wrapper: LogDensityModel containing the target log-density function
• sampler: Differential evolution sampler (any AbstractDifferentialEvolutionSampler)
• state: Current state of all chains

Keyword Arguments

• parallel: Whether to run chains in parallel using threading. Defaults to false. Advisable for slow models.
• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Over writes memory options given at initialization.
• kwargs...: Additional keyword arguments passed to update functions (see https://turinglang.org/AbstractMCMC.jl/stable/api/#Common-keyword-arguments)

Returns

• sample: DifferentialEvolutionSample containing new positions and log-densities
• new_state: Updated state for the next iteration

Example

sample, new_state = step(rng, model, sampler, state; parallel=true)

See also step_warmup, sample from AbstractMCMC.

step(rng, model_wrapper, sampler; n_chains, memory=true, N₀, adapt=true, initial_position=nothing, parallel=false, kwargs...)

Initialize differential evolution sampling by setting up chains and computing initial state.

This function serves as the entry point for differential evolution MCMC sampling. It handles chain initialization, memory setup for memory-based samplers, adaptive state initialization, and returns the initial sample and state that can be used with AbstractMCMC.sample.

Arguments

• rng: Random number generator
• model_wrapper: LogDensityModel containing the target log-density function
• sampler: Differential evolution sampler to use

Keyword Arguments

Generic DE Arguments

• n_chains: Number of parallel chains. Defaults to max(2 * dimension, 3) for adequate mixing.
• adapt: Whether to enable adaptive behavior during warm-up (if the sampler supports it). Defaults to true.
• initial_position: Starting positions for chains. Can be nothing (random initialization), or a vector of parameter vectors. If the provided vector is smaller than n_chains + n_hot_chains, it will be expanded; if larger and memory=true, excess positions become initial memory. Defaults to nothing.
• parallel: Whether to evaluate initial log-densities in parallel. Useful for expensive models. Defaults to false.
• n_preallocated_indices: This package provides fast sampling-without-replacement by pre-allocating indices, defaults to 3 (which the most asked for by the implemented samplers). Consider increasing it if you implement your own proposal that calls pick_chains with n_chains > 3.
• silent: Suppress informational logging during initialization (e.g., initial position adjustments and memory setup) when true. Defaults to false.

Memory-based Sampling Arguments

• memory: Whether to use memory-based sampling that stores past positions. Memory-based samplers can be more efficient for high-dimensional problems. Defaults to true.
• N₀: Initial memory size for memory-based samplers. Should be ≥ n_chains + n_hot_chains. Defaults to 2 * n_chains + n_hot_chains.
• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Overwrites memory options given at initialization, generally should only be of use if calling step directly.
• memory_refill: Whether to refill memory when full instead of extending the memory, will replace from the start. Defaults to false.
• memory_size: Maximum number of positions preallocated per chain in memory. The effective number stored positions is memory_size * (n_chains + n_hot_chains). Defaults to 1001 or 2*num_warmup if that is provided here or via sample. If memory_refill = true this is the maximum number stored before refilling, if memory_refill = false once the memory is full, the array is extended by another memory_size worth of positions. Set with consideration of available RAM and expected run length.
• memory_thin_interval: Thinning interval for memory updates. If > 0, only every memory_thin_interval-th position is stored in memory.

Parallel Tempering and Simulated Annealing Arguments

• n_hot_chains: Number of hot chains for parallel tempering. Defaults to 0 (no parallel tempering).
• max_temp_pt: Maximum temperature for parallel tempering. Defaults to 2*sqrt(dimension).
• max_temp_sa: Maximum temperature for simulated annealing. Defaults to max_temp_pt.
• α: Temperature ladder spacing parameter. Controls the geometric spacing between temperatures. Defaults to 1.0.
• annealing: Whether to use simulated annealing (temperature decreases over time). Defaults to false.
• annealing_steps: Number of annealing steps. Defaults to annealing ? num_warmup : 0.
• temperature_ladder: Pre-defined temperature ladder as a vector of vectors. If provided, overrides automatic temperature ladder creation. Defaults to create_temperature_ladder(n_chains, n_hot_chains, α, max_temp_pt, max_temp_sa, annealing_steps).

Returns

• sample: DifferentialEvolutionSample containing initial positions and log-densities
• state: Initial state (DifferentialEvolutionState) ready for sampling

Examples

using DifferentialEvolutionMetropolis, Random, Distributions

# Setup
rng = Random.default_rng()
model_wrapper(θ) = logpdf(MvNormal([0.0, 0.0], I), θ)
sampler = deMCzs()

# Basic initialization with default settings
sample, state = step(rng, model_wrapper, sampler)

# Custom number of chains with memory disabled
sample2, state2 = step(rng, model_wrapper, sampler; n_chains=10, memory=false)

# With custom initial positions
init_pos = [randn(2) for _ in 1:8]
sample3, state3 = step(rng, model_wrapper, sampler; initial_position=init_pos)

Notes

• For non-memory samplers, n_chains should typically be ≥ dimension for good mixing
• Memory-based samplers can work effectively with fewer chains than the problem dimension
• Initial log-densities are computed automatically for all starting positions
• When using parallel tempering (n_hot_chains > 0), only the cold chains (first n_chains) are returned in the sample, but all chains participate in the sampling process
• Memory-based samplers with parallel tempering will issue warnings since hot chains typically aren't necessary when using memory

See also sample from AbstractMCMC, deMC, deMCzs, DREAMz.

step_warmup(rng, model_wrapper, sampler, state; parallel=false, kwargs...)

Perform a single MCMC step during the warm-up (adaptive) phase.

During warm-up, this function performs the same sampling as step but also updates adaptive parameters. For subspace samplers, it adapts crossover probabilities based on the effectiveness of different parameter subsets.

Arguments

• rng: Random number generator
• model_wrapper: LogDensityModel containing the target log-density function
• sampler: Adaptive differential evolution sampler
• state: Current state including adaptive parameters

Keyword Arguments

• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Useful if memory has grown too large.
• parallel: Whether to run chains in parallel using threading. Defaults to false.
• kwargs...: Additional keyword arguments passed to update functions

Returns

• sample: DifferentialEvolutionSample containing new positions and log-densities
• new_state: Updated state with adapted parameters for the next iteration

Example

using DifferentialEvolutionMetropolis, Random, Distributions

# Setup for warmup step example
rng = Random.default_rng()
model_wrapper(θ) = logpdf(MvNormal([0.0, 0.0], I), θ)
sampler = DREAMz()

# Initialize state (this would typically be done by AbstractMCMC.sample)
# sample, new_state = step_warmup(rng, model_wrapper, sampler, state; parallel=false)

See also step, fix_sampler.

step_warmup(rng, model_wrapper, sampler, state; kwargs...)

Perform a single MCMC step during warm-up for composite samplers.

For composite samplers, this function randomly selects one of the component update methods, performs a warm-up step with that method, and updates the corresponding adaptive state while preserving other component states.

Arguments

• rng: Random number generator
• model_wrapper: LogDensityModel containing the target log-density function
• sampler: Composite differential evolution sampler
• state: Current state with composite adaptive parameters

Keyword Arguments

• update_memory: Whether to update the memory with new positions (for memory-based samplers). Defaults to true. Useful if memory has grown too large.
• kwargs...: Additional keyword arguments passed to component update functions

Returns

• sample: DifferentialEvolutionSample containing new positions and log-densities
• new_state: Updated state with adapted parameters for the selected component

See also step_warmup, setup_sampler_scheme.

fix_sampler(sampler::AbstractDifferentialEvolutionSampler, adaptive_state::AbstractDifferentialEvolutionAdaptiveState)

Fix adaptive parameters of a sampler to their current adapted values.

For non-adaptive samplers, returns the sampler unchanged. For adaptive samplers, returns a new sampler with the adaptive parameters fixed to their current values in the adaptive_state.

Arguments

• sampler: The differential evolution sampler to fix
• adaptive_state: The adaptive state containing current parameter values

Returns

• A sampler with fixed (non-adaptive) parameters

Example

using DifferentialEvolutionMetropolis, Random, Distributions

# This function is typically used after warmup/adaptation phase
# fixed_sampler = fix_sampler(adaptive_sampler, state.adaptive_state)

See also fix_sampler_state.

fix_sampler_state(sampler::AbstractDifferentialEvolutionSampler, state::DifferentialEvolutionState)

Fix adaptive sampler parameters and return a corresponding non-adaptive state.

Takes an adaptive sampler and state, fixes the sampler's adaptive parameters to their current values, and returns both the fixed sampler and a simplified state without adaptive components.

Arguments

• sampler: The differential evolution sampler (potentially adaptive)
• state: The current sampler state (DifferentialEvolutionState)

Returns

• fixed_sampler: Sampler with adaptive parameters fixed to current values
• fixed_state: State without adaptive components

Example

using DifferentialEvolutionMetropolis, Random, Distributions

# This function is typically used after warmup/adaptation phase
# fixed_sampler, fixed_state = fix_sampler_state(sampler, state)

See also fix_sampler.

r̂_stopping_criteria(rng, model, sampler, samples, state, iteration; kwargs...)

Stopping criterion based on the Gelman-Rubin diagnostic (R̂).

Sampling continues until the R̂ value for all parameters falls below maximum_R̂, indicating convergence across chains. This function is designed to be used as the N_or_isdone argument in AbstractMCMC.sample for adaptive stopping.

The diagnostic is computed on the last half of the collected samples to focus on the stationary portion of the chains.

Arguments

• rng: Random number generator (unused but required by AbstractMCMC interface)
• model: The model being sampled (unused but required by interface)
• sampler: The differential evolution sampler (unused but required by interface)
• samples: Vector of collected samples from all chains
• state: Current sampler state (unused but required by interface)
• iteration: Current iteration number

Keyword Arguments

• check_every: Frequency (in iterations) for checking R̂ values. Defaults to 1000.
• maximum_R̂: Maximum acceptable R̂ value for convergence. Defaults to 1.2.
• maximum_iterations: Maximum number of iterations before forced stopping. Defaults to 100000.
• minimum_iterations: Minimum iterations before convergence checking begins. Defaults to 0.

Returns

• true if sampling should stop (converged or maximum iterations reached)
• false if sampling should continue

Example

using DifferentialEvolutionMetropolis, AbstractMCMC, Random, Distributions

# Create a simple model
model_wrapper(θ) = logpdf(MvNormal([0.0, 0.0], I), θ)

# Setup sampler
sampler = deMCzs()

# Use with adaptive stopping criterion
rng = Random.default_rng()
chains = sample(rng, model_wrapper, sampler, r̂_stopping_criteria;
               n_chains=4, check_every=500, maximum_R̂=1.1)

See also MCMCDiagnosticTools.rhat, deMCzs, DREAMz.

DifferentialEvolutionOutput{T <: Real}

Container for differential evolution MCMC sampling results.

Fields

• samples::Array{T, 3}: Three-dimensional array of parameter samples with dimensions (iterations, chains, parameters). Each sample represents a point in parameter space from the MCMC chain.
• ld::Matrix{T}: Two-dimensional matrix of log-density values with dimensions (iterations, chains). Contains the log-probability density evaluated at each corresponding sample point.

Type Parameters

• T <: Real: Numeric type for the samples and log-density values (typically Float64).

Examples

# Access samples from the output
output = sample(model, sampler, n_samples)
parameter_samples = output.samples  # Shape: (n_samples, n_chains, n_params)
log_densities = output.ld          # Shape: (n_samples, n_chains)

# Extract samples for a specific chain
chain_1_samples = output.samples[:, 1, :]  # All samples from chain 1