Configuration & API reference¶
All sampler options are passed through bilby.run_sampler(..., sampler="laplace", **kwargs).
The reference below is generated directly from the source docstrings, so it always
matches the installed version.
The Laplace sampler¶
Every keyword argument and its default is documented here.
Laplace ¶
Bases: Sampler
Bilby sampler implementing the Laplace approximation.
Finds the MAP (maximum a posteriori) with scipy optimisation, computes the inverse Hessian of the log-posterior as a Gaussian proposal covariance, then draws posterior samples via a resample method (if requested).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
likelihood
|
Likelihood
|
|
required |
priors
|
PriorDict or dict
|
|
required |
outdir
|
str
|
|
'outdir'
|
label
|
str
|
|
'label'
|
resample
|
str or None
|
Resampling method: |
required |
seed
|
int or None
|
Random seed. Pass it as bilby's |
required |
npool
|
int or None
|
Number of processes for parallel likelihood evaluation (bilby standard
argument; the aliases |
required |
target_nsamples
|
int
|
Target number of posterior samples (default 10000). |
required |
batch_nsamples
|
int
|
For methods that draw samples in batches, this specifies the number of samples drawn per batch from the proposal distribution (default 1000). |
required |
prior_nsamples
|
int
|
Number of prior draws used in the MAP search (multi-start mode, default 100). |
required |
max_iterations
|
int
|
Proposal draws after which a batched resampling run (rejection /
importance / inprior) stops if its acceptance is below 1% (default
1e6). Raises |
required |
minimization_method
|
str
|
Optimization method. Default is |
required |
map_restarts
|
int
|
Number of independent |
required |
map_vectorized
|
bool
|
If True (default), hand |
required |
map_spike_guard
|
bool
|
If True (default), test every MAP candidate -- each restart, a
|
required |
map_spike_delta
|
float
|
Neighbour offset of the spike test, in the unit cube (default 1e-3). It must exceed the width of the spikes to be detected. The peak's curvature is removed, so a narrow posterior does not trip the test. |
required |
plot_diagnostic
|
bool
|
If True, produce a corner diagnostic plot after resampling. |
required |
cov_scaling
|
float or dict
|
Multiplicative scale applied to the Laplace covariance. Each value multiplies the corresponding parameter's variance (so a value of 4 widens that parameter's marginal sigma by 2x).
Off-diagonal entries scale by the geometric mean Applied after the eigenvalue-based covariance validation, so the requested scale is authoritative: validation repairs the estimated covariance, then this scaling is the final word on the proposal width. |
required |
sampling_cov
|
pd.DataFrame, tuple, or None
|
Pre-computed covariance to use in place of the Laplace-estimated covariance. Must be one of:
The MAP search still runs; only the covariance step is replaced.
Examples¶Given an
Or pass the tuple form directly::
|
required |
proposal_covariance
|
str or None
|
How the Laplace Gaussian is turned into the proposal every resampling
method draws from (
|
required |
fisher_method
|
str
|
How to estimate the posterior precision. |
required |
fisher_kwargs
|
dict or None
|
Keyword arguments forwarded to the waveform-Fisher computation when
|
required |
use_unit_cube
|
bool
|
If True (default), compute the Hessian in unit-cube coordinates (via the prior CDFs) and floor the precision at the prior precision. If False, compute it directly in parameter space. |
required |
jacobian_cap_scale
|
float
|
Unit-cube Hessian path only. When mapping the unit-cube precision back
to parameter space, the Jacobian |
required |
hessian_kwargs
|
dict or None
|
Keyword arguments forwarded to |
required |
use_injection_for_map
|
bool
|
If True and injection_parameters are set, use them as the starting
point for the MAP search, and (with |
required |
fail_on_error
|
bool
|
If True, raise SamplerError when sampling fails; otherwise just log. |
required |
n_modes
|
int
|
Number of distinct posterior modes to search for. When The mixture is the proposal for every resampling method:
|
required |
mode_searches
|
tuple of str
|
Which searches propose secondary modes when
The stochastic and symmetry searches can be enabled independently,
e.g. |
required |
mode_search_nsamples
|
int
|
Number of prior draws used by the |
required |
mode_search_subspace
|
list of str or None
|
Restrict the |
required |
smc_prior_flow
|
str
|
Which distribution aspire anneals from. Aspire's tempered target is
|
required |
mode_symmetries
|
list of (str, float) or None
|
Symmetries of the posterior, as The symmetry need not be exact. Each implied mode is verified by
evaluating the log-posterior at the mirrored point, and seeded when it
is within |
required |
mode_symmetry_tol
|
float or None
|
Largest difference, in nats, between a symmetry-implied mode's
log-posterior and that of the mode it mirrors for the mirror to be
seeded (the test is on the absolute difference). The mirror reuses its
source's covariance, so under Under |
required |
mode_symmetry_polish_max
|
int or None
|
Maximum number of mirrors |
required |
mode_multistart_nstarts
|
int or None
|
Number of random prior draws used by the |
required |
mode_separation_sigma
|
float
|
How far apart two modes must be, in units of the primary mode's
per-parameter sigma (after Lower it when a real secondary mode sits close to the primary, since at the default such a mode is rejected as a duplicate. Raise it if one broad mode is being split into several. |
required |
mode_weights
|
str
|
How to weight the mixture components when |
required |
smc_kwargs
|
dict or None
|
Configuration for SMC sampling (only used when
Any other keys are forwarded directly to
|
required |
emcee_kwargs
|
dict or None
|
Configuration for
Any other keys are forwarded to |
required |
smc_progress
|
bool
|
If True (default) and |
required |
smc_plot_every
|
int
|
How often to re-render the SMC stats and evolution-and-marginals
figures during sampling, in iterations. |
required |
smc_prior_fraction
|
float
|
Fraction of SMC's initial cloud drawn straight from the prior rather
than from the Laplace mixture, in The mixture can only seed SMC where the mode search looked. SMC begins
at Unlike The cost is proposal quality -- a prior draw is a poor sample of a peaked posterior, so a large fraction wastes particles and slows the early tempering iterations. |
required |
prior_parameters
|
list or None
|
List of parameter names for which initial proposal samples should be replaced with independent draws from the prior. Use this for parameters with wide posteriors consistent with their prior, where the Hessian poorly constrains the proposal covariance. Default is None (no replacement). |
required |
resume
|
bool
|
If True (default) and a resume file exists, load it and continue
from where the previous run left off. The path depends on the
resampling mode: |
required |
checkpoint_signal
|
int or None
|
Optional additional signal number (e.g. |
required |
check_point_delta_t
|
float
|
Periodic in-loop checkpoint interval in seconds (default 600) for the batched resampling modes (rejection / importance / inprior). Set to 0 to disable periodic saves (signal-driven only). SMC uses aspire's per-iteration HDF5 checkpoint instead and is not affected by this kwarg. |
required |
LaplacePosteriorEstimator¶
The engine behind the sampler: MAP finding, posterior precision/covariance estimation, the Laplace evidence, and Gaussian sampling. Useful directly if you want the covariance without running the full sampler.
LaplacePosteriorEstimator ¶
get_MAP_sample ¶
get_MAP_sample(initial_sample=None)
Find the maximum a posteriori (MAP) estimate.
Maximizes log-likelihood + log-prior. With
minimization_method='differential_evolution' (the sampler's
default), uses that global optimizer over the full prior-bounded
space. If initial_sample is provided, a single local minimization
is run from that starting point.
When minimization_method is not 'differential_evolution' and no
initial_sample is given, a multi-start local-optimizer strategy is
used instead: n_prior_samples random prior draws are each used as
starting points for a local optimizer and the best result is returned.
log_evidence_laplace ¶
log_evidence_laplace(sample, covariance)
Laplace approximation to the log evidence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sample
|
dict
|
MAP parameter values. |
required |
covariance
|
array
|
Inverse of the negative Hessian of the log-posterior (the posterior covariance at the MAP). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
log_evidence |
float
|
log Z ≈ log L(θ_MAP) + log π(θ_MAP) + (d/2) log(2π) + (1/2) log det(Σ) |
log_likelihood_from_array ¶
log_likelihood_from_array(x_array, clip_to_bounds=False)
Log-likelihood for one parameter vector or a column-stacked batch.
Accepts (N_params,) or (N_params, N_samples) and returns a
scalar or (N_samples,) respectively. Points outside the prior
support -- either outside a parameter's own range or violating a
Constraint -- return -inf and are never handed to the
likelihood.
clip_to_bounds clips into the per-parameter box. It
cannot rescue a constraint violation: a constraint bounds a derived
quantity, so there is no per-parameter projection onto the allowed
region, and such points still return -inf.
Waveform Fisher matrix¶
The gravitational-wave Fisher route (fisher_method="waveform").
Fisher matrix from gravitational-wave waveform derivatives.
For a bilby GravitationalWaveTransient-like likelihood the Fisher matrix is
F_ij = sum_detectors Re (d_i h | d_j h)
where (a|b) is the noise-weighted inner product and d_i h is the
derivative of the projected detector strain with respect to parameter i.
Unlike the numerical Hessian of the scalar log-likelihood, this is the genuine Fisher matrix: it is positive semi-definite by construction, it needs only first derivatives of the waveform (far better behaved under finite differencing than a scalar second derivative), and it drops the noisy, realization-dependent residual-times-curvature term that makes the observed information indefinite.
Relative-binning likelihoods are supported: they are an approximation to the
full-resolution likelihood, so the full-resolution Fisher is exactly the correct
proposal for them. Their waveform generator returns strain only at the coarse
frequency bin edges during sampling, so _full_resolution_waveforms flips it
to full-grid evaluation for the derivative computation. ROQ and multi-banded
likelihoods remain unsupported (their inner product genuinely differs from the
full-resolution one used here).
waveform_fisher_matrix ¶
waveform_fisher_matrix(likelihood, parameter_names, base_parameters, eps=DEFAULT_EPS, eps_mass=DEFAULT_EPS_MASS, eps_time=DEFAULT_EPS_TIME, bounds=None)
Fisher matrix F_ij = sum_det Re (d_i h | d_j h) via central differences.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
likelihood
|
GravitationalWaveTransient - like
|
Must expose |
required |
parameter_names
|
list of str
|
Parameters to differentiate, defining the basis of the matrix. |
required |
base_parameters
|
dict
|
Full parameter dictionary at the evaluation point (the MAP), including any fixed/derived parameters the waveform and projection require. |
required |
eps
|
float
|
Relative finite-difference steps (mass parameters use |
DEFAULT_EPS
|
eps_mass
|
float
|
Relative finite-difference steps (mass parameters use |
DEFAULT_EPS
|
eps_time
|
float
|
Absolute finite-difference step, in seconds, for time parameters
( |
DEFAULT_EPS_TIME
|
bounds
|
dict
|
|
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
The |
is_gw_waveform_likelihood ¶
is_gw_waveform_likelihood(likelihood)
True if the likelihood exposes interferometers and a waveform generator.
validate_waveform_likelihood ¶
validate_waveform_likelihood(likelihood)
Raise ValueError if the likelihood is unsupported by this path.