pypfilt.hmc

pypfilt.hmc.hmc(settings, instance, param_values, obs_tables=None)

Hamiltonian Monte Carlo sampling for a given scenario instance.

Parameters

  • settings (HmcSettings) – The settings for the HMC sampler.

  • instance (Scenario) – The scenario instance.

  • param_values (np.ndarray) – A structured array of starting locations for each chain.

  • obs_tables (Option[Dict[str, np.ndarray]]) – The observation tables for the scenario instance.

Note

For stochastic models, in order to account for stochastic effects on the likelihood, you should ensure that multiple evaluations are used for each sample.

class pypfilt.hmc.HmcSettings(samples_per_chain: int, evaluations_per_sample: int = 1, evaluation_mask_fn: Optional[Callable[[numpy.ndarray, Results], None]] = None, gradient_delta: float = 0.1, leapfrog_step: float = 0.001, leapfrog_path_length: float = 0.1, tick_fn: Optional[Callable[[THmcSettings, HmcProposal], None]] = None, step_fn: Optional[Callable[[THmcSettings, HmcLeapfrogStep], None]] = None)

Hamiltonian Monte Carlo sampling settings.

Parameters

  • samples_per_chain (int) – The number of samples to draw for each chain.

  • evaluations_per_sample (int) – The number of model evaluations to perform to estimate the likelihood of each sample.

  • evaluation_mask_fn (Optional[Callable[[np.ndarray, Results], None]]) – An optional function that identifies model evaluations that should be ignored.

  • gradient_delta (float) – The size of the parameter perturbations used to estimate the likelihood gradient.

  • leapfrog_step (float) – The step size for the leapfrog integrator.

  • leapfrog_path_length (float) – The path length for the leapfrog integrator.

  • tick_fn (Optional[Callable[[HmcSettings, HmcProposal], None]]) – An optional function that is called with the results of each proposal.

  • step_fn (Optional[Callable[[HmcSettings, HmcLeapfrogStep], None]]) – An optional function that is called after each leapfrog integration step.

class pypfilt.hmc.HmcProposal(sample_number: int, prev_proposals: numpy.typing.NDArray.numpy.float_, new_proposals: numpy.typing.NDArray.numpy.float_, accept_mask: numpy.typing.NDArray.numpy.bool_, new_samples: numpy.typing.NDArray.numpy.float_, prev_proposals_llhd: numpy.typing.NDArray.numpy.float_, new_proposals_llhd: numpy.typing.NDArray.numpy.float_, start_momentum: numpy.typing.NDArray.numpy.float_, end_momentum: numpy.typing.NDArray.numpy.float_, start_momentum_llhd: numpy.typing.NDArray.numpy.float_, end_momentum_llhd: numpy.typing.NDArray.numpy.float_)

Describes the proposals for each chain and whether they were accepted.

Parameters

  • sample_number – The sample number for these proposals.

  • prev_proposals (numpy.ndarray[Any, numpy.dtype[float]]) – The previous samples for each chain.

  • new_proposals (numpy.ndarray[Any, numpy.dtype[float]]) – The proposed values for each chain.

  • accept_mask (numpy.ndarray[Any, numpy.dtype[bool]]) – The acceptance status of each proposed value.

  • new_samples (numpy.ndarray[Any, numpy.dtype[float]]) – The new samples for each chain.

  • prev_proposals_llhd (numpy.ndarray[Any, numpy.dtype[float]]) – The previous sample likelihoods.

  • new_proposals_llhd (numpy.ndarray[Any, numpy.dtype[float]]) – The proposed sample likelihoods.

  • start_momentum (numpy.ndarray[Any, numpy.dtype[float]]) – The initial momentum for each proposed sample.

  • end_momentum (numpy.ndarray[Any, numpy.dtype[float]]) – The final momentum for each proposed sample.

  • start_momentum_llhd (numpy.ndarray[Any, numpy.dtype[float]]) – The initial momentum likelihoods.

  • end_momentum_llhd (numpy.ndarray[Any, numpy.dtype[float]]) – The final momentum likelihoods.

class pypfilt.hmc.HmcLeapfrogStep(step_number: int, total_steps: int, values: numpy.typing.NDArray.numpy.float_, momentum: numpy.typing.NDArray.numpy.float_, llhd_grad: numpy.typing.NDArray.numpy.float_)

Describes a single leapfrog integration step.

Parameters

  • step_number (int) – The step number, where zero is the initial momentum half-step, \(1..N\) are the full steps, and \(N+1\) is the final momentum half-step.

  • total_steps (int) – The number of full steps \(N\).

  • values (numpy.ndarray[Any, numpy.dtype[float]]) – The sample values after performing this integration step.

  • momentum (numpy.ndarray[Any, numpy.dtype[float]]) – The momentum after performing this integration step.

  • llhd_grad (numpy.ndarray[Any, numpy.dtype[float]]) – The approximate likelihood gradient at values.