DREAM

The DREAM class is imported using the following command:

>>> from UQpy.sampling.mcmc.DREAM import DREAM

class DREAM(pdf_target=None, log_pdf_target=None, args_target=None, burn_length=0, jump=1, dimension=None, seed=None, save_log_pdf=False, concatenate_chains=True, jump_rate=3, c=0.1, c_star=1e-06, crossover_probabilities_number=3, gamma_probability=0.2, crossover_adaptation=(-1, 1), check_chains=(-1, 1), random_state=None, n_chains=None, nsamples=None, nsamples_per_chain=None)

DiffeRential Evolution Adaptive Metropolis algorithm [29] [30]

Parameters:

• pdf_target (Union[Callable, list[Callable], None]) –

  Target density function from which to draw random samples. Either pdf_target or log_pdf_target must be provided (the latter should be preferred for better numerical stability).

  If pdf_target is a callable, it refers to the joint pdf to sample from, it must take at least one input x, which are the point(s) at which to evaluate the pdf. Within MCMC the pdf_target is evaluated as: p(x) = pdf_target(x, *args_target)

  where x is a numpy.ndarray  of shape :code:`(nsamples, dimension) and args_target are additional positional arguments that are provided to MCMC via its args_target input.

  If pdf_target is a list of callables, it refers to independent marginals to sample from. The marginal in dimension j is evaluated as: p_j(xj) = pdf_target[j](xj, *args_target[j]) where x is a numpy.ndarray of shape (nsamples, dimension)

• log_pdf_target (Union[Callable, list[Callable], None]) –

  Logarithm of the target density function from which to draw random samples. Either pdf_target or log_pdf_target must be provided (the latter should be preferred for better numerical stability).

  Same comments as for input pdf_target.

• args_target (Optional[tuple]) – Positional arguments of the pdf / log-pdf target function. See pdf_target

• burn_length (int) – Length of burn-in - i.e., number of samples at the beginning of the chain to discard (note: no thinning during burn-in). Default is \(0\), no burn-in.

• jump (int) – Thinning parameter, used to reduce correlation between samples. Setting jump=n corresponds to skipping n-1 states between accepted states of the chain. Default is \(1\) (no thinning).

• dimension (Optional[int]) – A scalar value defining the dimension of target density function. Either dimension and n_chains or seed must be provided.

• seed (Optional[list]) –

  Seed of the Markov chain(s), shape (n_chains, dimension). Default: zeros(n_chains x dimension).

  If seed is not provided, both n_chains and dimension must be provided.

• save_log_pdf (bool) – Boolean that indicates whether to save log-pdf values along with the samples. Default: False

• concatenate_chains (bool) – Boolean that indicates whether to concatenate the chains after a run, i.e., samples are stored as a numpy.ndarray of shape (nsamples * n_chains, dimension) if True, (nsamples, n_chains, dimension) if False. Default: True

• n_chains (Optional[int]) – The number of Markov chains to generate. Either dimension and n_chains or seed must be provided.

• jump_rate (int) – Jump rate. Default: \(3\)

• c (float) – Differential evolution parameter. Default: \(0.1\)

• c_star (float) – Differential evolution parameter, should be small compared to width of target. Default: \(1e-6\)

• crossover_probabilities_number (int) – Number of crossover probabilities. Default: \(3\)

• gamma_probability (float) – Prob(gamma=1). Default: \(0.2\)

• crossover_adaptation (tuple) – (iter_max, rate) governs adaptation of crossover probabilities (adapts every rate iterations if iter<iter_max). Default: (-1, 1), i.e., no adaptation

• check_chains (tuple) – (iter_max, rate) governs discarding of outlier chains (discard every rate iterations if iter<iter_max). Default: (-1, 1), i.e., no check on outlier chains

• random_state (Union[None, int, RandomState]) – Random seed used to initialize the pseudo-random number generator. Default is None.

• nsamples (Optional[int]) – Number of samples to generate.

• nsamples_per_chain (Optional[int]) – Number of samples to generate per chain.

run_one_iteration(current_state, current_log_pdf)

Run one iteration of the mcmc chain for DREAM algorithm, starting at current state - see MCMC class.