ultranest package

Submodules

ultranest.dychmc module

Constrained Hamiltanean Monte Carlo step sampling.

Uses gradient to reflect at nested sampling boundaries.

ultranest.dychmc.stop_criterion(thetaminus, thetaplus, rminus, rplus)

Compute the stop condition in the main loop

computes: dot(dtheta, rminus) >= 0 & dot(dtheta, rplus >= 0)

Parameters

• thetaminus (ndarray[float, ndim=1]) – under position

• thetaplus (ndarray[float, ndim=1]) – above position

• rminus (ndarray[float, ndim=1]) – under momentum

• rplus (ndarray[float, ndim=1]) – above momentum

Returns

criterion – whether the condition is valid

Return type

bool

ultranest.dychmc.step_or_reflect(theta, v, epsilon, transform, loglike, gradient, Lmin)

Make a step from theta towards v with stepsize epsilon.

ultranest.dychmc.build_tree(theta, v, direction, j, epsilon, transform, loglike, gradient, Lmin)

The main recursion.

ultranest.dychmc.tree_sample(theta, p, logL, v, epsilon, transform, loglike, gradient, Lmin, maxheight=inf)

Build NUTS-like tree of sampling path from theta towards p with stepsize epsilon.

ultranest.dychmc.generate_uniform_direction(d, massmatrix)

Draw unit direction vector according to mass matrix.

class ultranest.dychmc.DynamicCHMCSampler(scale, nsteps, adaptive_nsteps=False, delta=0.9, nudge=1.04)

Bases: object

Dynamic Constrained Hamiltonian/Hybrid Monte Carlo technique

Run a billiard ball inside the likelihood constrained. The ball reflects off the constraint.

The trajectory is explored in steps of stepsize epsilon. A No-U-turn criterion and randomized doubling of forward or backward steps is used to avoid repeating circular trajectories. Because of this, the number of steps is dynamic.

Parameters

• nsteps (int) – number of accepted steps until the sample is considered independent.

• adaptive_nsteps (False, 'proposal-distance', 'move-distance') – if not false, allow earlier termination than nsteps. The ‘proposal-distance’ strategy stops when the sum of all proposed vectors exceeds the mean distance between pairs of live points. As distance, the Mahalanobis distance is used. The ‘move-distance’ strategy stops when the distance between start point and current position exceeds the mean distance between pairs of live points.

• delta (float) – step size

• nudge (float) – change in step size, must be >1.

set_gradient(gradient)

plot(filename)

Plot sampler statistics.

move(ui, pi, Li, region, Lmin, ndraw=1, plot=False)

Move from position ui, Li, gradi with a HMC trajectory.

Returns

• unew (vector) – new position in cube space

• pnew (vector) – new position in physical parameter space

• Lnew (float) – new likelihood

• nc (int) – number of likelihood evaluations

• alpha (float) – acceptance rate of trajectory

• treeheight (int) – height of NUTS tree

create_problem(Ls, region)

Set up auxiliary distribution.

Parameters

• Ls (array of floats) – live point likelihoods

• region (MLFriends region object) – region.transformLayer is used to obtain mass matrices

adjust_stepsize()

Store chain statistics and adapt proposal.

region_changed(Ls, region)

React to change of region.

adjust_nsteps(region, history)

ultranest.dyhmc module

Experimental constrained Hamiltanean Monte Carlo step sampling

Contrary to CHMC, this uses the likelihood gradients throughout the path. A helper surface is created using the live points.

ultranest.dyhmc.stop_criterion(thetaminus, thetaplus, rminus, rplus)

Compute the stop condition in the main loop dot(dtheta, rminus) >= 0 & dot(dtheta, rplus >= 0)

Parameters

• thetaminus (ndarray[float, ndim=1]) – under position

• thetaplus (ndarray[float, ndim=1]) – above position

• rminus (ndarray[float, ndim=1]) – under momentum

• rplus (ndarray[float, ndim=1]) – above momentum

Returns

criterion – whether the condition is valid

Return type

bool

ultranest.dyhmc.leapfrog(theta, r, grad, epsilon, invmassmatrix, f)

Leap frog step from theta with momentum r and stepsize epsilon. The local gradient grad is updated with function f

ultranest.dyhmc.build_tree(theta, r, grad, v, j, epsilon, invmassmatrix, f, joint0)

The main recursion.

ultranest.dyhmc.tree_sample(theta, logp, r0, grad, extra, epsilon, invmassmatrix, f, joint, maxheight=inf)

Build NUTS-like tree of sampling path from theta towards p with stepsize epsilon.

ultranest.dyhmc.find_beta_params_static(d, u10)

Define auxiliary distribution following naive intuition. Make 50% quantile to be at u=0.1, and very flat at high u.

ultranest.dyhmc.find_beta_params_dynamic(d, u10)

Define auxiliary distribution taking into account kinetic energy of a d-dimensional HMC. Make exp(-d/2) quantile to be at u=0.1, and 95% quantile at u=0.5.

ultranest.dyhmc.generate_momentum_normal(d, massmatrix)

draw direction vector according to mass matrix

ultranest.dyhmc.generate_momentum(d, massmatrix, alpha, beta)

draw momentum from a circle, with amplitude following the beta distribution

ultranest.dyhmc.generate_momentum_circle(d, massmatrix)

draw from a circle, with a little noise in amplitude

ultranest.dyhmc.generate_momentum_flattened(d, massmatrix)

like normal distribution, but make momenta distributed like a single gaussian. this is the one being used

class ultranest.dyhmc.FlattenedProblem(d, Ls, function, layer)

Bases: object

Creates a suitable auxiliary distribution from samples of likelihood values

The distribution is the CDF of a beta distribution, with 0 -> logLmin 1 -> 90% quantile of logLs 0.5 -> 10% quantile of logLs

.modify_Lgrad() returns the conversion from logL, grad to the equivalents on the auxiliary distribution.

.__call__(x) returns logL, grad on the auxiliary distribution.

modify_Lgrad(L, grad)

generate_momentum()

class ultranest.dyhmc.DynamicHMCSampler(ndim, nsteps, transform_loglike_gradient, delta=0.9, nudge=1.04)

Bases: object

Dynamic Hamiltonian/Hybrid Monte Carlo technique

Typically, HMC operates on the posterior. It has the benefit of producing “orbit” trajectories, that can follow the guidance of gradients.

In nested sampling, we need to sample the prior subject to the likelihood constraint. This means a HMC would most of the time go in straight lines, until it steps outside the boundary. Techniques such as Constrained HMC and Galilean MC use the gradient outside to select the reflection direction.

However, it would be beneficial to be repelled by the likelihood boundary, and to take advantage of gradient guidance. This implements a new technique that does this.

The trick is to define a auxiliary distribution from the likelihood, generate HMC trajectories from it, and draw points from the trajectory with inverse the probability of the auxiliary distribution to sample from the prior. Thus, the auxiliary distribution should be mostly flat, and go to zero at the boundaries to repell the HMC.

Given Lmin and Lmax from the live points, use a beta approximation of log-likelihood

p=1 if L>Lmin u = (L - Lmin) / (Lmax - Lmin) p = Beta_PDF(u; alpha, beta)

then define

d log(p) / dx = dlog(p_orig)/dlog(p) * dlog(p_orig) / dx new gradient = conversion * original gradient

with conversion

dlogp/du = 0 if u>1; otherwise: dlogp/du = u**(1-alpha) * (1-u)**(1-beta) / Ic(u; alpha, beta) / Beta_PDF(u, alpha, beta) du/dL = 1 / (Lmax - Lmin)

The beta distribution achieves: * a flattening of the loglikelihood to avoid seeing only “walls” * using the gradient to identify how to orbit the likelihood contour * at higher, unseen likelihoods, the exploration is in straight lines * trajectory do not have the energy to go below Lmin. * alpha and beta parameters allow flexible choice of “contour avoidance”

Run HMC trajectory on p This will draw samples proportional to p Modify multinomial acceptance by 1/p to get uniform samples. and reject porig < p_1

The remaining choices for HMC are how long the trajectories should run (number of steps) and the step size. The former is solved by No-U-Turn Sampler or dynamic HMC, which randomly build forward and backward paths until the trajectory turns around. Then, a random point from the trajectory is chosen.

The step size is chosen by targeting an acceptance rate of delta~0.95, and decreasing(increasing) every time the region is rebuilt if the acceptance rate is below(above).

Initialise sampler.

Parameters

• nsteps (int) – number of accepted steps until the sample is considered independent.

• transform_loglike_gradient (function) – called with unit cube position vector u, returns transformed parameter vector p, loglikelihood and gradient (dlogL/du, not just dlogL/dp)

plot(filename)

Plot sampler statistics.

move(ui, pi, Li, gradi, region, ndraw=1, Lflat=None, gradflat=None, plot=False)

Move from position ui, Li, gradi with a HMC trajectory.

Returns

• unew (vector) – new position in cube space

• pnew (vector) – new position in physical parameter space

• Lnew (float) – new likelihood

• gradnew (vector) – new gradient

• Lflat (float) – new likelihood on auxiliary distribution

• gradflat (vector) – new gradient on auxiliary distribution

• nc (int) – number of likelihood evaluations

• alpha (float) – acceptance rate of HMC trajectory

• beta (float) – acceptance rate of inverse-beta-biased HMC trajectory

create_problem(Ls, region)

Set up auxiliary distribution.

Parameters

• Ls (array of floats) – live point likelihoods

• region (MLFriends region object) – region.transformLayer is used to obtain mass matrices

adjust_stepsize()

region_changed(Ls, region)

ultranest.flatnuts module

FLATNUTS is a implementation of No-U-turn sampler for nested sampling assuming a flat prior space (hyper-cube u-space).

This is highly experimental. It is similar to NoGUTS and suffers from the same stability problems.

Directional sampling within regions.

Work in unit cube space. assume a step size.

1. starting from a live point

2. choose a random direction based on whitened space metric

3. for forward and backward direction:

1. find distance where leaving spheres (surely outside)

2. bisect the step that leads out of the likelihood threshold

3. can we scatter forward?

   • if we stepped outside the unit cube, use normal to the parameter(s) we stepped out from

   • if gradient available, use it at first outside point

   • for each sphere that contains the last inside point:

     • resize so that first outside point is on the surface, get tangential vector there (this vector is just the difference between sphere center and last inside point)

     • compute reflection of direction vector with tangential plane

   • choose a forward reflection at random (if any)

3.4) test if next point is inside again. If yes, continue NUTS

NUTS:

• alternatingly double the number of steps to the forward or backward side

• build a tree; terminate when start and end directions are not forward any more

• choose a end point at random out of the sequence

If the number of steps on any straight line is <10 steps, make step size smaller If the number of steps on any straight line is >100 steps, make step size slightly bigger

param - Number of NUTS tracks

type - Number of NUTS tracks

has to be user-tuned to ensure sufficiently independent samples; starting from 1, look when Z does not change anymore

param - Step size

type - Step size

self-adjusting

Benefit of this algorithm:

• insensitive to step size

• insensitive to dimensionality (sqrt scaling), better than slice sampling

• takes advantage of region information, can accelerate low-d problems as well

Drawbacks:

• inaccurate reflections degrade dimensionality scaling

• more complex to implement than slice sampling

class ultranest.flatnuts.SingleJumper(stepsampler, nsteps=0)

Bases: object

Jump on step at a time. If unsuccessful, reverse direction.

prepare_jump()

check_gaps(gaps)

make_jump(gaps={})

class ultranest.flatnuts.DirectJumper(stepsampler, nsteps, log=False)

Bases: object

Jump to n steps immediately. If unsuccessful, takes rest in other direction.

prepare_jump()

check_gaps(gaps)

make_jump(gaps={})

class ultranest.flatnuts.IntervalJumper(stepsampler, nsteps)

Bases: object

Use interval to choose final point randomly

prepare_jump()

make_jump()

class ultranest.flatnuts.ClockedSimpleStepSampler(contourpath, plot=False, log=False)

Bases: object

Find a new point with a series of small steps

Starts a sampling track from x in direction v. is_inside is a function that returns true when a given point is inside the volume

epsilon gives the step size in direction v. samples, if given, helps choose the gradient – To be removed plot: if set to true, make some debug plots

reset()

reverse(reflpoint, v, plot=False)

Reflect off the surface at reflpoint going in direction v

returns the new direction.

set_nsteps(i)

is_done()

expand_onestep(fwd, transform, loglike, Lmin)

Helper interface, make one step (forward fwd=True or backward fwd=False)

expand_to_step(nsteps, transform, loglike, Lmin)

Helper interface, go to step nstep

get_independent_sample(transform, loglike, Lmin)

Helper interface, call next() until a independent sample is returned

class ultranest.flatnuts.ClockedStepSampler(contourpath, plot=False, log=False)

Bases: ClockedSimpleStepSampler

Find a new point with a series of small steps

Starts a sampling track from x in direction v. is_inside is a function that returns true when a given point is inside the volume

epsilon gives the step size in direction v. samples, if given, helps choose the gradient – To be removed plot: if set to true, make some debug plots

continue_sampling(i)

expand_to(i)

eval_at(j, xj, v, sign, Llast)

reflect_at(j, xk, vk, sign, Llast)

next(Llast=None)

Run steps forward or backward to step i (can be positive or negative, 0 is the starting point)

class ultranest.flatnuts.ClockedBisectSampler(contourpath, plot=False, log=False)

Bases: ClockedStepSampler

Step sampler that does not require each step to be evaluated

Starts a sampling track from x in direction v. is_inside is a function that returns true when a given point is inside the volume

epsilon gives the step size in direction v. samples, if given, helps choose the gradient – To be removed plot: if set to true, make some debug plots

continue_sampling(i)

expand_to(j)

bisect_at(lefti, leftx, leftv, midi, midx, midv, righti, rightx, rightv, sign, Llast)

