Python samplers

AbstractPythonSampler

Supertype for sampling algorithms implemented by a Python package.

Concrete backends are expected to implement python_sample. Loading Gravity does not import any Python sampling package.

AbstractPythonNestedSampler <: AbstractPythonSampler

Supertype for Python nested-sampling backends.

PythonNestedSamplingProblem(logdensity, prior_transform, ndim; kwargs...)

Description of the Julia functions exposed to a Python nested sampler.

logdensity and prior_transform operate on a single parameter vector. Gravity-generated density functions which require their static likelihood data can be used by passing options. A prior transform requiring separate static data can use prior_transform_options. If batch_logdensity or batch_prior_transform is provided, it receives a matrix whose rows are parameter vectors. Otherwise the corresponding scalar function is applied row by row.

Although the field is named logdensity to keep the bridge general, nested samplers normally require a log-likelihood together with a transform from the unit cube to the prior. Passing a log-posterior can change the evidence.

PythonSamplerCallbacks

Python-callable scalar and vectorized functions associated with a PythonNestedSamplingProblem. Construct instances with python_callbacks.

UltraNestSampler(; run_kwargs=(;), kwargs...)

Configuration for the Python ultranest.ReactiveNestedSampler backend.

Extra keyword arguments are passed to the ReactiveNestedSampler constructor. run_kwargs is a NamedTuple of defaults passed to sampler.run. Keywords given directly to python_sample override those defaults.

The backend always enables UltraNest's vectorized mode.

UltraNestResult

Native result of an UltraNest run. result is the dictionary returned by ReactiveNestedSampler.run, and sampler is the Python sampler instance. The callbacks are retained for the lifetime of the result.

NautilusSampler(; run_kwargs=(;), posterior_kwargs=(;), kwargs...)

Configuration for the Python nautilus.Sampler backend.

Extra keywords are passed to its constructor; run_kwargs and posterior_kwargs are passed to run and posterior. The backend always uses a vectorized likelihood and array-valued parameters.

NautilusResult

Result of a Nautilus run. The equal-weight posterior is retained so repeated chain conversions do not perform a new random resampling.

DynestySampler(; dynamic=true, run_kwargs=(;), kwargs...)

Configuration for the Python dynesty backend. By default, dynesty.DynamicNestedSampler is used; set dynamic=false to use dynesty.NestedSampler. Extra keywords are passed to the sampler constructor, and run_kwargs is passed to run_nested.

Dynesty does not expose a vectorized likelihood interface. Gravity supplies a pool adapter which batches direct pool.map calls, including initialization of live points and dynamic batches. Proposal evolution remains serial because concurrent Python calls into Julia are not safe.

DynestyResult

Result of a dynesty run. samples contains the equal-weight posterior, resampled once when sampling finishes. The native sampler, callbacks, and problem are retained.

python_callbacks(problem)

Create the four Python functions used by Python nested-sampling backends: scalar and batched log-density callbacks, and scalar and batched prior-transform callbacks.

NumPy inputs are exposed to Julia as zero-copy PyArray views. Array results are returned as NumPy float64 arrays. A batched input has shape (number_of_points, problem.ndim).

ensure_python_sampler(backend; checkpointing=false)

Ensure that the optional Python distribution required by backend is installed in PythonCall's CondaPkg-managed environment. Missing dependencies are installed automatically. Supported backends are :ultranest, :nautilus, and :dynesty. Nautilus's checkpointing extra is also installed when a checkpoint file is requested.

python_sample(sampler, problem; kwargs...)

Run a Python sampling backend. Concrete sampler implementations add methods to this function.

python_sample(config::UltraNestSampler, problem; kwargs...)

Run vectorized reactive nested sampling with Python UltraNest. Keywords are passed to ReactiveNestedSampler.run and override config.run_kwargs.

python_sample(config::NautilusSampler, problem; kwargs...)

Run vectorized nested sampling with Python Nautilus. Keywords are passed to Sampler.run and override config.run_kwargs.

python_sample(config::DynestySampler, problem; kwargs...)

Run static or dynamic nested sampling with Python dynesty. Keywords are passed to run_nested and override config.run_kwargs.

ultranest_chains(result; include_logdensity=false, logdensity=nothing,
                 logdensity_options=NoPythonSamplerOptions(), start=1, thin=1)

Convert the equally weighted posterior samples in an UltraNestResult to a single MCMCChains.Chains.

If include_logdensity is true, evaluate a Julia log-density once more for all posterior samples and store it as the internal variable :lp. By default this is the density used during sampling. logdensity and logdensity_options can override it, allowing generated Gravity models to sample their log-likelihood but store their log-posterior as :lp. This can be expensive, but enables Gravity utilities such as bestlp.

The UltraNest evidence is stored as chain.logevidence. Evidence uncertainty, iteration and call counts, and effective sample size are stored in chain.info.

nautilus_chains(result; include_logdensity=false, logdensity=nothing,
                logdensity_options=NoPythonSamplerOptions(), start=1, thin=1)

Convert the equal-weight posterior in a NautilusResult to one MCMCChains.Chains. If include_logdensity is true, store a Julia log-density as the internal variable :lp.

dynesty_chains(result; include_logdensity=false, logdensity=nothing,
               logdensity_options=NoPythonSamplerOptions(), start=1, thin=1)

Convert the equal-weight posterior in a DynestyResult to one MCMCChains.Chains. If include_logdensity is true, store a Julia log-density as the internal variable :lp.