next(Llast=None)

Run steps forward or backward to step i (can be positive or negative, 0 is the starting point)

class ultranest.flatnuts.ClockedNUTSSampler(contourpath, plot=False, log=False)

Bases: ClockedBisectSampler

No-U-turn sampler (NUTS) on flat surfaces.

Starts a sampling track from x in direction v. is_inside is a function that returns true when a given point is inside the volume

epsilon gives the step size in direction v. samples, if given, helps choose the gradient – To be removed plot: if set to true, make some debug plots

reset()

next(Llast=None)

Alternatingly doubles the number of steps to forward and backward direction (which may include reflections, see StepSampler and BisectSampler). When track returns (start and end of tree point toward each other), terminates and returns a random point on that track.

sample_chain_point(a, b)

Gets a point on the track between a and b (inclusive).

Parameters

• a (array) – starting point

• b (array) – end point

Returns

• newpoint (tuple) – tuple of point_coordinates and loglikelihood

• is_independent (bool) – always True

build_tree(startstate, j, rwd)

Build sub-trees of depth j in direction rwd

startstate: (i, x, v) state information of first node j: int height of the tree rwd: bool whether we go backward

ultranest.hotstart module

Warm start and hot start helper functions.

ultranest.hotstart.get_auxiliary_problem(loglike, transform, ctr, invcov, enlargement_factor, df=1)

Return a new loglike and transform based on an auxiliary distribution.

Given a likelihood and prior transform, and information about the (expected) posterior peak, generates a auxiliary likelihood and prior transform that is identical but requires fewer nested sampling iterations.

This is achieved by deforming the prior space, and undoing that transformation by correction weights in the likelihood.

The auxiliary distribution used for transformation/weighting is a d-dimensional Student-t distribution.

Usage:

aux_loglikelihood, aux_aftertransform = get_auxiliary_problem(loglike, transform, ctr, invcov, enlargement_factor, df=1)
aux_sampler = ReactiveNestedSampler(parameters, aux_loglikelihood)
aux_results = aux_sampler.run()
posterior_samples = [aux_aftertransform(sample) for sample in aux_results['samples']]

Parameters

• loglike (function) – original likelihood function

• transform (function) – original prior transform function

• ctr (array) – Posterior center (in u-space).

• invcov (array) – Covariance of the posterior (in u-space).

• enlargement_factor (float) –

  Factor by which the scale of the auxiliary distribution is enlarged in all dimensions.

  For Gaussian-like posteriors, sqrt(ndim) seems to work, Heavier tailed or non-elliptical distributions may need larger factors.

• df (float) – Number of degrees of freedom of the auxiliary student-t distribution. The default is recommended. For truly gaussian posteriors, the student-t can be made more gaussian (by df>=30) for accelation.

Returns

• aux_loglike (function) – auxiliary loglikelihood function.

• aux_aftertransform (function) – auxiliary transform function. Takes d u-space coordinates, and returns d + 1 p-space parameters. The first d return coordinates are identical to what transform would return. The final coordinate is the correction weight.

ultranest.hotstart.get_extended_auxiliary_problem(loglike, transform, ctr, invcov, enlargement_factor, df=1)

Return a new loglike and transform based on an auxiliary distribution.

Given a likelihood and prior transform, and information about the (expected) posterior peak, generates a auxiliary likelihood and prior transform that is identical but requires fewer nested sampling iterations.

This is achieved by deforming the prior space, and undoing that transformation by correction weights in the likelihood.

The auxiliary distribution used for transformation/weighting is a d-dimensional Student-t distribution.

Parameters

• loglike (function) – original likelihood function

• transform (function) – original prior transform function

• ctr (array) – Posterior center (in u-space).

• invcov (array) – Covariance of the posterior (in u-space).

• enlargement_factor (float) –

  Factor by which the scale of the auxiliary distribution is enlarged in all dimensions.

  For Gaussian-like posteriors, sqrt(ndim) seems to work, Heavier tailed or non-elliptical distributions may need larger factors.

• df (float) – Number of degrees of freedom of the auxiliary student-t distribution. The default is recommended. For truly gaussian posteriors, the student-t can be made more gaussian (by df>=30) for accelation.

Returns

• aux_loglike (function) – auxiliary loglikelihood function. Takes d + 1 parameters (see below). The likelihood is the same as loglike, but adds weights.

• aux_transform (function) – auxiliary transform function. Takes d u-space coordinates, and returns d + 1 p-space parameters. The first d return coordinates are identical to what transform would return. The final coordinate is the correction weight.

ultranest.hotstart.get_extended_auxiliary_independent_problem(loglike, transform, ctr, err, df=1)

Return a new loglike and transform based on an auxiliary distribution.

Given a likelihood and prior transform, and information about the (expected) posterior peak, generates a auxiliary likelihood and prior transform that is identical but requires fewer nested sampling iterations.

This is achieved by deforming the prior space, and undoing that transformation by correction weights in the likelihood.

The auxiliary distribution used for transformation/weighting is a independent Student-t distribution for each parameter.

Usage:

aux_loglikelihood, aux_transform = get_auxiliary_problem(loglike, transform, ctr, invcov, enlargement_factor, df=1)
aux_sampler = ReactiveNestedSampler(parameters, aux_loglikelihood, transform=aux_transform, derived_param_names=['logweight'])
aux_results = aux_sampler.run()
posterior_samples = aux_results['samples'][:,-1]

Parameters

• loglike (function) – original likelihood function

• transform (function) – original prior transform function

• ctr (array) – Posterior center (in u-space).

• err (array) – Standard deviation around the posterior center (in u-space).

• df (float) – Number of degrees of freedom of the auxiliary student-t distribution. The default is recommended. For truly gaussian posteriors, the student-t can be made more gaussian (by df>=30) for accelation.

Returns

• aux_loglike (function) – auxiliary loglikelihood function.

• aux_transform (function) – auxiliary transform function. Takes d u-space coordinates, and returns d + 1 p-space parameters. The first d return coordinates are identical to what transform would return. The final coordinate is the log of the correction weight.

ultranest.hotstart.compute_quantile_intervals(steps, upoints, uweights)

Compute lower and upper axis quantiles.

Parameters

• steps (array) – list of quantiles q to compute.

• upoints (array) – samples, with dimensions (N, d)

• uweights (array) – sample weights

Returns

• ulo (array) – list of lower quantiles (at q), one entry for each dimension d.

• uhi (array) – list of upper quantiles (at 1-q), one entry for each dimension d.

ultranest.hotstart.compute_quantile_intervals_refined(steps, upoints, uweights, logsteps_max=20)

Compute lower and upper axis quantiles.

Parameters

• steps (array) – list of quantiles q to compute, with dimensions

• upoints (array) – samples, with dimensions (N, d)

• uweights (array) – sample weights. N entries.

• logsteps_max (int) – number of intermediate steps to inject between largest quantiles interval and full unit cube

Returns

• ulo (array) – list of lower quantiles (at q), of shape (M, d), one entry per quantile and dimension d.

• uhi (array) – list of upper quantiles (at 1-q), of shape (M, d), one entry per quantile and dimension d.

• uinterpspace (array) – list of steps (length of steps plus logsteps_max long)

ultranest.hotstart.get_auxiliary_contbox_parameterization(param_names, loglike, transform, upoints, uweights, vectorized=False)

Return a new loglike and transform based on an auxiliary distribution.

Given a likelihood and prior transform, and information about the (expected) posterior peak, generates a auxiliary likelihood and prior transform that is identical but requires fewer nested sampling iterations.

This is achieved by deforming the prior space, and undoing that transformation by correction weights in the likelihood. A additional parameter, “aux_logweight”, is added at the end, which contains the correction weight. You can ignore it.

The auxiliary distribution used for transformation/weighting is factorized. Each axis considers the ECDF of the auxiliary samples, and segments it into quantile segments. Within each segment, the parameter edges in u-space are linearly interpolated. To see the interpolation quantiles for each axis, use:

steps = 10**-(1.0 * np.arange(1, 8, 2))
ulos, uhis, uinterpspace = compute_quantile_intervals_refined(steps, upoints, uweights)

Parameters

• param_names (list) – parameter names

• loglike (function) – original likelihood function

• transform (function) – original prior transform function

• upoints (array) – Posterior samples (in u-space).

• uweights (array) – Weights of samples (needs to sum of 1)

• vectorized (bool) – whether the loglike & transform functions are vectorized

Returns

• aux_param_names (list) – new parameter names (param_names) plus additional ‘aux_logweight’

• aux_loglike (function) – auxiliary loglikelihood function.

• aux_transform (function) – auxiliary transform function. Takes d u-space coordinates, and returns d + 1 p-space parameters. The first d return coordinates are identical to what transform would return. The final coordinate is the log of the correction weight.

• vectorized (bool) – whether the returned functions are vectorized

• Usage

• ——

• :: –

  aux_loglikelihood, aux_transform = get_auxiliary_contbox_parameterization(

  loglike, transform, auxiliary_usamples)

  aux_sampler = ReactiveNestedSampler(parameters, aux_loglikelihood, transform=aux_transform, derived_param_names=[‘logweight’]) aux_results = aux_sampler.run() posterior_samples = aux_results[‘samples’][:,-1]

ultranest.hotstart.reuse_samples(param_names, loglike, points, logl, logw=None, logz=0.0, logzerr=0.0, upoints=None, batchsize=128, vectorized=False, log_weight_threshold=-10, **kwargs)

Reweight existing nested sampling run onto a new loglikelihood.

Parameters

• param_names (list of strings) – Names of the parameters

• loglike (function) – New likelihood function

• points (np.array of shape (npoints, ndim)) – Equally weighted (unless logw is passed) posterior points

• logl (np.array(npoints)) – Previously likelihood values of points

• logw (np.array(npoints)) – Log-weights of existing points.

• logz (float) – Previous evidence / marginal likelihood value.

• logzerr (float) – Previous evidence / marginal likelihood uncertainty.

• upoints (np.array of shape (npoints, ndim)) – Posterior points before transformation.

• vectorized (bool) – Whether loglike function is vectorized

• batchsize (int) – Number of points simultaneously passed to vectorized loglike function

• log_weight_threshold (float) – Lowest log-weight to consider

Returns

results – All information of the run. Important keys: Number of nested sampling iterations (niter), Evidence estimate (logz), Effective Sample Size (ess), weighted samples (weighted_samples), equally weighted samples (samples), best-fit point information (maximum_likelihood), posterior summaries (posterior).

Return type

dict

ultranest.integrator module

Ultranest calculates the Bayesian evidence and posterior samples of arbitrary models.

class ultranest.integrator.ReactiveNestedSampler(param_names, loglike, transform=None, derived_param_names=[], wrapped_params=None, resume='subfolder', run_num=None, log_dir=None, num_test_samples=2, draw_multiple=True, num_bootstraps=30, vectorized=False, ndraw_min=128, ndraw_max=65536, storage_backend='hdf5', warmstart_max_tau=-1)

Bases: object

Nested sampler with reactive exploration strategy.

Storage & resume capable, optionally MPI parallelised.

Initialise nested sampler.

Parameters

• param_names (list of str, names of the parameters.) – Length gives dimensionality of the sampling problem.

• loglike (function) – log-likelihood function. Receives multiple parameter vectors, returns vector of likelihood.

• transform (function) – parameter transform from unit cube to physical parameters. Receives multiple cube vectors, returns multiple parameter vectors.

• derived_param_names (list of str) – Additional derived parameters created by transform. (empty by default)

• log_dir (str) – where to store output files

• resume ('resume', 'resume-similar', 'overwrite' or 'subfolder') –

  if ‘overwrite’, overwrite previous data.

  if ‘subfolder’, create a fresh subdirectory in log_dir.

  if ‘resume’ or True, continue previous run if available. Only works when dimensionality, transform or likelihood are consistent.

  if ‘resume-similar’, continue previous run if available. Only works when dimensionality and transform are consistent. If a likelihood difference is detected, the existing likelihoods are updated until the live point order differs. Otherwise, behaves like resume.

• run_num (int or None) – If resume==’subfolder’, this is the subfolder number. Automatically increments if set to None.

• wrapped_params (list of bools) – indicating whether this parameter wraps around (circular parameter).

• num_test_samples (int) – test transform and likelihood with this number of random points for errors first. Useful to catch bugs.

• vectorized (bool) – If true, loglike and transform function can receive arrays of points.

• draw_multiple (bool) – If efficiency goes down, dynamically draw more points from the region between ndraw_min and ndraw_max. If set to False, few points are sampled at once.

• ndraw_min (int) – Minimum number of points to simultaneously propose. Increase this if your likelihood makes vectorization very cheap.

• ndraw_max (int) – Maximum number of points to simultaneously propose. Increase this if your likelihood makes vectorization very cheap. Memory allocation may be slow for extremely high values.

• num_bootstraps (int) – number of logZ estimators and MLFriends region bootstrap rounds.

• storage_backend (str or class) – Class to use for storing the evaluated points (see ultranest.store) ‘hdf5’ is strongly recommended. ‘tsv’ and ‘csv’ are also possible.

• warmstart_max_tau (float) – Maximum disorder to accept when resume=’resume-similar’; Live points are reused as long as the live point order is below this normalised Kendall tau distance. Values from 0 (highly conservative) to 1 (extremely negligent).

run(update_interval_volume_fraction=0.8, update_interval_ncall=None, log_interval=None, show_status=True, viz_callback='auto', dlogz=0.5, dKL=0.5, frac_remain=0.01, Lepsilon=0.001, min_ess=400, max_iters=None, max_ncalls=None, max_num_improvement_loops=-1, min_num_live_points=400, cluster_num_live_points=40, insertion_test_window=10, insertion_test_zscore_threshold=4, region_class=<class 'ultranest.mlfriends.MLFriends'>)

Run until target convergence criteria are fulfilled.

Parameters

• update_interval_volume_fraction (float) – Update region when the volume shrunk by this amount.

• update_interval_ncall (int) – Update region after update_interval_ncall likelihood calls (not used).

• log_interval (int) – Update stdout status line every log_interval iterations

• show_status (bool) – show integration progress as a status line. If no output desired, set to False.

• viz_callback (function) – callback function when region was rebuilt. Allows to show current state of the live points. See nicelogger() or LivePointsWidget. If no output desired, set to False.

• dlogz (float) – Target evidence uncertainty. This is the std between bootstrapped logz integrators.

• dKL (float) – Target posterior uncertainty. This is the Kullback-Leibler divergence in nat between bootstrapped integrators.

• frac_remain (float) – Integrate until this fraction of the integral is left in the remainder. Set to a low number (1e-2 … 1e-5) to make sure peaks are discovered. Set to a higher number (0.5) if you know the posterior is simple.

• Lepsilon (float) – Terminate when live point likelihoods are all the same, within Lepsilon tolerance. Increase this when your likelihood function is inaccurate, to avoid unnecessary search.

• min_ess (int) – Target number of effective posterior samples.

• max_iters (int) – maximum number of integration iterations.

• max_ncalls (int) – stop after this many likelihood evaluations.

• max_num_improvement_loops (int) – run() tries to assess iteratively where more samples are needed. This number limits the number of improvement loops.

• min_num_live_points (int) – minimum number of live points throughout the run

• cluster_num_live_points (int) – require at least this many live points per detected cluster

• insertion_test_zscore_threshold (float) – z-score used as a threshold for the insertion order test. Set to infinity to disable.

• insertion_test_window (int) – Number of iterations after which the insertion order test is reset.

• region_class (MLFriends or RobustEllipsoidRegion or SimpleRegion) – Whether to use MLFriends+ellipsoidal+tellipsoidal region (better for multi-modal problems) or just ellipsoidal sampling (faster for high-dimensional, gaussian-like problems) or a axis-aligned ellipsoid (fastest, to be combined with slice sampling).

run_iter(update_interval_volume_fraction=0.8, update_interval_ncall=None, log_interval=None, dlogz=0.5, dKL=0.5, frac_remain=0.01, Lepsilon=0.001, min_ess=400, max_iters=None, max_ncalls=None, max_num_improvement_loops=-1, min_num_live_points=400, cluster_num_live_points=40, show_status=True, viz_callback='auto', insertion_test_window=10000, insertion_test_zscore_threshold=2, region_class=<class 'ultranest.mlfriends.MLFriends'>)

Iterate towards convergence.

Use as an iterator like so:

for result in sampler.run_iter(...):
    print('lnZ = %(logz).2f +- %(logzerr).2f' % result)

Parameters as described in run() method.

Yields

results (dict)

store_tree()

Store tree to disk (results/tree.hdf5).

print_results(use_unicode=True)

Give summary of marginal likelihood and parameter posteriors.

Parameters

use_unicode (bool) – Whether to print a unicode plot of the posterior distributions

plot()

Make corner, run and trace plots.

calls:

• plot_corner()

• plot_run()

• plot_trace()

plot_corner()

Make corner plot.

Writes corner plot to plots/ directory if log directory was specified, otherwise show interactively.

This does essentially:

from ultranest.plot import cornerplot
cornerplot(results)

plot_trace()

Make trace plot.

Write parameter trace diagnostic plots to plots/ directory if log directory specified, otherwise show interactively.

This does essentially:

from ultranest.plot import traceplot
traceplot(results=results, labels=paramnames + derivedparamnames)

plot_run()

Make run plot.

Write run diagnostic plots to plots/ directory if log directory specified, otherwise show interactively.

This does essentially:

from ultranest.plot import runplot
runplot(results=results)

class ultranest.integrator.NestedSampler(param_names, loglike, transform=None, derived_param_names=[], resume='subfolder', run_num=None, log_dir='logs/test', num_live_points=1000, vectorized=False, wrapped_params=[])

Bases: object

Simple Nested sampler for reference.

Set up nested sampler.

Parameters

• param_names (list of str, names of the parameters.) – Length gives dimensionality of the sampling problem.

• loglike (function) – log-likelihood function. Receives multiple parameter vectors, returns vector of likelihood.

• transform (function) – parameter transform from unit cube to physical parameters. Receives multiple cube vectors, returns multiple parameter vectors.

• derived_param_names (list of str) – Additional derived parameters created by transform. (empty by default)

• log_dir (str) – where to store output files

• resume ('resume', 'overwrite' or 'subfolder') – if ‘overwrite’, overwrite previous data. if ‘subfolder’, create a fresh subdirectory in log_dir. if ‘resume’ or True, continue previous run if available.

• wrapped_params (list of bools) – indicating whether this parameter wraps around (circular parameter).

• num_live_points (int) – Number of live points

• vectorized (bool) – If true, loglike and transform function can receive arrays of points.

• run_num (int) – unique run number. If None, will be automatically incremented.

run(update_interval_iter=None, update_interval_ncall=None, log_interval=None, dlogz=0.001, max_iters=None)

Explore parameter space.

Parameters

• update_interval_iter – Update region after this many iterations.

• update_interval_ncall – Update region after update_interval_ncall likelihood calls.

• log_interval – Update stdout status line every log_interval iterations

• dlogz – Target evidence uncertainty.

• max_iters – maximum number of integration iterations.

print_results()

Give summary of marginal likelihood and parameters.

plot()

Make corner plot.

ultranest.integrator.read_file(log_dir, x_dim, num_bootstraps=20, random=True, verbose=False, check_insertion_order=True)

Read the output HDF5 file of UltraNest.

Parameters

• log_dir (str) – Folder containing results

• x_dim (int) – number of dimensions

• num_bootstraps (int) – number of bootstraps to use for estimating logZ.

• random (bool) – use randomization for volume estimation.

• verbose (bool) – show progress

• check_insertion_order (bool) – whether to perform MWW insertion order test for assessing convergence

Returns

• sequence (dict) –

  contains arrays storing for each iteration estimates of:

  • logz: log evidence estimate

  • logzerr: log evidence uncertainty estimate

  • logvol: log volume estimate

  • samples_n: number of live points

  • logwt: log weight

  • logl: log likelihood

• final (dict) – same as ReactiveNestedSampler.results and ReactiveNestedSampler.run return values

ultranest.integrator.warmstart_from_similar_file(usample_filename, param_names, loglike, transform, vectorized=False, min_num_samples=50)

Warmstart from a previous run.

Usage:

aux_paramnames, aux_log_likelihood, aux_prior_transform, vectorized = warmstart_from_similar_file(
    'model1/chains/weighted_post_untransformed.txt', parameters, log_likelihood_with_background, prior_transform)

aux_sampler = ReactiveNestedSampler(aux_paramnames, aux_log_likelihood, transform=aux_prior_transform,vectorized=vectorized)
aux_sampler.run()
posterior_samples = aux_results['samples'][:,-1]

See ultranest.hotstart.get_auxiliary_contbox_parameterization() for more information.

The remaining parameters have the same meaning as in ReactiveNestedSampler.

Parameters

• usample_filename (str) – ‘directory/chains/weighted_post_untransformed.txt’ contains posteriors in u-space (untransformed) of a previous run. Columns are weight, logl, param1, param2, …

• min_num_samples (int) – minimum number of samples in the usample_filename file required. Too few samples will give a poor approximation.

• param_names (list) –

• loglike (function) –

• transform (function) –

• vectorized (bool) –

Returns

• aux_param_names (list) – new parameter list

• aux_loglikelihood (function) – new loglikelihood function

• aux_transform (function) – new prior transform function

• vectorized (bool) – whether the new functions are vectorized

ultranest.mlfriends module

Construct and sample from region.

Implements MLFriends efficiently, with transformation layers and clustering.

class ultranest.mlfriends.AffineLayer(ctr=0, T=1, invT=1, nclusters=1, wrapped_dims=[], clusterids=None)

Bases: ScalingLayer

Affine whitening transformation.

Learns the covariance of points.

Initialise layer.

The parameters are optional and can be learned from points with optimize()

Parameters

• ctr (vector) – Center of points

• T (matrix) – transformation matrix

• invT (matrix) – inverse transformation matrix

• nclusters (int) – number of clusters

• wrapped_dims (array of bools) – indicates which parameter axes are circular.

• clusterids (array of int) – cluster id for each point

create_new(upoints, maxradiussq, minvol=0.0)

Learn next layer from this optimized layer’s clustering.

Parameters

• upoints (array) – points to use for optimize (in u-space)

• maxradiussq (float) – square of the MLFriends radius

• minvol (float) – Minimum volume to regularize sample covariance

Return type

A new, optimized AffineLayer.

optimize(points, centered_points, clusterids=None, minvol=0.0)

Optimize layer.

Estimates covariance of centered_points. minvol sets the smallest allowed size of the covariance to avoid numerical collapse.

Parameters

• points (array) – points to use for optimize (in u-space)

• centered_points (array) – points with their cluster center subtracted

• clusterids (array of ints) – for each point, which cluster they belong to

• minvol (float) – Minimum volume to regularize sample covariance

transform(u)

Transform points from cube space to a whitened space.

untransform(ww)

Transform points from whitened space back to cube space.

class ultranest.mlfriends.MLFriends(u, transformLayer)

Bases: object

MLFriends region.

Defines a region around nested sampling live points for

1. checking whether a proposed point likely also fulfills the likelihood constraints

2. proposing new points.

Learns geometry of region from existing live points.

Initialise region.

Parameters

• u (array of vectors) – live points

• transformLayer (ScalingLayer or AffineLayer) – whitening layer

compute_enlargement(nbootstraps=50, minvol=0.0, rng=<module 'numpy.random' from '/home/user/.local/lib/python3.10/site-packages/numpy/random/__init__.py'>)

Return MLFriends radius and ellipsoid enlargement using bootstrapping.

The wrapping ellipsoid covariance is determined in each bootstrap round.

Parameters

• nbootstraps (int) – number of bootstrapping rounds

• minvol (float) – minimum volume to enforce to wrapping ellipsoid

• rng – random number generator

Returns

• max_distance (float) – square radius of MLFriends algorithm

• max_radius (float) – square radius of enclosing ellipsoid.

compute_maxradiussq(nbootstraps=50)

Run MLFriends bootstrapping

Parameters

nbootstraps (int) – number of bootstrapping rounds

Return type

square radius that safely encloses all live points.

compute_mean_pair_distance()

create_ellipsoid(minvol=0.0)

Create wrapping ellipsoid and store its center and covariance.

Parameters

minvol (float) – If positive, make sure ellipsoid has at least this volume.

estimate_volume()

Estimate the order of magnitude of the volume around a single point given the current transformLayer.

Does not account for: * the number of live points * their overlap * the intersection with the unit cube borders

Returns

volume – Volume

Return type

float

inside(pts)

Check if inside region.

Parameters

pts (array of vectors) – Points to check

Returns

is_inside – True if inside MLFriends region and wrapping ellipsoid, for each point in pts.

Return type

array of bools

inside_ellipsoid(u)

Check if inside wrapping ellipsoid.

Parameters

u (array of vectors) – Points to check

Returns

is_inside – True if inside wrapping ellipsoid, for each point in pts.

Return type

array of bools

sample(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Switches automatically between the sampling_methods (attribute).

Parameters

nsamples (int) – number of samples to draw

Returns

• samples (array of shape (nsamples, dimension)) – samples drawn

• idx (array of integers (nsamples)) – index of a point nearby (MLFriends.u)

sample_from_boundingbox(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Draws uniformly from bounding box around region.

Parameters as described in sample().

sample_from_points(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Chooses randomly from points and their ellipsoids.

Parameters as described in sample().

sample_from_transformed_boundingbox(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Draws uniformly from bounding box around region (in whitened space).

Parameters as described in sample().

sample_from_wrapping_ellipsoid(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Draws uniformly from wrapping ellipsoid and filters with region.

Parameters as described in sample().

set_transformLayer(transformLayer)

Update transformation layer. Invalidates attribute maxradius.

Parameters

transformLayer (ScalingLayer or AffineLayer) – t-space transformation layer

class ultranest.mlfriends.RobustEllipsoidRegion(u, transformLayer)

Bases: MLFriends

Ellipsoidal region.

Defines a region around nested sampling live points for

1. checking whether a proposed point likely also fulfills the likelihood constraints

2. proposing new points.

Learns geometry of region from existing live points.

Initialise region.

Parameters

• u (array of vectors) – live points

• transformLayer (ScalingLayer or AffineLayer) – whitening layer

compute_enlargement(nbootstraps=50, minvol=0.0, rng=<module 'numpy.random' from '/home/user/.local/lib/python3.10/site-packages/numpy/random/__init__.py'>)

Return MLFriends radius and ellipsoid enlargement using bootstrapping.

The wrapping ellipsoid covariance is determined in each bootstrap round.

Parameters

• nbootstraps (int) – number of bootstrapping rounds

• minvol (float) – minimum volume to enforce to wrapping ellipsoid

• rng – random number generator

Returns

• max_distance (float) – square radius of MLFriends algorithm

• max_radius (float) – square radius of enclosing ellipsoid.

estimate_volume()

Estimate the volume of the ellipsoid.

Does not account for the intersection with the unit cube borders.

Returns

logvolume – logarithm of the volume.

Return type

float

inside(pts)

Check if inside region.

Parameters

pts (array of vectors) – Points to check

Returns

is_inside – True if inside MLFriends region and wrapping ellipsoid, for each point in pts.

Return type

array of bools

sample(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Switches automatically between the sampling_methods (attribute).

Parameters

nsamples (int) – number of samples to draw

Returns

• samples (array of shape (nsamples, dimension)) – samples drawn

• idx (array of integers (nsamples)) – index of a point nearby (MLFriends.u)

sample_from_boundingbox(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Draws uniformly from bounding box around region.

Parameters as described in sample().

sample_from_transformed_boundingbox(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Draws uniformly from bounding box around region (in whitened space).

Parameters as described in sample().

sample_from_wrapping_ellipsoid(nsamples=100)

Draw uniformly sampled points from MLFriends region.

Draws uniformly from wrapping ellipsoid and filters with region.

Parameters as described in sample().

class ultranest.mlfriends.ScalingLayer(mean=0, std=1, nclusters=1, wrapped_dims=[], clusterids=None)

Bases: object

Simple transformation layer that only shifts and scales each axis.

Initialise layer.

create_new(upoints, maxradiussq, minvol=0.0)

Learn next layer from this optimized layer’s clustering.

Parameters

• upoints (array) – points to use for optimize (in u-space)

• maxradiussq (float) – square of the MLFriends radius

• minvol (float) – Minimum volume to regularize sample covariance

Return type

A new, optimized ScalingLayer.

optimize(points, centered_points, clusterids=None, minvol=0.0)

Optimize layer.

Estimates mean and std of points.

Parameters

• points (array) – points to use for optimize (in u-space)

• centered_points (array) – points with their cluster center subtracted

• clusterids (array of ints) – for each point, which cluster they belong to

• minvol – ignored

optimize_wrap(points)

Optimization for wrapped/circular parameters. Does nothing if there are no wrapped/circular parameters.

Parameters

• points (array) – points to use for optimization (in u-space)

• there. (Find largest gap in live points and wrap parameter space) –

• example (For) – |***** ****|

• has:: (if a wrapped axis) – |***** ****|

• middle (it would identify the) –

• it (subtract) –

• space (so that the new) –

• is:: –

  **** |

set_clusterids(clusterids=None, npoints=None)

Updates the cluster id assigned to each point.

transform(u)

Transform points from cube space to a whitened space.

untransform(ww)

Transform points from whitened space back to cube space.

unwrap(wpoints)

Undo wrapping for circular parameters.

wrap(points)

Wrap points for circular parameters.

class ultranest.mlfriends.SimpleRegion(u, transformLayer)

Bases: RobustEllipsoidRegion

Axis-aligned ellipsoidal region.

Defines a region around nested sampling live points for

1. checking whether a proposed point likely also fulfills the likelihood constraints

2. proposing new points.

Learns geometry of region from existing live points.

Initialise region.

Parameters

• u (array of vectors) – live points

• transformLayer (ScalingLayer or AffineLayer) – whitening layer

compute_enlargement(nbootstraps=50, minvol=0.0, rng=<module 'numpy.random' from '/home/user/.local/lib/python3.10/site-packages/numpy/random/__init__.py'>)

Return MLFriends radius and ellipsoid enlargement using bootstrapping.

The wrapping ellipsoid covariance is determined in each bootstrap round.

Parameters

• nbootstraps (int) – number of bootstrapping rounds

• minvol (float) – minimum volume to enforce to wrapping ellipsoid

• rng – random number generator

Returns

• max_distance (float) – square radius of MLFriends algorithm

• max_radius (float) – square radius of enclosing ellipsoid.

create_ellipsoid(minvol=0.0)

Create wrapping ellipsoid and store its center and covariance.

Parameters

minvol (float) – If positive, make sure ellipsoid has at least this volume.

class ultranest.mlfriends.WrappingEllipsoid(u)

Bases: object

Ellipsoid which safely wraps points.

Initialise region.

Parameters

u (array of vectors) – live points

compute_enlargement(nbootstraps=50, rng=<module 'numpy.random' from '/home/user/.local/lib/python3.10/site-packages/numpy/random/__init__.py'>)

Return ellipsoid enlargement after nbootstraps bootstrapping rounds.

The wrapping ellipsoid covariance is determined in each bootstrap round.

create_ellipsoid(minvol=0.0)

Create wrapping ellipsoid and store its center and covariance.

inside(u)

Check if inside wrapping ellipsoid.

Parameters

u (array of vectors) – Points to check

Returns

is_inside – True if inside wrapping ellipsoid, for each point in pts.

Return type

array of bools

update_center(ctr)

Update ellipsoid center, considering fixed dimensions.

Parameters

ctr (vector) – new center

ultranest.mlfriends.bounding_ellipsoid()

Calculate bounding ellipsoid containing a set of points x.

Parameters

• x ((npoints, ndim) ndarray) – Coordinates of uniformly sampled points.

• pointvol (float, optional) – Used to set a minimum bound on the ellipsoid volume when minvol is True.

Return type

mean and covariance of points

ultranest.mlfriends.compute_mean_pair_distance()

Compute the average distance between pairs of points. Pairs from different clusters are excluded in the computation.

Parameters

• pts (array) – points

• clusterids (array of ints or None) – for each point, index of the associated cluster.

Return type

mean distance between point pairs.

ultranest.mlfriends.find_nearby()

Gets the index of a point in a within square radius radiussq, for each point b in bpts.

The number is written to nnearby (of same length as bpts). If none is found, -1 is written.

Parameters

• apts (array) – points

• bpts (array) – points

• radiussq (float) – square of the MLFriends radius

• nnearby (array of ints) – The result will be written here.

ultranest.mlfriends.make_eigvals_positive()

For the symmetric square matrix a, increase any zero eigenvalues to fulfill a target product of eigenvalues.

Parameters

• a (array) – covariance matrix

• targetprod (array) – target product of eigenvalues

Return type

covariance matrix

ultranest.mlfriends.update_clusters()

Clusters upoints, so that clusters are distinct if no member pair is within a radius of sqrt(maxradiussq).

Parameters

• upoints (array) – points (in u-space)

• tpoints (array) – points (in t-space)

• maxradiussq (float) – square of the MLFriends radius

• clusterids (array of ints or None) – for each point, index of the associated cluster.

Returns

• nclusters (int) – the number of clusters found, which is also clusterids.max()

• new_clusterids (array of int) – the new clusterids for each point

• overlapped_points – upoints with their cluster centers subtracted.

• The existing cluster ids are re-used when assigning new clusters,

• if possible.

• Clustering is performed on a transformed coordinate space (tpoints).

• Returned values are based on upoints.

ultranest.mlfriends.vol_prefactor()

Volume constant for an n-dimensional sphere.

for n even: $$ (2pi)^(n /2) / (2 * 4 * … * n)$$ for n odd : $$2 * (2pi)^((n-1)/2) / (1 * 3 * … * n)$$

Parameters

n (int) – dimensionality

Return type

volume (float)

ultranest.netiter module

Functions and classes for treating nested sampling exploration as a tree.

The root represents the prior volume, branches and sub-branches split the volume. The leaves of the tree are the integration tail.

Nested sampling proceeds as a breadth first graph search, with active nodes sorted by likelihood value. The number of live points are the number of parallel edges (active nodes to do).

Most functions receive the argument “roots”, which are the children of the tree root (main branches).

The exploration is bootstrap-capable without requiring additional computational effort: The roots are indexed, and the bootstrap explorer can ignore the rootids it does not know about.

class ultranest.netiter.TreeNode(value=None, id=None, children=None)

Bases: object

Simple tree node.

Parameters

• value (float) – value used to order nodes (typically log-likelihood)

• id (int) – identifier, refers to the order of discovery and storage (PointPile)

• children (list) – children nodes, should be TreeNode objects. if None, a empty list is used.

class ultranest.netiter.BreadthFirstIterator(roots)

Bases: object

Generator exploring the tree.

Nodes are ordered by value and expanded in order. The number of edges passing the node “in parallel” are “active”.

Start with initial set of nodes roots.

reset()

(Re)start exploration from the top.

next_node()

Get next node in order.

Does not remove the node from active set.

Returns

None if done. rootid, node, (active_nodes, active_root_ids, active_node_values, active_node_ids) otherwise

Return type

tuple or None

drop_next_node()

Forget the current node.

expand_children_of(rootid, node)

Replace the current node with its children in the iterators list of active nodes.

Parameters

• rootid (int) – index of the root returned by the most recent call to BreadthFirstIterator.next_node()

• node (TreeNode) – node returned by the most recent call to BreadthFirstIterator.next_node()

ultranest.netiter.print_tree(roots, title='Tree:')

Print a pretty yet compact graphic of the tree.

Parameters

• roots (list) – list of TreeNode specifying the roots of the tree.

• title (str) – Print this string first.

ultranest.netiter.dump_tree(filename, roots, pointpile)

Write a copy of the tree to a HDF5 file.

Parameters

• filename (str) – output filename

• roots (list) – list of TreeNode specifying the roots of the tree.

• pointpile (PointPile) – information on the node points

ultranest.netiter.count_tree(roots)

Return the total number of nodes and maximum number of parallel edges.

Parameters

roots (list) – list of TreeNode specifying the roots of the tree.

Returns

• count (int) – total number of nodes

• maxwidth (int) – maximum number of active/parallel nodes encountered

ultranest.netiter.count_tree_between(roots, lo, hi)

Compute basic statistics about a tree.

Return the total number of nodes and maximum number of parallel edges, but only considering a interval of the tree.

Parameters

• roots (list) – list of TreeNode specifying the roots of the tree.

• lo (float) – lower value threshold

• hi (float) – upper value threshold

Returns

• nnodes (int) – total number of nodes in the value interval lo .. hi (inclusive).

• maxwidth (int) – maximum number of parallel edges

ultranest.netiter.find_nodes_before(root, value)

Identify all nodes that have children above value.

If a root child is above the value, its parent (root) is the leaf returned.

Parameters

• root (TreeNode) – tree

• value (float) – selection threshold

Returns

• list_of_parents (list of nodes) – parents

• list_of_nforks (list of floats) – The list of number of forks experienced is: 1 if direct descendent of one of the root node’s children, where no node had more than one child. 12 if the root child had 4 children, one of which had 3 children.

class ultranest.netiter.PointPile(udim, pdim, chunksize=1000)

Bases: object

A in-memory linearized storage of point coordinates.

TreeNode objects only store the logL value and id, which is the index in the point pile. The point pile stores the point coordinates in u and p-space (transformed and untransformed).

Set up point pile.

Parameters

• udim (int) – number of parameters, dimension of unit cube points

• pdim (int) – number of physical (and derived) parameters

• chunksize (int) – the point pile grows as needed, in these intervals.

add(newpointu, newpointp)

Save point.

Parameters

• newpointu (array) – point (in u-space)

• newpointp (array) – point (in p-space)

Returns

index – index of the new point in the pile

Return type

int

getu(i)

Get cube point(s) with index(indices) i.

getp(i)

Get parameter point(s) with index(indices) i.

make_node(value, u, p)

Store point in pile, and create a new tree node that points to it.

Parameters

• value (float) – value to store in node (loglikelihood)

• u (array) – point (in u-space)

• p (array) – point (in p-space)

Returns

node – node

Return type

TreeNode

class ultranest.netiter.SingleCounter(random=False)

Bases: object

Evidence log(Z) and posterior weight summation for a Nested Sampling tree.

Parameters

random (bool) – if False, use mean estimator for volume shrinkage if True, draw a random sample

reset()

Reset counters and integration.

property logZremain

Estimate conservatively the logZ of the current tail (un-opened nodes).

passing_node(node, parallel_nodes)

Accumulate node to the integration.

Parameters

• node (TreeNode) – breadth-first removed node

• parallel_nodes (list) – nodes active next to node

class ultranest.netiter.MultiCounter(nroots, nbootstraps=10, random=False, check_insertion_order=False)

Bases: object

Like SingleCounter, but bootstrap capable.

Attributes:

• logZ, logZerr, logVolremaining: main estimator logZerr is probably not reliable, because it needs nlive to convert H to logZerr.

• Lmax: highest loglikelihood currently known

• logZ_bs, logZerr_bs: bootstrapped logZ estimate

• logZremain, remainder_ratio: weight and fraction of the unexplored remainder

Each of the following has as many entries as number of iterations:

• all_H, all_logZ, all_logVolremaining, logweights: information for all instances first entry is the main estimator, i.e., not bootstrapped

• istail: whether that node was a leaf.

• nlive: number of parallel arcs (“live points”)

Initialise counter.

Parameters

• nroots (int) – number of children the tree root has

• nbootstraps (int) – number of bootstrap rounds

• random (bool) – if False, use mean estimator for volume shrinkage if True, draw a random sample

• check_insertion_order (bool) – whether to run insertion order rank U test

reset(nentries)

Reset counters/integrator.

Parameters

nentries (int) – number of iterators

property logZ_bs

Estimate logZ from the bootstrap ensemble.

property logZerr_bs

Estimate logZ error from the bootstrap ensemble.

property insertion_order_runlength

Get shortest insertion order test run.

Returns

• shortest_run_length (int) – Shortest insertion order test run length.

• The MWW (U-test) statistic is considered at each iteration.

• When it exceeds a threshold (4 sigma by default, insertion_order_threshold),

• the statistic is reset. The run length is recorded.

• This property returns the shortest run length of all recorded

• so far, or infinity otherwise.

• At 4 sigma, run lengths no shorter than 10^5.5 are expected

• in unbiased runs.

property insertion_order_converged

Check convergence.

Returns

• converged (bool) – Whether the run is unbiased according to a U-test.

• The MWW (U-test) statistic is considered at each iteration.

• When it exceeds a threshold (4 sigma by default, insertion_order_threshold),

• the statistic is reset. The run length is recorded.

• This property returns the shortest run length of all recorded

• so far, or infinity otherwise.

• At 4 sigma, run lengths no shorter than 10^5.5 are expected

• in unbiased runs. If the number of runs exceeds the number

• of iterations divided by 10^5.5, the run is likely biased

• and not converged.

• If not converged, the step sampler may need to use more steps,

• or the problem needs to be reparametrized.

passing_node(rootid, node, rootids, parallel_values)

Accumulate node to the integration.

Breadth-first removed node and nodes active next to node (parallel_nodes). rootid and rootids are needed to identify which bootstrap instance should accumulate.

Parameters

• rootid (TreeNode) – root node this node is from.

• node (TreeNode) – node being processed.

• rootids (array of ints) – for each parallel node, which root it belongs to.

• parallel_values (float array) – loglikelihood values of nodes passing node.

ultranest.netiter.combine_results(saved_logl, saved_nodeids, pointpile, main_iterator, mpi_comm=None)

Combine a sequence of likelihoods and nodes into a summary dictionary.

Parameters

• saved_logl (list of floats) – loglikelihoods of dead points

• saved_nodeids (list of ints) – indices of dead points

• pointpile (PointPile) – Point pile.

• main_iterator (BreadthFirstIterator) – iterator used

• mpi_comm – MPI communicator object, or None if MPI is not used.

Returns

results – All information of the run. Important keys: Number of nested sampling iterations (niter), Evidence estimate (logz), Effective Sample Size (ess), H (information gain), weighted samples (weighted_samples), equally weighted samples (samples), best-fit point information (maximum_likelihood), posterior summaries (posterior). The rank order test score (insertion_order_MWW_test) is included if the iterator has it.

Return type

dict

ultranest.netiter.logz_sequence(root, pointpile, nbootstraps=12, random=True, onNode=None, verbose=False, check_insertion_order=True)

Run MultiCounter through tree root.

Keeps track of, and returns (logz, logzerr, logv, nlive).

Parameters

• root (TreeNode) – Tree

• pointpile (PointPile) – Point pile

• nbootstraps (int) – Number of independent iterators

• random (bool) – Whether to randomly draw volume estimates

• onNode (function) – Function to call for every node. receives current node and the iterator

• verbose (bool) – Whether to show a progress indicator on stderr

• check_insertion_order (bool) – Whether to perform a rolling insertion order rank test

Returns

• results (dict) – Run information, see combine_results()

• sequence (dict) – Each entry of the dictionary is results[‘niter’] long, and contains the state of information at that iteration. Important keys are: Iteration number (niter), Volume estimate (logvol), loglikelihood (logl), absolute logarithmic weight (logwt), Relative weight (weights), point (samples), Number of live points (nlive), Evidence estimate (logz) and its uncertainty (logzerr), Rank test score (insert_order).

ultranest.ordertest module

Mann-Whitney-Wilcoxon U test for a uniform distribution of integers.

This implements the same idea as https://arxiv.org/abs/2006.03371 except their KS test is problematic because the variable (insertion order) is not continuous. Instead, this implements a Mann-Whitney-Wilcoxon U test, which also is in practice more sensitive than the KS test. A highly efficient implementation is achieved by keeping only a histogram of the insertion orders and comparing those to expectations from a uniform distribution.

To quantify the convergence of a run, one route is to apply this test at the end of the run. Another approach is to reset the counters every time the test exceeds a z-score of 3 sigma, and report the run lengths, which quantify how many iterations nested sampling was able to proceed without detection of a insertion order problem.

ultranest.ordertest.infinite_U_zscore(sample, B)

Compute Mann-Whitney-Wilcoxon U test for a sample of integers to be uniformly distributed between 0 and B.

Parameters

• B (int) – maximum rank allowed.

• sample (array of integers) – values between 0 and B (inclusive).

Returns

zscore

Return type

float

class ultranest.ordertest.UniformOrderAccumulator

Bases: object

Mann-Whitney-Wilcoxon U test accumulator.

Stores rank orders (1 to N), for comparison with a uniform order.

Initiate empty accumulator.

reset()

Set all counts to zero.

add(order, N)

Accumulate rank order (0 to N).

Parameters

• N (int) – maximum rank allowed.

• order (int) – rank between 0 and N (inclusive).

property zscore

z-score of the null hypothesis (uniform distribution) probability.

ultranest.pathsampler module

MCMC-like step sampling on a trajectory.

These features are experimental.

class ultranest.pathsampler.SamplingPathSliceSampler(nsteps)

Bases: StepSampler

Slice sampler, respecting the region, on the sampling path.

This first builds up a complete trajectory, respecting reflections. Then, from the trajectory a new point is drawn with slice sampling.

The trajectory is built by doubling the length to each side and checking if the point is still inside. If not, reflection is attempted with the gradient (either provided or region-based estimate).

Initialise sampler.

Parameters

nsteps (int) – number of accepted steps until the sample is considered independent.

generate_direction(ui, region, scale=1)

Choose new initial direction according to region.transformLayer axes.

adjust_accept(accepted, unew, pnew, Lnew, nc)

Adjust proposal given that we have been accepted at a new point after nc calls.

adjust_outside_region()

Adjust proposal given that we have stepped out of region.

move(ui, region, ndraw=1, plot=False)

Advance by slice sampling on the path.

class ultranest.pathsampler.SamplingPathStepSampler(nresets, nsteps, scale=1.0, balance=0.01, nudge=1.1, log=False)

Bases: StepSampler

Step sampler on a sampling path.

Initialise sampler.

Parameters

• nresets (int) – after this many iterations, select a new direction

• nsteps (int) – how many steps to make in total

• scale (float) – initial step size

• balance (float) – acceptance rate to target if below, scale is increased, if above, scale is decreased

• nudge (float) – factor for increasing scale (must be >=1) nudge=1 implies no step size adaptation.

start()

Start sampler, reset all counters.

start_path(ui, region)

Start new trajectory path.

terminate_path()

Terminate current path, and reset path counting variable.

set_gradient(grad_function)

Set gradient function.

generate_direction(ui, region, scale)

Choose a random axis from region.transformLayer.

adjust_accept(accepted, unew, pnew, Lnew, nc)

Adjust proposal given that we have been accepted at a new point after nc calls.

adjust_outside_region()

Adjust proposal given that we landed outside region.

adjust_scale(maxlength)

Adjust scale, but not above maxlength.

movei(ui, region, ndraw=1, plot=False)

Make a move and return the proposed index.

move(ui, region, ndraw=1, plot=False)

Advance move.

reflect(reflpoint, v, region, plot=False)

Reflect at reflpoint going in direction v. Return new direction.

get_point(inew)

Get point corresponding to index inew.

class ultranest.pathsampler.OtherSamplerProxy(nnewdirections, sampler='steps', nsteps=0, balance=0.9, scale=0.1, nudge=1.1, log=False)

Bases: object

Proxy for ClockedSamplers.

Initialise sampler.

Parameters

• nnewdirections (int) – number of accepted steps until the sample is considered independent.

• sampler (str) – which sampler to use

• nsteps – number of steps in sampler

• balance – acceptance rate to target

• scale – initial proposal scale

• nudge – adjustment factor for scale when acceptance rate is too low or high. must be >=1.

accumulate_statistics()

Accumulate statistics at end of step sequence.

adjust_scale(maxlength)

Adjust proposal scale, but not above maxlength.

startup(region, us, Ls)

Choose a new random starting point.

start_direction(region)

Choose a new random direction.

plot(filename)

Plot sampler statistics.

ultranest.plot module

Plotting utilities.

ultranest.plot.runplot(results, span=None, logplot=False, kde=True, nkde=1000, color='blue', plot_kwargs=None, label_kwargs=None, lnz_error=True, lnz_truth=None, truth_color='red', truth_kwargs=None, max_x_ticks=8, max_y_ticks=3, use_math_text=True, mark_final_live=True, fig=None)

Plot live points, ln(likelihood), ln(weight), and ln(evidence) vs. ln(prior volume).

Parameters

• results (dynesty.results.Results instance) – dynesty.results.Results instance from a nested sampling run.

• span (iterable with shape (4,), optional) –

  A list where each element is either a length-2 tuple containing lower and upper bounds or a float from (0., 1.] giving the fraction below the maximum. If a fraction is provided, the bounds are chosen to be equal-tailed. An example would be:

  span = [(0., 10.), 0.001, 0.2, (5., 6.)]
  

  Default is (0., 1.05 * max(data)) for each element.

• logplot (bool, optional) – Whether to plot the evidence on a log scale. Default is False.

• kde (bool, optional) – Whether to use kernel density estimation to estimate and plot the PDF of the importance weights as a function of log-volume (as opposed to the importance weights themselves). Default is True.

• nkde (int, optional) – The number of grid points used when plotting the kernel density estimate. Default is 1000.

• color (str or iterable with shape (4,), optional) – A ~matplotlib-style color (either a single color or a different value for each subplot) used when plotting the lines in each subplot. Default is ‘blue’.

• plot_kwargs (dict, optional) – Extra keyword arguments that will be passed to plot.

• label_kwargs (dict, optional) – Extra keyword arguments that will be sent to the ~matplotlib.axes.Axes.set_xlabel and ~matplotlib.axes.Axes.set_ylabel methods.

• lnz_error (bool, optional) – Whether to plot the 1, 2, and 3-sigma approximate error bars derived from the ln(evidence) error approximation over the course of the run. Default is True.

• lnz_truth (float, optional) – A reference value for the evidence that will be overplotted on the evidence subplot if provided.

• truth_color (str or iterable with shape (ndim,), optional) – A ~matplotlib-style color used when plotting lnz_truth. Default is ‘red’.

• truth_kwargs (dict, optional) – Extra keyword arguments that will be used for plotting lnz_truth.

• max_x_ticks (int, optional) – Maximum number of ticks allowed for the x axis. Default is 8.

• max_y_ticks (int, optional) – Maximum number of ticks allowed for the y axis. Default is 4.

• use_math_text (bool, optional) – Whether the axis tick labels for very large/small exponents should be displayed as powers of 10 rather than using e. Default is False.

• mark_final_live (bool, optional) – Whether to indicate the final addition of recycled live points (if they were added to the resulting samples) using a dashed vertical line. Default is True.

• fig ((~matplotlib.figure.Figure, ~matplotlib.axes.Axes), optional) – If provided, overplot the run onto the provided figure. Otherwise, by default an internal figure is generated.

Returns

runplot – Output summary plot.

Return type

(~matplotlib.figure.Figure, ~matplotlib.axes.Axes)

ultranest.plot.cornerplot(results, logger=None)

Make a corner plot with corner.

ultranest.plot.traceplot(results, span=None, quantiles=[0.025, 0.5, 0.975], smooth=0.02, post_color='blue', post_kwargs=None, kde=True, nkde=1000, trace_cmap='plasma', trace_color=None, trace_kwargs=None, connect=False, connect_highlight=10, connect_color='red', connect_kwargs=None, max_n_ticks=5, use_math_text=False, labels=None, label_kwargs=None, show_titles=False, title_fmt='.2f', title_kwargs=None, truths=None, truth_color='red', truth_kwargs=None, verbose=False, fig=None)

Plot traces and marginalized posteriors for each parameter.

Parameters

• results (~dynesty.results.Results instance) – A ~dynesty.results.Results instance from a nested sampling run. Compatible with results derived from nestle.

• span (iterable with shape (ndim,), optional) –

  A list where each element is either a length-2 tuple containing lower and upper bounds or a float from (0., 1.] giving the fraction of (weighted) samples to include. If a fraction is provided, the bounds are chosen to be equal-tailed. An example would be:

  span = [(0., 10.), 0.95, (5., 6.)]
  

  Default is 0.999999426697 (5-sigma credible interval) for each parameter.

• quantiles (iterable, optional) – A list of fractional quantiles to overplot on the 1-D marginalized posteriors as vertical dashed lines. Default is [0.025, 0.5, 0.975] (the 95%/2-sigma credible interval).

• smooth (float or iterable with shape (ndim,), optional) – The standard deviation (either a single value or a different value for each subplot) for the Gaussian kernel used to smooth the 1-D marginalized posteriors, expressed as a fraction of the span. Default is 0.02 (2% smoothing). If an integer is provided instead, this will instead default to a simple (weighted) histogram with bins=smooth.

• post_color (str or iterable with shape (ndim,), optional) – A ~matplotlib-style color (either a single color or a different value for each subplot) used when plotting the histograms. Default is ‘blue’.

• post_kwargs (dict, optional) – Extra keyword arguments that will be used for plotting the marginalized 1-D posteriors.

• kde (bool, optional) – Whether to use kernel density estimation to estimate and plot the PDF of the importance weights as a function of log-volume (as opposed to the importance weights themselves). Default is True.

• nkde (int, optional) – The number of grid points used when plotting the kernel density estimate. Default is 1000.

• trace_cmap (str or iterable with shape (ndim,), optional) – A ~matplotlib-style colormap (either a single colormap or a different colormap for each subplot) used when plotting the traces, where each point is colored according to its weight. Default is ‘plasma’.

• trace_color (str or iterable with shape (ndim,), optional) – A ~matplotlib-style color (either a single color or a different color for each subplot) used when plotting the traces. This overrides the trace_cmap option by giving all points the same color. Default is None (not used).

• trace_kwargs (dict, optional) – Extra keyword arguments that will be used for plotting the traces.

• connect (bool, optional) – Whether to draw lines connecting the paths of unique particles. Default is False.

• connect_highlight (int or iterable, optional) – If connect=True, highlights the paths of a specific set of particles. If an integer is passed, connect_highlight random particle paths will be highlighted. If an iterable is passed, then the particle paths corresponding to the provided indices will be highlighted.

• connect_color (str, optional) – The color of the highlighted particle paths. Default is ‘red’.

• connect_kwargs (dict, optional) – Extra keyword arguments used for plotting particle paths.

• max_n_ticks (int, optional) – Maximum number of ticks allowed. Default is 5.

• use_math_text (bool, optional) – Whether the axis tick labels for very large/small exponents should be displayed as powers of 10 rather than using e. Default is False.

• labels (iterable with shape (ndim,), optional) – A list of names for each parameter. If not provided, the default name used when plotting will follow \(x_i\) style.

• label_kwargs (dict, optional) – Extra keyword arguments that will be sent to the ~matplotlib.axes.Axes.set_xlabel and ~matplotlib.axes.Axes.set_ylabel methods.

• show_titles (bool, optional) – Whether to display a title above each 1-D marginalized posterior showing the 0.5 quantile along with the upper/lower bounds associated with the 0.025 and 0.975 (95%/2-sigma credible interval) quantiles. Default is True.

• title_fmt (str, optional) – The format string for the quantiles provided in the title. Default is ‘.2f’.

• title_kwargs (dict, optional) – Extra keyword arguments that will be sent to the ~matplotlib.axes.Axes.set_title command.

• truths (iterable with shape (ndim,), optional) – A list of reference values that will be overplotted on the traces and marginalized 1-D posteriors as solid horizontal/vertical lines. Individual values can be exempt using None. Default is None.

• truth_color (str or iterable with shape (ndim,), optional) – A ~matplotlib-style color (either a single color or a different value for each subplot) used when plotting truths. Default is ‘red’.

• truth_kwargs (dict, optional) – Extra keyword arguments that will be used for plotting the vertical and horizontal lines with truths.

• verbose (bool, optional) – Whether to print the values of the computed quantiles associated with each parameter. Default is False.

• fig ((~matplotlib.figure.Figure, ~matplotlib.axes.Axes), optional) – If provided, overplot the traces and marginalized 1-D posteriors onto the provided figure. Otherwise, by default an internal figure is generated.

Returns

traceplot – Output trace plot.

Return type

(~matplotlib.figure.Figure, ~matplotlib.axes.Axes)

class ultranest.plot.PredictionBand(x, shadeargs={}, lineargs={})

Bases: object

Plot bands of model predictions as calculated from a chain.

call add(y) to add predictions from each chain point

Example:

x = numpy.linspace(0, 1, 100)
band = PredictionBand(x)
for c in chain:
    band.add(c[0] * x + c[1])
# add median line
band.line(color='k')
# add 1 sigma quantile
band.shade(color='k', alpha=0.3)
# add wider quantile
band.shade(q=0.01, color='gray', alpha=0.1)
plt.show()

Parameters

x (array) – The independent variable

Initialise with independent variable x.

add(y)

Add a possible prediction y.

set_shadeargs(**kwargs)

Set matplotlib style for shading.

set_lineargs(**kwargs)

Set matplotlib style for line.

get_line(q=0.5)

Over prediction space x, get quantile q. Default is median.

shade(q=0.341, **kwargs)

Plot a shaded region between 0.5-q and 0.5+q. Default is 1 sigma.

line(**kwargs)

Plot the median curve.

ultranest.popstepsampler module

class ultranest.popstepsampler.PopulationSliceSampler(popsize, nsteps, generate_direction, scale=1.0, scale_adapt_factor=0.9, log=False, logfile=None)

Bases: object

Vectorized slice/HARM sampler.

Revert until all previous steps have likelihoods allL above Lmin. Updates currentt, generation and allL, in-place.

Parameters

• popsize (int) – number of walkers to maintain

• nsteps (int) – number of steps to take until the found point is accepted as independent.

• generate_direction (function (u, region, scale) -> v) – function such as generate_unit_directions, which generates a random slice direction.

• scale (float) – initial guess scale for the length of the slice

• scale_adapt_factor (float) – smoothing factor for updating scale. if near 1, scale is barely updating, if near 0, the last slice length is used as a initial guess for the next.

region_changed(Ls, region)

notification that the region changed. Currently not used.

step_back(Lmin)

see ultranest.stepfuncs.step_back()

setup_start(us, Ls, starting)

Initialize walker starting points.

For iteration zero, randomly selects a live point as starting point.

Parameters

• us (np.array((nlive, ndim))) – live points

• Ls (np.array(nlive)) – loglikelihoods live points

• starting (np.array(nwalkers, dtype=bool)) – which walkers to initialize.

property status

setup_brackets(mask_starting, region)

Pick starting direction and range for slice

Parameters

• region (MLFriends object) – Region

• mask_starting (np.array(nwalkers, dtype=bool)) – which walkers to set up.

advance(transform, loglike, Lmin)

Advance the walker population

Parameters

• transform (function) – prior transform function

• loglike (function) – loglikelihood function

• Lmin (float) – current log-likelihood threshold

shift()

Update walker from which to pick next.

ultranest.samplingpath module

Sparsely sampled, virtual sampling path.

Supports reflections at unit cube boundaries, and regions.

ultranest.samplingpath.nearest_box_intersection_line(ray_origin, ray_direction, fwd=True)

Compute intersection of a line (ray) and a unit box (0:1 in all axes).

Based on http://www.iquilezles.org/www/articles/intersectors/intersectors.htm

To continue forward traversing at the reflection point use:

while True:
    # update current point x
    x, _, i = box_line_intersection(x, v)
    # change direction
    v[i] *= -1

Parameters

• ray_origin (vector) – starting point of line

• ray_direction (vector) – line direction vector

Returns

• p (vector) – intersection point

• t (float) – intersection point distance from ray_origin in units in ray_direction

• i (int) – axes which change direction at pN

ultranest.samplingpath.box_line_intersection(ray_origin, ray_direction)

Find intersections of a line with the unit cube, in both sides.

Returns

• left (nearest_box_intersection_line return value) – from negative direction

• right (nearest_box_intersection_line return value) – from positive direction

ultranest.samplingpath.linear_steps_with_reflection(ray_origin, ray_direction, t, wrapped_dims=None)

Go t steps in direction ray_direction from ray_origin.

Reflect off the unit cube if encountered, respecting wrapped dimensions. In any case, the distance should be t * ray_direction.

Returns

• new_point (vector) – end point

• new_direction (vector) – new direction.

ultranest.samplingpath.get_sphere_tangent(sphere_center, edge_point)

Compute tangent at sphere surface point.

Assume a sphere centered at sphere_center with radius so that edge_point is on the surface. At edge_point, in which direction does the normal vector point?

Returns

tangent – vector pointing to the sphere center.

Return type

vector

ultranest.samplingpath.get_sphere_tangents(sphere_center, edge_point)

Compute tangent at sphere surface point.

Assume a sphere centered at sphere_center with radius so that edge_point is on the surface. At edge_point, in which direction does the normal vector point?

This function is vectorized and handles arrays of arguments.

Returns

tangent – vector pointing to the sphere center.

Return type

vector

ultranest.samplingpath.reflect(v, normal)

Reflect vector v off a normal vector, return new direction vector.

ultranest.samplingpath.distances(l, o, r=1)

Compute sphere-line intersection.

Parameters

• l (vector) – direction vector (line starts at 0)

• o (vector) – center of sphere (coordinate vector)

• r (float) – radius of sphere

Returns

tpos, tneg – the positive and negative coordinate along the l vector where r is intersected. If no intersection, throws AssertError.

Return type

floats

ultranest.samplingpath.isunitlength(vec)

Verify that vec is of unit length.

ultranest.samplingpath.angle(a, b)

Compute dot product between vectors a and b.

The arccos of the return value would give an actual angle.

ultranest.samplingpath.extrapolate_ahead(dj, xj, vj, contourpath=None)

Make di steps of size vj from xj.

Reflect off unit cube if necessary.

ultranest.samplingpath.interpolate(i, points, fwd_possible, rwd_possible, contourpath=None)

Interpolate a point on the path indicated by points.

Given a sparsely sampled track (stored in .points), potentially encountering reflections, extract the corrdinates of the point with index i. That point may not have been evaluated yet.

Parameters

• i (int) – position on track to return.

• points (list of tuples (index, coordinate, direction, loglike)) – points on the path

• fwd_possible (bool) – whether the path could be extended in the positive direction.

• rwd_possible (bool) – whether the path could be extended in the negative direction.

• contourpath (ContourPath) – Use region to reflect. Not used at the moment.

class ultranest.samplingpath.SamplingPath(x0, v0, L0)

Bases: object

Path described by a (potentially sparse) sequence of points.

Convention of the stored point tuple (i, x, v, L): i: index (0 is starting point) x: point v: direction L: loglikelihood value

Initialise with path starting point.

Starting point (x0), direction (v0) and loglikelihood value (L0) of the path. Is given index 0.

add(i, xi, vi, Li)

Add point xi, direction vi and value Li with index i to the path.

reset(x0, v0, L0)

Reset path, start from x0, v0, L0.

plot(**kwargs)

Plot the current path.

Only uses first two dimensions.

interpolate(i)

Interpolate point with index i on path.

extrapolate(i)

Advance beyond the current path, extrapolate from the end point.

Parameters

i (int) – index on path.

Returns

coords – coordinates of the new point.

Return type

vector

class ultranest.samplingpath.ContourSamplingPath(samplingpath, region)

Bases: object

Region-aware form of the sampling path.

Uses region points to guess a likelihood contour gradient.

Initialise with samplingpath and region.

add(i, x, v, L)

Add point xi, direction vi and value Li with index i to the path.

interpolate(i)

Interpolate point with index i on path.

extrapolate(i)

Advance beyond the current path, extrapolate from the end point.

Parameters

i (int) – index on path.

Returns

coords – coordinates of the new point.

Return type

vector

gradient(reflpoint, plot=False)

Compute gradient approximation.

Finds spheres enclosing the reflpoint, and chooses their mean as the direction to go towards. If no spheres enclose the reflpoint, use nearest sphere.

v is not used, because that would break detailed balance.

Considerations:

• in low-d, we want to focus on nearby live point spheres The border traced out is fairly accurate, at least in the normal away from the inside.

• in high-d, reflpoint is contained by all live points, and none of them point to the center well. Because the sampling is poor, the “region center” position will be very stochastic.

Parameters

• reflpoint (vector) – point outside the likelihood contour, reflect there

• v (vector) – previous direction vector

Returns

gradient – normal of ellipsoid

Return type

vector

ultranest.solvecompat module

Drop-in replacement for pymultinest.solve.

Example:

from ultranest.solvecompat import pymultinest_solve_compat as solve

# is a drop-in replacement for

from pymultinest.solve import solve

ultranest.solvecompat.pymultinest_solve_compat(LogLikelihood, Prior, n_dims, paramnames=None, outputfiles_basename=None, resume=False, n_live_points=400, evidence_tolerance=0.5, seed=-1, max_iter=0, wrapped_params=None, verbose=True, speed='safe', **kwargs)

Run nested sampling analysis.

Disadvantages compared to using ReactiveNestedSampler directly: cannot resume easily, cannot plot interactively. Limited results.

It is recommended that you directly use:

sampler = ReactiveNestedSampler(paramnames, LogLikelihood, transform=Prior)
sampler.run()

following the UltraNest documentation and manuals, as this gives you more control on resuming and sampler options.

ultranest.stepfuncs module

Efficient Helper functions for stepsamplers

ultranest.stepfuncs.evolve()

Evolve each slice sampling walker.

Parameters

• transform (function) – prior transform function

• loglike (function) – loglikelihood function

• Lmin (float) – current log-likelihood threshold

• search_right (np.array(nwalkers, dtype=bool)) – whether stepping out in the positive direction

• bisecting (np.array(nwalkers, dtype=bool)) – whether bisecting. If neither search_right nor bisecting, then

• currentu (np.array((nwalkers, ndim))) – slice starting point (where currentt=0)

• currentL (np.array(nwalkers)) – current loglikelihood

• currentt (np.array(nwalkers)) – proposed coordinate on the slice

• currentv (np.array((nwalkers, ndim))) – slice direction vector

• current_left (np.array(nwalkers)) – current slice negative end

• current_right (np.array(nwalkers)) – current slice positive end

• searching_left (np.array(nwalkers, dtype=bool)) – whether stepping out in the negative direction

• searching_right (np.array(nwalkers, dtype=bool)) – whether stepping out in the positive direction

Returns

• currentt (np.array(nwalkers)) – as above

• currentv (np.array((nwalkers, ndim))) – as above

• current_left (np.array(nwalkers)) – as above

• current_right (np.array(nwalkers)) – as above

• searching_left (np.array(nwalkers, dtype=bool)) – as above

• searching_right (np.array(nwalkers, dtype=bool)) – as above

• success (np.array(nwalkers, dtype=bool)) – whether the walker accepts the point.

• unew (np.array((success.sum(), ndim))) – coordinates of accepted points

• pnew (np.array((success.sum(), nparams))) – transformed coordinates of accepted points

• Lnew (np.array(success.sum())) – log-likelihoods of accepted points

• nc (int) – number of points for which the log-likelihood function was called.

• This function writes in-place to

• currentt, currentv, current_left, current_right, searching_left,

• searching_right and currentu, but also returns these.

ultranest.stepfuncs.evolve_prepare()

Get auxiliary slice sampler state selectors.

Vectorized computation for multiple (nwalkers) walkers.

Parameters

• searching_left (np.array(nwalkers, dtype=bool)) – whether stepping out in the negative direction

• searching_right (np.array(nwalkers, dtype=bool)) – whether stepping out in the positive direction

Returns

• search_right (np.array(nwalkers, dtype=bool):) – if searching right and not left

• bisecting (np.array(nwalkers, dtype=bool):) – if not searching right nor left any more

ultranest.stepfuncs.evolve_update()

Update the state of each walker.

This uses the robust logic of slice sampling, with stepping out by doubling.

Parameters

• acceptable (np.array(nwalkers, dtype=bool)) – whether a likelihood evaluation was made. If false, rejected because out of contour.

• Lnew (np.array(acceptable.sum(), dtype=bool)) – likelihood value of proposed point

• Lmin (float) – current log-likelihood threshold

• search_right (np.array(nwalkers, dtype=bool)) – whether stepping out in the positive direction

• bisecting (np.array(nwalkers, dtype=bool)) – whether bisecting. If neither search_right nor bisecting, then

• currentt (np.array(nwalkers)) – proposed coordinate on the slice

• current_left (np.array(nwalkers)) – current slice negative end

• current_right (np.array(nwalkers)) – current slice positive end

• searching_left (np.array(nwalkers, dtype=bool)) – whether stepping out in the negative direction

• searching_right (np.array(nwalkers, dtype=bool)) – whether stepping out in the positive direction

• success (np.array(nwalkers, dtype=bool)) – whether the walker accepts the point.

Notes

Writes to currentt, current_left, current_right, searching_left, searching_right, success.

ultranest.stepfuncs.generate_cube_oriented_direction()

Draw a unit direction vector in direction of a random unit cube axes.

Parameters

• ui (np.array((npoints, ndim), dtype=float)) – starting points (not used)

• region – not used

• scale (float) – length of returned vector

Returns

v – Random axis vectors of length scale, one for each starting point.

Return type

np.array((npoints, ndim), dtype=float)

ultranest.stepfuncs.generate_random_direction()

Draw uniform direction vector in unit cube space of length scale.

Parameters

• region (MLFriends object) – current region (not used)

• scale (float) – length of direction vector

Returns

v – new direction vector

Return type

array

ultranest.stepfuncs.generate_region_oriented_direction()

Draw a random direction vector in direction of one of the region axes.

If given, the vector length is scale. If not, the vector length in transformed space is tscale.

Parameters

• region (MLFriends object) – current region

• scale (float) – length of direction vector in t-space

Returns

v – new direction vector (in u-space)

Return type

array

ultranest.stepfuncs.generate_region_random_direction()

Draw a direction vector in a random direction of the region.

The vector length is scale (in unit cube space).

Parameters

• region (MLFriends object) – current region

• scale (float:) – length of direction vector (in t-space)

Returns

v – new direction vector

Return type

array

ultranest.stepfuncs.step_back()

Revert walkers which have wandered astray.

Revert until all previous steps have likelihoods allL above Lmin. Updates currentt, generation and allL, in-place.

Parameters

• Lmin (float) – current loglikelihood threshold

• allL (np.array((nwalkers, ngenerations))) – loglikelihoods of the chain. NaN where not evaluated yet.

• generation (np.array(nwalkers, dtype=int)) – how many iterations each walker has completed.

• currentt (np.array(nwalkers)) – current slice coordinate

ultranest.stepfuncs.within_unit_cube()

whether all fields are between 0 and 1, for each row

Parameters

u (np.array((npoints, ndim), dtype=float):) – points

Returns

within – for each point, whether it is within the unit cube

Return type

np.array(npoints, dtype=bool):

ultranest.stepsampler module

MCMC-like step sampling within a region.

The classes implemented here are generators that, in each iteration, only make one likelihood call. This allows keeping a population of samplers that have the same execution time per call, even if they do not terminate at the same number of iterations.

ultranest.stepsampler.generate_random_direction(ui, region, scale=1)

Draw uniform direction vector in unit cube space of length scale.

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region (not used)

• scale (float) – length of direction vector

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.generate_cube_oriented_direction(ui, region, scale=1)

Draw a unit direction vector in direction of a random unit cube axes.

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region (not used)

• scale (float) – factor to multiple the vector

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.generate_cube_oriented_differential_direction(ui, region, scale=1)

Draw a unit direction vector in direction of a random unit cube axes.

Guess the length from the difference of two points in that axis.

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region

• scale (float) – factor to multiple the vector

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.generate_differential_direction(ui, region, scale=1)

Draw a vector using the difference between two points.

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region

• scale (float) – factor to multiple the vector

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.generate_partial_differential_direction(ui, region, scale=1)

Draw a unit direction vector in direction of a random unit cube axes.

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region

• scale (float) – factor to multiple the vector

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.generate_region_oriented_direction(ui, region, scale=1)

Draw a random direction vector in direction of one of the region axes.

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region

• scale (float) – factor to multiple the vector

Returns

v – new direction vector (in u-space)

Return type

array

ultranest.stepsampler.generate_region_random_direction(ui, region, scale=1)

Draw a direction vector in a random direction of the region.

The vector length is scale (in unit cube space).

Parameters

• ui (array) – starting point

• region (MLFriends object) – current region

• scale (float:) – length of direction vector (in t-space)

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.generate_mixture_random_direction(ui, region, scale=1)

Draw either from a region-direction or a unit axis.

Parameters

• region (MLFriends) – region

• ui (array) – vector of starting point

• scale (float) – length of the vector.

Returns

v – new direction vector

Return type

array

ultranest.stepsampler.inside_region(region, unew, uold)

Check if unew is inside region.

Parameters

• region (MLFriends object) – current region

• unew (array) – point to check

• uold (array) – not used

Returns

v – boolean whether point is inside the region

Return type

array

ultranest.stepsampler.adapt_proposal_total_distances(region, history, mean_pair_distance, ndim)

ultranest.stepsampler.adapt_proposal_total_distances_NN(region, history, mean_pair_distance, ndim)

ultranest.stepsampler.adapt_proposal_summed_distances(region, history, mean_pair_distance, ndim)

ultranest.stepsampler.adapt_proposal_summed_distances_NN(region, history, mean_pair_distance, ndim)

ultranest.stepsampler.adapt_proposal_move_distances(region, history, mean_pair_distance, ndim)

ultranest.stepsampler.adapt_proposal_move_distances_midway(region, history, mean_pair_distance, ndim)

class ultranest.stepsampler.StepSampler(nsteps, generate_direction, scale=1.0, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False)

Bases: object

Base class for a simple step sampler, staggering around.

Scales proposal towards a 50% acceptance rate.

Initialise sampler.

Parameters

• scale (float) – initial proposal size

• nsteps (int) –

  number of accepted steps until the sample is considered independent.

  To find the right value, run nested sampling several time, always doubling nsteps, until Z is stable.

• generate_direction (function) –

  direction proposal function.

  Available are:

  • generate_cube_oriented_direction() (slice sampling)

  • generate_region_oriented_direction() (slice sampling on the whitened parameter space)

  • SequentialDirectionGenerator (sequential slice sampling on the whitened parameter space)

  • generate_random_direction() (hit-and-run sampling)

  • generate_region_random_direction() (hit-and-run sampling on the whitened parameter space)

  • generate_cube_oriented_differential_direction() (slice sampling with better proposal scale)

  • generate_differential_direction() (differential evolution slice proposal)

  • generate_partial_differential_direction() (differential evolution slice proposal on only 10% of the parameters)

  • generate_mixture_random_direction() (generate_differential_direction and generate_cube_oriented_differential_direction)

  Additionally, OrthogonalDirectionGenerator can be applied to a generate_direction.

  When in doubt, try generate_mixture_random_direction(). It combines efficient moves along the live point distribution, with robustness against collapse to a subspace. generate_cube_oriented_direction() works well too.

• adaptive_nsteps (False, 'proposal-distance', 'move-distance') –

  Strategy to adapt the number of steps. The strategies make sure that:

  • ’move-distance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.

  • ’move-distance-midway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.

  • ’proposal-total-distances’: mean square distance of proposed vectors exceeds the mean distance between pairs of live points.

  • ’proposal-total-distances-NN’: mean distance of chain points from starting point exceeds mean distance between pairs of live points.

  • ’proposal-summed-distances-NN’: summed distances between chain points exceeds mean distance between pairs of live points.

  • ’proposal-summed-distances-min-NN’: smallest distance between chain points exceeds mean distance between pairs of live points.

  Adapting can give usable results. However, strictly speaking, detailed balance is not maintained, so the results can be biased. You can use the logstat property to find out the nsteps learned from one run (third column), and use the largest value for nsteps of a fresh run.

• max_nsteps (int) – Maximum number of steps the adaptive_nsteps can reach.

• region_filter (bool) – if True, use region to check if a proposed point can be inside before calling likelihood.

• log (file) – log file for sampler statistics, such as acceptance rate, proposal scale, number of steps, jump distance and distance between live points

plot(filename)

Plot sampler statistics.

Parameters

filename (str) – Stores plot into filename and data into filename + ".txt.gz".

move(ui, region, ndraw=1, plot=False)

Move around point ui. Stub to be implemented by child classes.

adjust_outside_region()

Adjust proposal, given that we landed outside region.

adjust_accept(accepted, unew, pnew, Lnew, nc)

Adjust proposal, given that a new point was found after nc calls.

Parameters

• accepted (bool) – Whether the most recent proposal was accepted

• unew (array) – new point (in u-space)

• pnew (array) – new point (in p-space)

• Lnew (float) – loglikelihood of new point

• nc (int) – number of likelihood function calls used.

adapt_nsteps(region)

Adapt the number of steps.

Parameters

region (MLFriends object) – current region

finalize_chain(region=None, Lmin=None, Ls=None)

Store chain statistics and adapt proposal.

Parameters

• region (MLFriends object) – current region

• Lmin (float) – current loglikelihood threshold

• Ls (array) – loglikelihood values of the live points

new_chain(region=None)

Start a new path, reset statistics.

region_changed(Ls, region)

React to change of region.

Parameters

• region (MLFriends object) – current region

• Ls (array) – loglikelihood values of the live points

class ultranest.stepsampler.MHSampler(nsteps, generate_direction, scale=1.0, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False)

Bases: StepSampler

Gaussian Random Walk.

Initialise sampler.

Parameters

• scale (float) – initial proposal size

• nsteps (int) –

  number of accepted steps until the sample is considered independent.

  To find the right value, run nested sampling several time, always doubling nsteps, until Z is stable.

• generate_direction (function) –

  direction proposal function.

  Available are:

  • generate_cube_oriented_direction() (slice sampling)

  • generate_region_oriented_direction() (slice sampling on the whitened parameter space)

  • SequentialDirectionGenerator (sequential slice sampling on the whitened parameter space)

  • generate_random_direction() (hit-and-run sampling)

  • generate_region_random_direction() (hit-and-run sampling on the whitened parameter space)

  • generate_cube_oriented_differential_direction() (slice sampling with better proposal scale)

  • generate_differential_direction() (differential evolution slice proposal)

  • generate_partial_differential_direction() (differential evolution slice proposal on only 10% of the parameters)

  • generate_mixture_random_direction() (generate_differential_direction and generate_cube_oriented_differential_direction)

  Additionally, OrthogonalDirectionGenerator can be applied to a generate_direction.

  When in doubt, try generate_mixture_random_direction(). It combines efficient moves along the live point distribution, with robustness against collapse to a subspace. generate_cube_oriented_direction() works well too.

• adaptive_nsteps (False, 'proposal-distance', 'move-distance') –

  Strategy to adapt the number of steps. The strategies make sure that:

  • ’move-distance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.

  • ’move-distance-midway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.

  • ’proposal-total-distances’: mean square distance of proposed vectors exceeds the mean distance between pairs of live points.

  • ’proposal-total-distances-NN’: mean distance of chain points from starting point exceeds mean distance between pairs of live points.

  • ’proposal-summed-distances-NN’: summed distances between chain points exceeds mean distance between pairs of live points.

  • ’proposal-summed-distances-min-NN’: smallest distance between chain points exceeds mean distance between pairs of live points.

  Adapting can give usable results. However, strictly speaking, detailed balance is not maintained, so the results can be biased. You can use the logstat property to find out the nsteps learned from one run (third column), and use the largest value for nsteps of a fresh run.

• max_nsteps (int) – Maximum number of steps the adaptive_nsteps can reach.

• region_filter (bool) – if True, use region to check if a proposed point can be inside before calling likelihood.

• log (file) – log file for sampler statistics, such as acceptance rate, proposal scale, number of steps, jump distance and distance between live points

move(ui, region, ndraw=1, plot=False)

Move in u-space with a Gaussian proposal.

Parameters

• ui (array) – current point

• ndraw (int) – number of points to draw.

• region – ignored

• plot – ignored

ultranest.stepsampler.CubeMHSampler(*args, **kwargs)

Gaussian Metropolis-Hastings sampler, using unit cube.

ultranest.stepsampler.RegionMHSampler(*args, **kwargs)

Gaussian Metropolis-Hastings sampler, using region.

class ultranest.stepsampler.SliceSampler(nsteps, generate_direction, scale=1.0, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False)

Bases: StepSampler

Slice sampler, respecting the region.

Initialise sampler.

Parameters

• scale (float) – initial proposal size

• nsteps (int) –

  number of accepted steps until the sample is considered independent.

  To find the right value, run nested sampling several time, always doubling nsteps, until Z is stable.

• generate_direction (function) –

  direction proposal function.

  Available are:

  • generate_cube_oriented_direction() (slice sampling)

  • generate_region_oriented_direction() (slice sampling on the whitened parameter space)

  • SequentialDirectionGenerator (sequential slice sampling on the whitened parameter space)

  • generate_random_direction() (hit-and-run sampling)

  • generate_region_random_direction() (hit-and-run sampling on the whitened parameter space)

  • generate_cube_oriented_differential_direction() (slice sampling with better proposal scale)

  • generate_differential_direction() (differential evolution slice proposal)

  • generate_partial_differential_direction() (differential evolution slice proposal on only 10% of the parameters)

  • generate_mixture_random_direction() (generate_differential_direction and generate_cube_oriented_differential_direction)

  Additionally, OrthogonalDirectionGenerator can be applied to a generate_direction.

  When in doubt, try generate_mixture_random_direction(). It combines efficient moves along the live point distribution, with robustness against collapse to a subspace. generate_cube_oriented_direction() works well too.

• adaptive_nsteps (False, 'proposal-distance', 'move-distance') –

  Strategy to adapt the number of steps. The strategies make sure that:

  • ’move-distance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.

  • ’move-distance-midway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.

  • ’proposal-total-distances’: mean square distance of proposed vectors exceeds the mean distance between pairs of live points.

  • ’proposal-total-distances-NN’: mean distance of chain points from starting point exceeds mean distance between pairs of live points.

  • ’proposal-summed-distances-NN’: summed distances between chain points exceeds mean distance between pairs of live points.

  • ’proposal-summed-distances-min-NN’: smallest distance between chain points exceeds mean distance between pairs of live points.

  Adapting can give usable results. However, strictly speaking, detailed balance is not maintained, so the results can be biased. You can use the logstat property to find out the nsteps learned from one run (third column), and use the largest value for nsteps of a fresh run.

• max_nsteps (int) – Maximum number of steps the adaptive_nsteps can reach.

• region_filter (bool) – if True, use region to check if a proposed point can be inside before calling likelihood.

• log (file) – log file for sampler statistics, such as acceptance rate, proposal scale, number of steps, jump distance and distance between live points

new_chain(region=None)

Start a new path, reset slice.

adjust_accept(accepted, unew, pnew, Lnew, nc)

see StepSampler.adjust_accept()

adjust_outside_region()

Adjust proposal given that we landed outside region.

move(ui, region, ndraw=1, plot=False)

Advance the slice sampling move. see StepSampler.move()

ultranest.stepsampler.CubeSliceSampler(*args, **kwargs)

Slice sampler, randomly picking region axes.

ultranest.stepsampler.RegionSliceSampler(*args, **kwargs)

Slice sampler, randomly picking region axes.

ultranest.stepsampler.BallSliceSampler(*args, **kwargs)

Hit & run sampler. Choose random directions in space.

ultranest.stepsampler.RegionBallSliceSampler(*args, **kwargs)

Hit & run sampler. Choose random directions according to region.

class ultranest.stepsampler.SequentialRegionDirectionGenerator

Bases: object

Sequentially proposes one region axes after the next.

ultranest.stepsampler.RegionSequentialSliceSampler(*args, **kwargs)

Slice sampler, sequentially iterating region axes.

class ultranest.stepsampler.OrthogonalDirectionGenerator(generate_direction)

Bases: object

Orthogonalizes proposal vectors.

Parameters

generate_direction (function) – direction proposal to orthogonalize

class ultranest.stepsampler.SpeedVariableGenerator(step_matrix, generate_direction=<function generate_region_random_direction>)

Bases: object

Propose directions in region, but only some dimensions at a time, completely user-definable.

Initialise sampler.

Parameters

• step_matrix (matrix or list of slices) –

  if a bool matrix of shape (n_steps, n_dims):

  Each row of the matrix indicates which parameters should be updated.

  Example:

  [[True, True], [False, True], [False, True]]
  

  This would update the first parameter 1/3 times, and the second parameters every time. Three steps are made until the point is considered independent.

  For a full update in every step, use:

  np.ones((n_steps, n_dims), dtype=bool)
  

  if a list of slices:

  Each entry indicates which parameters should be updated.

  Example:

  [Ellipsis, slice(2,10), slice(5,10)]
  

  This would update the first parameter 1/3 times, parameters 2-9 2/3 times and parameter 5-9 in every step. Three steps are made until the point is considered independent.

• generate_direction (function) – direction proposal function.

ultranest.stepsampler.SpeedVariableRegionSliceSampler(step_matrix, *args, **kwargs)

Slice sampler, in region axes.

Updates only some dimensions at a time, completely user-definable.

ultranest.stepsampler.ellipsoid_bracket(ui, v, ellipsoid_center, ellipsoid_inv_axes, ellipsoid_radius_square)

Find line-ellipsoid intersection points.

For a line from ui in direction v through an ellipsoid centered at ellipsoid_center with axes matrix ellipsoid_inv_axes, return the lower and upper intersection parameter.

Parameters

• ui (array) – current point (in u-space)

• v (array) – direction vector

• ellipsoid_center (array) – center of the ellipsoid

• ellipsoid_inv_axes (array) – ellipsoid axes matrix, as computed by WrappingEllipsoid

• ellipsoid_radius_square (float) – square of the ellipsoid radius

Returns

• left (float) – distance to go until ellipsoid is intersected (non-positive)

• right (float) – distance to go until ellipsoid is intersected (non-negative)

ultranest.stepsampler.crop_bracket_at_unit_cube(ui, v, left, right, epsilon=1e-06)

Find line-cube intersection points.

A line segment from ui in direction v from t between left <= 0 <= right will be truncated by the unit cube. Returns the bracket and whether cropping was applied.

Parameters

• ui (array) – current point (in u-space)

• v (array) – direction vector

• left (float) – bracket lower end (non-positive)

• right (float) – bracket upper end (non-negative)

• epsilon (float) – small number to allow for numerical effects

Returns

• left (float) – new left

• right (float) – new right

• cropped_left (bool) – whether left was changed

• cropped_right (bool) – whether right was changed

ultranest.store module

Storage for nested sampling points.

The information stored is a table with

• the likelihood threshold drawn from

• the likelihood, prior volume coordinates and physical coordinates of the point

class ultranest.store.NullPointStore(ncols)

Bases: object

No storage.

Mock initialisation.

reset()

Do nothing.

close()

Do nothing.

flush()

Do nothing.

add(row, ncalls)

Increases the number of “stored” points.

pop(Lmin)

Return no point (None, None).

class ultranest.store.FilePointStore

Bases: object

Base class for storing points in a file.

reset()

Reset stack to loaded data.

Useful when Lmin is not reset to a lower value.

close()

Close file.

flush()

Flush file to disk.

pop(Lmin)

Request from the storage a point sampled from <= Lmin with L > Lmin.

Returns

• index (int) – index of the point, None if no point exists

• point (array) – point values, None if no point exists

class ultranest.store.TextPointStore(filepath, ncols)

Bases: FilePointStore

Storage in a text file.

Stores previously drawn points above some likelihood contour, so that they can be reused in another run.

The format is a tab separated text file. Through the fmt and delimiter attributes the output can be altered.

Load and append to storage at filepath.

The file should contain ncols columns (Lmin, L, and others).

add(row, ncalls)

Add data point row = [Lmin, L, *otherinfo] to storage.

class ultranest.store.HDF5PointStore(filepath, ncols, **h5_file_args)

Bases: FilePointStore

Storage in a HDF5 file.

Stores previously drawn points above some likelihood contour, so that they can be reused in another run.

The format is a HDF5 file, which grows as needed.

Load and append to storage at filepath.

File contains ncols columns in ‘points’ dataset (Lmin, L, and others). h5_file_args are passed on to hdf5.File.

FILES_OPENED = []

add(row, ncalls)

Add data point row = [Lmin, L, otherinfo to storage.

ultranest.utils module

Utility functions for logging and statistics.

ultranest.utils.create_logger(module_name, log_dir=None, level=20)

Set up the logging channel module_name.

Append to debug.log in log_dir (if not None). Write to stdout with output level level.

If logging handlers are already registered for this module, no new handlers are registered.

Parameters

• module_name (str) – logger module

• log_dir (str) – directory to write debug.log file into

• level (logging level) – which level (and above) to log to stdout.

Returns

logger instance

Return type

logger

ultranest.utils.make_run_dir(log_dir, run_num=None, append_run_num=True, max_run_num=10000)

Generate a new numbered directory for this run to store output.

Parameters

• log_dir (str) – base path

• run_num (int) – folder to add to path, such as prefix/run1/

• append_run_num (bool) – If true, set run_num to next unused number

• max_run_num (int) – Maximum number of automatic run subfolders

Returns

folderpath – dictionary of folder paths for different purposes. Keys are “run_dir” (the path), “info”, “results”, “chains”, “plots”.

Return type

dict

ultranest.utils.vectorize(function)

Vectorize likelihood or prior_transform function.

ultranest.utils.resample_equal(samples, weights, rstate=None)

Resample the samples so that the final samples all have equal weight.

Each input sample appears in the output array either floor(weights[i] * N) or ceil(weights[i] * N) times, with floor or ceil randomly selected (weighted by proximity).

Parameters

• samples (~numpy.ndarray) – Unequally weight samples returned by the nested sampling algorithm. Shape is (N, …), with N the number of samples.

• weights (~numpy.ndarray) – Weight of each sample. Shape is (N,).

• rstate (~numpy.random.RandomState) – random number generator. If not provided, numpy.random is used.

Returns

equal_weight_samples – Samples with equal weights, same shape as input samples.

Return type

~numpy.ndarray

Examples

>>> x = np.array([[1., 1.], [2., 2.], [3., 3.], [4., 4.]])
>>> w = np.array([0.6, 0.2, 0.15, 0.05])
>>> nestle.resample_equal(x, w)
array([[ 1.,  1.],
       [ 1.,  1.],
       [ 1.,  1.],
       [ 3.,  3.]])

Notes

Implements the systematic resampling method described in this PDF. Another way to sample according to weights would be:

N = len(weights)
new_samples = samples[np.random.choice(N, size=N, p=weights)]

However, the method used in this function is less “noisy”.

ultranest.utils.listify(*args)

Concatenate args, which are (made to be) lists.

Parameters

args (iterable) – Lists to concatenate.

Returns

Concatenation of the lists in args.

Return type

list

ultranest.utils.quantile(x, q, weights=None)

Compute (weighted) quantiles from an input set of samples.

Parameters

• x (~numpy.ndarray with shape (nsamps,)) – Input samples.

• q (~numpy.ndarray with shape (nquantiles,)) – The list of quantiles to compute from [0., 1.].

• weights (~numpy.ndarray with shape (nsamps,), optional) – The associated weight from each sample.

Returns

quantiles – The weighted sample quantiles computed at q.

Return type

~numpy.ndarray with shape (nquantiles,)

ultranest.utils.vol_prefactor(n)

Volume constant for an n-dimensional sphere.

for n even: $$ (2pi)^(n /2) / (2 * 4 * … * n)$$ for n odd : $$2 * (2pi)^((n-1)/2) / (1 * 3 * … * n)$$

Parameters

n (int) – Dimensionality

Returns

Volume

Return type

float

ultranest.utils.is_affine_transform(a, b)

Check if one points a and b are related by an affine transform.

The implementation currently returns False for rotations.

Parameters

• a (array) – transformed points

• b (array) – original points

Returns

is_affine

Return type

bool

ultranest.utils.normalised_kendall_tau_distance(values1, values2, i=None, j=None)

Normalised Kendall tau distance between two equally sized arrays.

see https://en.wikipedia.org/wiki/Kendall_tau_distance

You can optionally pass precomputed indices:

i, j = np.meshgrid(np.arange(N), np.arange(N))

Parameters

• values1 (array of ints) – ranks

• values2 (array of ints) – other ranks (same length as values1)

• i (array of ints) – 2d indices selecting values1

• j (array of ints) – 2d indices selecting values2

Returns

distance

Return type

float

ultranest.utils.verify_gradient(ndim, transform, loglike, gradient, verbose=False, combination=False)

Check with numerical differentiation if gradient function is plausibly correct.

Raises AssertError if not fulfilled. All functions are vectorized.

Parameters

• ndim (int) – dimensionality

• transform (function) – transform unit cube parameters to physical parameters, vectorized

• loglike (function) – loglikelihood function, vectorized

• gradient (function) – computes gradient of loglike to unit cube parameters. Takes a single point and returns a single vector.

• verbose (bool) – whether to show intermediate test results

• combination (bool) – if true, the gradient function should return a tuple of: (transformed parameters, loglikelihood, gradient) for a given unit cube point.

ultranest.utils.distributed_work_chunk_size(num_total_tasks, mpi_rank, mpi_size)

Computes the number of tasks for process number mpi_rank, so that num_total_tasks tasks are spread uniformly among mpi_size processes.

Parameters

• num_total_tasks (int) – total number of tasks to be split

• mpi_rank (int) – process id

• mpi_size (int) – total number of processes

ultranest.utils.submasks(mask, *masks)

Get indices for an array, so that array[indices] is equivalent to a[mask][mask1][mask2].

Parameters

• mask (np.array(dtype=bool)) – selection of some array

• masks (list of np.array(dtype=bool)) – each further mask is a subselection

Returns

indices – indices which select the subselection in the original array

Return type

np.array(dtype=int)

ultranest.viz module

Visual impression of current exploration.

ultranest.viz.round_parameterlimits(plo, phi, paramlimitguess=None)

Guess the current parameter range.

Parameters

• plo (array of floats) – for each parameter, current minimum value

• phi (array of floats) – for each parameter, current maximum value

• paramlimitguess (array of float tuples) – for each parameter, guess of parameter range if available

Returns

• plo_rounded (array of floats) – for each parameter, rounded minimum value

• phi_rounded (array of floats) – for each parameter, rounded maximum value

• formats (array of float tuples) – for each parameter, string format for representing it.

ultranest.viz.nicelogger(points, info, region, transformLayer, region_fresh=False)

Log current live points and integration progress to stdout.

Parameters

• points (dict with keys "u", "p", "logl") – live points (u: cube coordinates, p: transformed coordinates, logl: loglikelihood values)

• info (dict) –

  integration information. Keys are:

  • paramlims (optional): parameter ranges

  • logvol: expected volume at this iteration

• region (MLFriends) – Current region.

• transformLayer (ScaleLayer or AffineLayer) – Current transformLayer (for clustering information).

• region_fresh (bool) – Whether the region was just updated.

ultranest.viz.isnotebook()

Check if running in a Jupyter notebook.

class ultranest.viz.LivePointsWidget

Bases: object

Widget for ipython and jupyter notebooks.

Shows where the live points are currently in parameter space.

Initialise. To draw, call .initialize().

initialize(paramnames, width)

Set up and display widget.

Parameters

• paramnames (list of str) – Parameter names

• width (int) – number of html table columns.

ultranest.viz.get_default_viz_callback()

Get default callback.

LivePointsWidget for Jupyter notebook, nicelogger otherwise.

Module contents

Performs nested sampling to calculate the Bayesian evidence and posterior samples Some parts are from the Nestle library by Kyle Barbary (https://github.com/kbarbary/nestle) Some parts are from the nnest library by Adam Moss (https://github.com/adammoss/nnest)