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)[source]¶ Compute the stop condition in the main loop dot(dtheta, rminus) >= 0 & dot(dtheta, rplus >= 0)
 thetaminus, thetaplus: ndarray[float, ndim=1]
under and above position
 rminus, rplus: ndarray[float, ndim=1]
under and above momentum
 criterion: bool
return if the condition is valid

ultranest.dychmc.
step_or_reflect
(theta, v, epsilon, transform, loglike, gradient, Lmin)[source]¶ Make a step from theta towards v with stepsize epsilon.

ultranest.dychmc.
build_tree
(theta, v, direction, j, epsilon, transform, loglike, gradient, Lmin)[source]¶ The main recursion.

ultranest.dychmc.
tree_sample
(theta, p, logL, v, epsilon, transform, loglike, gradient, Lmin, maxheight=inf)[source]¶ Build NUTSlike tree of sampling path from theta towards p with stepsize epsilon.

ultranest.dychmc.
generate_uniform_direction
(d, massmatrix)[source]¶ draw unit direction vector according to mass matrix

class
ultranest.dychmc.
DynamicCHMCSampler
(ndim, nsteps, transform, loglike, gradient, adaptive_nsteps=False, delta=0.9, nudge=1.04)[source]¶ 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 NoUturn 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.
Initialise sampler.
 Parameters
nsteps (int) – number of accepted steps until the sample is considered independent.
adaptive_nsteps (False, 'proposaldistance', 'movedistance') – if not false, allow earlier termination than nsteps. The ‘proposaldistance’ 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 ‘movedistance’ strategy stops when the distance between start point and current position exceeds the mean distance between pairs of live points.
transform (function) – called with unit cube position vector u, returns transformed parameter vector p.
loglike (function) – called with transformed parameters p, returns loglikelihood
gradient (function) – called with unit cube position vector u, returns gradient (dlogL/du, not just dlogL/dp)

move
(ui, pi, Li, region, Lmin, ndraw=1, plot=False)[source]¶ 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
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)[source]¶ Compute the stop condition in the main loop dot(dtheta, rminus) >= 0 & dot(dtheta, rplus >= 0)
 thetaminus, thetaplus: ndarray[float, ndim=1]
under and above position
 rminus, rplus: ndarray[float, ndim=1]
under and above momentum
 criterion: bool
return if the condition is valid

ultranest.dyhmc.
leapfrog
(theta, r, grad, epsilon, invmassmatrix, f)[source]¶ 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)[source]¶ The main recursion.

ultranest.dyhmc.
tree_sample
(theta, logp, r0, grad, extra, epsilon, invmassmatrix, f, joint, maxheight=inf)[source]¶ Build NUTSlike tree of sampling path from theta towards p with stepsize epsilon.

ultranest.dyhmc.
find_beta_params_static
(d, u10)[source]¶ 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)[source]¶ Define auxiliary distribution taking into account kinetic energy of a ddimensional 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)[source]¶ draw direction vector according to mass matrix

ultranest.dyhmc.
generate_momentum
(d, massmatrix, alpha, beta)[source]¶ draw momentum from a circle, with amplitude following the beta distribution

ultranest.dyhmc.
generate_momentum_circle
(d, massmatrix)[source]¶ draw from a circle, with a little noise in amplitude

ultranest.dyhmc.
generate_momentum_flattened
(d, massmatrix)[source]¶ 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)[source]¶ 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.

class
ultranest.dyhmc.
DynamicHMCSampler
(ndim, nsteps, transform_loglike_gradient, delta=0.9, nudge=1.04)[source]¶ 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 loglikelihood
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**(1alpha) * (1u)**(1beta) / 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 NoUTurn 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)

move
(ui, pi, Li, gradi, region, ndraw=1, Lflat=None, gradflat=None, plot=False)[source]¶ 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 inversebetabiased HMC trajectory
ultranest.flatnuts module¶
FLATNUTS¶
Experimental.
Directional sampling within regions.
Work in unit cube space. assume a step size.
starting from a live point
choose a random direction based on whitened space metric
for forward and backward direction:
find distance where leaving spheres (surely outside)
bisect the step that leads out of the likelihood threshold
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 usertuned to ensure sufficiently independent samples; starting from 1, look when Z does not change anymore
 param  Step size
 type  Step size
selfadjusting
 Benefit of this algorithm:
insensitive to step size
insensitive to dimensionality (sqrt scaling), better than slice sampling
takes advantage of region information, can accelerate lowd problems as well
 Drawbacks:
inaccurate reflections degrade dimensionality scaling
more complex to implement than slice sampling

class
ultranest.flatnuts.
SingleJumper
(stepsampler, nsteps=0)[source]¶ Bases:
object
Jump on step at a time. If unsuccessful, reverse direction.

class
ultranest.flatnuts.
DirectJumper
(stepsampler, nsteps, log=False)[source]¶ Bases:
object
Jump to n steps immediately. If unsuccessful, takes rest in other direction.

class
ultranest.flatnuts.
IntervalJumper
(stepsampler, nsteps)[source]¶ Bases:
object
Use interval to choose final point randomly

class
ultranest.flatnuts.
ClockedSimpleStepSampler
(contourpath, plot=False, log=False)[source]¶ 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

reverse
(reflpoint, v, plot=False)[source]¶ Reflect off the surface at reflpoint going in direction v
returns the new direction.


class
ultranest.flatnuts.
ClockedStepSampler
(contourpath, plot=False, log=False)[source]¶ Bases:
ultranest.flatnuts.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

class
ultranest.flatnuts.
ClockedBisectSampler
(contourpath, plot=False, log=False)[source]¶ Bases:
ultranest.flatnuts.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

class
ultranest.flatnuts.
ClockedNUTSSampler
(contourpath, plot=False, log=False)[source]¶ Bases:
ultranest.flatnuts.ClockedBisectSampler
NoUturn 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

next
(Llast=None)[source]¶ 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.

ultranest.hotstart module¶
Hot start helper functions.

ultranest.hotstart.
get_auxiliary_problem
(loglike, transform, ctr, invcov, enlargement_factor, df=1)[source]¶ 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 ddimensional Studentt 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 uspace).
invcov (array) – Covariance of the posterior (in uspace).
enlargement_factor (float) –
Factor by which the scale of the auxiliary distribution is enlarged in all dimensions.
For Gaussianlike posteriors, sqrt(ndim) seems to work, Heavier tailed or nonelliptical distributions may need larger factors.
df (float) – Number of degrees of freedom of the auxiliary studentt distribution. The default is recommended. For truly gaussian posteriors, the studentt 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 uspace coordinates, and returns d + 1 pspace 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)[source]¶ 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 ddimensional Studentt distribution.
 Parameters
loglike (function) – original likelihood function
transform (function) – original prior transform function
ctr (array) – Posterior center (in uspace).
invcov (array) – Covariance of the posterior (in uspace).
enlargement_factor (float) –
Factor by which the scale of the auxiliary distribution is enlarged in all dimensions.
For Gaussianlike posteriors, sqrt(ndim) seems to work, Heavier tailed or nonelliptical distributions may need larger factors.
df (float) – Number of degrees of freedom of the auxiliary studentt distribution. The default is recommended. For truly gaussian posteriors, the studentt 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 uspace coordinates, and returns d + 1 pspace parameters. The first d return coordinates are identical to what
transform
would return. The final coordinate is the correction weight.

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)[source]¶ 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)) – Logweights 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 logweight to consider
Returns –
 –
results (dict) – 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), bestfit point information (maximum_likelihood), posterior summaries (posterior).
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)[source]¶ 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) – loglikelihood 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', 'resumesimilar', '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 ‘resumesimilar’, 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.
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=’resumesimilar’; 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'>)[source]¶ 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()
orLivePointsWidget
. 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 KullbackLeibler 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 (1e2 … 1e5) 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) – zscore 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) – Whether to use MLFriends+ellipsoidal+tellipsoidal region (better for multimodal problems) or just ellipsoidal sampling (faster for highdimensional, gaussianlike problems).

run_iter
(update_interval_volume_fraction=0.2, 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'>)[source]¶ 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.

print_results
(logZ=True, posterior=True)[source]¶ Give summary of marginal likelihood and parameters.

plot_corner
()[source]¶ 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)

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=[])[source]¶ 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) – loglikelihood 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
(update_interval_iter=None, update_interval_ncall=None, log_interval=None, dlogz=0.001, max_iters=None)[source]¶ 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.

ultranest.integrator.
read_file
(log_dir, x_dim, num_bootstraps=20, random=True, verbose=False, check_insertion_order=True)[source]¶ 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.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:
ultranest.mlfriends.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 uspace)
maxradiussq (float) – square of the MLFriends radius
minvol (float) – Minimum volume to regularize sample covariance
 Returns
 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 uspace)
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
checking whether a proposed point likely also fulfills the likelihood constraints
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.8/sitepackages/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
 Returns
 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) – tspace transformation layer

class
ultranest.mlfriends.
RobustEllipsoidRegion
(u, transformLayer)¶ Bases:
ultranest.mlfriends.MLFriends
Ellipsoidal region.
Defines a region around nested sampling live points for
checking whether a proposed point likely also fulfills the likelihood constraints
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.8/sitepackages/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 uspace)
maxradiussq (float) – square of the MLFriends radius
minvol (float) – Minimum volume to regularize sample covariance
 Returns
 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 uspace)
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 uspace)
largest gap in live points and wrap parameter space there. (Find) –
example (For) – ***** ****
a wrapped axis has:: (if) – ***** ****
would identify the middle (it) –
it (subtract) –
that the new space (so) –
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.
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.8/sitepackages/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

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.
 Returns
 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.
 Returns
 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
 Returns
 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 uspace)
tpoints (array) – points (in tspace)
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 reused 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)$$ forn
odd : $$2 * (2pi)^((n1)/2) / (1 * 3 * … * n)$$ Parameters
n (int) – dimensionality
 Returns
 Return type
volume (float)
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:
ultranest.mlfriends.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 uspace)
maxradiussq (float) – square of the MLFriends radius
minvol (float) – Minimum volume to regularize sample covariance
 Returns
 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 uspace)
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
checking whether a proposed point likely also fulfills the likelihood constraints
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.8/sitepackages/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
 Returns
 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) – tspace transformation layer

class
ultranest.mlfriends.
RobustEllipsoidRegion
(u, transformLayer)¶ Bases:
ultranest.mlfriends.MLFriends
Ellipsoidal region.
Defines a region around nested sampling live points for
checking whether a proposed point likely also fulfills the likelihood constraints
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.8/sitepackages/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 uspace)
maxradiussq (float) – square of the MLFriends radius
minvol (float) – Minimum volume to regularize sample covariance
 Returns
 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 uspace)
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 uspace)
largest gap in live points and wrap parameter space there. (Find) –
example (For) – ***** ****
a wrapped axis has:: (if) – ***** ****
would identify the middle (it) –
it (subtract) –
that the new space (so) –
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.
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.8/sitepackages/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

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.
 Returns
 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.
 Returns
 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
 Returns
 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 uspace)
tpoints (array) – points (in tspace)
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 reused 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)$$ forn
odd : $$2 * (2pi)^((n1)/2) / (1 * 3 * … * n)$$ Parameters
n (int) – dimensionality
 Returns
 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 subbranches 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 bootstrapcapable 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)[source]¶ Bases:
object
Simple tree node.
Define TreeNode.
 Parameters
value – used to order nodes
id (int) – refers to the order of discovery and storage (PointPile)
children (list of :class:TreeNode objects) – children nodes. if None, a empty list is used.

class
ultranest.netiter.
BreadthFirstIterator
(roots)[source]¶ 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.

next_node
()[source]¶ 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

expand_children_of
(rootid, node)[source]¶ 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 :pyfunc:BreadthFirstIterator.next_node
node (:pyclass:TreeNode) – node returned by the most recent call to :pyfunc:BreadthFirstIterator.next_node


ultranest.netiter.
print_tree
(roots, title='Tree:')[source]¶ Print a pretty yet compact graphic of the tree.
 Parameters
roots (list of :pyclass:TreeNode) – tree

ultranest.netiter.
dump_tree
(filename, roots, pointpile)[source]¶ Write a copy of the tree to a HDF5 file.
 Parameters
filename (str) – output filename
roots (list of :pyclass:TreeNode) – tree to store
pointpile (:class:PointPile) – information on the node points

ultranest.netiter.
count_tree
(roots)[source]¶ Return the total number of nodes and maximum number of parallel edges.
 Parameters
roots (list of :pyclass:TreeNode) – 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)[source]¶ 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 of :pyclass:TreeNode) – 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)[source]¶ 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 (:pyclass: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)[source]¶ Bases:
object
A inmemory linearized storage of point coordinates.
:pyclass:TreeNodes only store the logL value and id, which is the index in the point pile. The point pile stores the point coordinates.
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.

class
ultranest.netiter.
SingleCounter
(random=False)[source]¶ Bases:
object
Evidence log(Z) and posterior weight summation for a Nested Sampling tree.
Initialise counter.
 Parameters
random (bool) – if False, use mean estimator for volume shrinkage if True, draw a random sample

property
logZremain
¶ Estimate conservatively the logZ of the current tail (unopened nodes).

class
ultranest.netiter.
MultiCounter
(nroots, nbootstraps=10, random=False, check_insertion_order=False)[source]¶ Bases:
object
Like SingleCounter, but bootstrap capable.
Attributes:
logZ
,logZerr
,logVolremaining
: main estimatorlogZerr
is probably not reliable, because it needsnlive
to convertH
tologZerr
.Lmax
: highest loglikelihood currently knownlogZ_bs
,logZerr_bs
: bootstrapped logZ estimatelogZremain
,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 bootstrappedistail
: 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

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 (Utest) 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 Utest.
The MWW (Utest) 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)[source]¶ Accumulate node to the integration.
Breadthfirst removed node and nodes active next to node (parallel_nodes). rootid and rootids are needed to identify which bootstrap instance should accumulate.
 Parameters
rootid (:pyclass:TreeNode) – root node this node is from.
node (:pyclass: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)[source]¶ 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 (:pyclass:PointPile) – Point pile.
main_iterator (:pyclass: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), bestfit 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)[source]¶ Run MultiCounter through tree root.
Keeps track of, and returns
(logz, logzerr, logv, nlive)
. Parameters
root (:pyclass:TreeNode) – Tree
pointpile (:pyclass: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 :pyfunc: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¶
MannWhitneyWilcoxon 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 MannWhitneyWilcoxon 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 zscore 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)[source]¶ Compute MannWhitneyWilcoxon 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
[source]¶ Bases:
object
MannWhitneyWilcoxon U test accumulator.
Stores rank orders (1 to N), for comparison with a uniform order.
Initiate empty accumulator.

add
(order, N)[source]¶ Accumulate rank order (0 to N).
 Parameters
N (int) – maximum rank allowed.
order (int) – rank between 0 and N (inclusive).

property
zscore
¶ zscore of the null hypothesis (uniform distribution) probability.

ultranest.pathsampler module¶
MCMClike step sampling on a trajectory.
These features are experimental.

class
ultranest.pathsampler.
SamplingPathSliceSampler
(nsteps)[source]¶ Bases:
ultranest.stepsampler.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 regionbased estimate).
Initialise sampler.
 Parameters
nsteps (int) – number of accepted steps until the sample is considered independent.

generate_direction
(ui, region, scale=1)[source]¶ Choose new initial direction according to region.transformLayer axes.

class
ultranest.pathsampler.
SamplingPathStepSampler
(nresets, nsteps, scale=1.0, balance=0.01, nudge=1.1, log=False)[source]¶ Bases:
ultranest.stepsampler.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.

adjust_accept
(accepted, unew, pnew, Lnew, nc)[source]¶ Adjust proposal given that we have been accepted at a new point after nc calls.

class
ultranest.pathsampler.
OtherSamplerProxy
(nnewdirections, sampler='steps', nsteps=0, balance=0.9, scale=0.1, nudge=1.1, log=False)[source]¶ 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.
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)[source]¶ 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 length2 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 equaltailed. 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 logvolume (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 ~matplotlibstyle 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 3sigma 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 ~matplotlibstyle 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.
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)[source]¶ 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 length2 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 equaltailed. An example would be:
span = [(0., 10.), 0.95, (5., 6.)]
Default is 0.999999426697 (5sigma credible interval) for each parameter.
quantiles (iterable, optional) – A list of fractional quantiles to overplot on the 1D marginalized posteriors as vertical dashed lines. Default is [0.025, 0.5, 0.975] (the 95%/2sigma 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 1D 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 ~matplotlibstyle 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 1D posteriors.
kde (bool, optional) – Whether to use kernel density estimation to estimate and plot the PDF of the importance weights as a function of logvolume (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 ~matplotlibstyle 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 ~matplotlibstyle 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 1D marginalized posterior showing the 0.5 quantile along with the upper/lower bounds associated with the 0.025 and 0.975 (95%/2sigma 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 1D 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 ~matplotlibstyle 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 1D 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={})[source]¶ 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.
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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Reflect vector
v
off anormal
vector, return new direction vector.

ultranest.samplingpath.
distances
(l, o, r=1)[source]¶ Compute sphereline 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.
angle
(a, b)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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 valueInitialise with path starting point.
Starting point (x0), direction (v0) and loglikelihood value (L0) of the path. Is given index 0.

class
ultranest.samplingpath.
ContourSamplingPath
(samplingpath, region)[source]¶ Bases:
object
Regionaware form of the sampling path.
Uses region points to guess a likelihood contour gradient.
Initialise with samplingpath and region.

extrapolate
(i)[source]¶ 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)[source]¶ 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 lowd, 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 highd, 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¶
Dropin replacement for pymultinest.solve.
Example:
from ultranest.solvecompat import pymultinest_solve_compat as solve
# is a dropin 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)[source]¶ Run nested sampling analysis.
Disadvantages compared to using ReactiveNestedSampler directly: cannot resume easily, cannot plot interactively. Limited results.
ultranest.stepsampler module¶
MCMClike 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)[source]¶ 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.stepsampler.
generate_cube_oriented_direction
(ui, region, scale=1)[source]¶ Draw a unit direction vector in direction of a random unit cube axes.
 Parameters
region (MLFriends object) – current region (not used)
 Returns
v – new direction vector
 Return type
array

ultranest.stepsampler.
generate_region_oriented_direction
(ui, region, scale=1)[source]¶ 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 tspace
 Returns
v – new direction vector (in uspace)
 Return type
array

ultranest.stepsampler.
generate_region_random_direction
(ui, region, scale=1)[source]¶ 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 tspace)
 Returns
v – new direction vector
 Return type
array

ultranest.stepsampler.
generate_mixture_random_direction
(ui, region, scale=1, uniform_weight=1e06)[source]¶ Draw from a mix of a ball proposal and a regionshaped proposal.
 Parameters
region (MLFriends) – region
uniform_weight (float) – sets the weight for the equalaxis ball contribution
scale (float) – length of the vector.
 Returns
v – new direction vector
 Return type
array

ultranest.stepsampler.
inside_region
(region, unew, uold)[source]¶ 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)[source]¶

ultranest.stepsampler.
adapt_proposal_total_distances_NN
(region, history, mean_pair_distance, ndim)[source]¶

ultranest.stepsampler.
adapt_proposal_summed_distances
(region, history, mean_pair_distance, ndim)[source]¶

ultranest.stepsampler.
adapt_proposal_summed_distances_NN
(region, history, mean_pair_distance, ndim)[source]¶

ultranest.stepsampler.
adapt_proposal_move_distances
(region, history, mean_pair_distance, ndim)[source]¶

ultranest.stepsampler.
adapt_proposal_move_distances_midway
(region, history, mean_pair_distance, ndim)[source]¶

class
ultranest.stepsampler.
StepSampler
(nsteps, generate_direction, scale=1.0, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False)[source]¶ 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.
adaptive_nsteps (False, 'proposaldistance', 'movedistance') –
Select a strategy to adapt the number of steps. The strategies make sure that:
’movedistance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.
’movedistancemidway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.
’proposaltotaldistances’: mean square distance of proposed vectors exceeds the mean distance between pairs of live points.
’proposaltotaldistancesNN’: mean distance of chain points from starting point exceeds mean distance between pairs of live points.
’proposalsummeddistancesNN’: summed distances between chain points exceeds mean distance between pairs of live points.
’proposalsummeddistancesminNN’: smallest distance between chain points exceeds mean distance between pairs of live points.
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)[source]¶ Plot sampler statistics.
 Parameters
filename (str) – Stores plot into
filename
and data intofilename + ".txt.gz"
.

move
(ui, region, ndraw=1, plot=False)[source]¶ Move around point
ui
. Stub to be implemented by child classes.

adjust_accept
(accepted, unew, pnew, Lnew, nc)[source]¶ 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 uspace)
pnew (array) – new point (in pspace)
Lnew (float) – loglikelihood of new point
nc (int) – number of likelihood function calls used.

adapt_nsteps
(region)[source]¶ Adapt the number of steps.
 Parameters
region (MLFriends object) – current region

class
ultranest.stepsampler.
MHSampler
(nsteps, generate_direction, scale=1.0, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False)[source]¶ Bases:
ultranest.stepsampler.StepSampler
Gaussian Random Walk.
Initialise sampler.
 Parameters
scale (float) – initial proposal size
nsteps (int) – number of accepted steps until the sample is considered independent.
adaptive_nsteps (False, 'proposaldistance', 'movedistance') –
Select a strategy to adapt the number of steps. The strategies make sure that:
’movedistance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.
’movedistancemidway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.
’proposaltotaldistances’: mean square distance of proposed vectors exceeds the mean distance between pairs of live points.
’proposaltotaldistancesNN’: mean distance of chain points from starting point exceeds mean distance between pairs of live points.
’proposalsummeddistancesNN’: summed distances between chain points exceeds mean distance between pairs of live points.
’proposalsummeddistancesminNN’: smallest distance between chain points exceeds mean distance between pairs of live points.
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

class
ultranest.stepsampler.
SliceSampler
(nsteps, generate_direction, scale=1.0, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False)[source]¶ Bases:
ultranest.stepsampler.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.
adaptive_nsteps (False, 'proposaldistance', 'movedistance') –
Select a strategy to adapt the number of steps. The strategies make sure that:
’movedistance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.
’movedistancemidway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.
’proposaltotaldistances’: mean square distance of proposed vectors exceeds the mean distance between pairs of live points.
’proposaltotaldistancesNN’: mean distance of chain points from starting point exceeds mean distance between pairs of live points.
’proposalsummeddistancesNN’: summed distances between chain points exceeds mean distance between pairs of live points.
’proposalsummeddistancesminNN’: smallest distance between chain points exceeds mean distance between pairs of live points.
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)[source]¶ Advance the slice sampling move. see
StepSampler.move()

ultranest.stepsampler.
CubeSliceSampler
(*args, **kwargs)[source]¶ Slice sampler, randomly picking region axes.

ultranest.stepsampler.
RegionSliceSampler
(*args, **kwargs)[source]¶ Slice sampler, randomly picking region axes.

ultranest.stepsampler.
BallSliceSampler
(*args, **kwargs)[source]¶ Hit & run sampler. Choose random directions in space.

ultranest.stepsampler.
RegionBallSliceSampler
(*args, **kwargs)[source]¶ Hit & run sampler. Choose random directions according to region.

ultranest.stepsampler.
RegionSequentialSliceSampler
(*args, **kwargs)[source]¶ Slice sampler, sequentially iterating region axes.

class
ultranest.stepsampler.
SpeedVariableGenerator
(step_matrix, generate_direction=<function generate_region_random_direction>)[source]¶ Bases:
object
Propose directions in region, but only some dimensions at a time, completely userdefinable.
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 29 2/3 times and parameter 59 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)[source]¶ Slice sampler, in region axes.
Updates only some dimensions at a time, completely userdefinable.

ultranest.stepsampler.
ellipsoid_bracket
(ui, v, ellipsoid_center, ellipsoid_inv_axes, ellipsoid_radius_square)[source]¶ 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 uspace)
v (array) – direction vector
ellipsoid_center (array) – center of the ellipsoid
ellipsoid_inv_axes (array) – ellipsoid axes matrix, as computed by :class:WrappingEllipsoid
ellipsoid_radius_square (float) – square of the ellipsoid radius
 Returns
left (float) – distance to go until ellipsoid is intersected (nonpositive)
right (float) – distance to go until ellipsoid is intersected (nonnegative)

ultranest.stepsampler.
crop_bracket_at_unit_cube
(ui, v, left, right, epsilon=1e06)[source]¶ 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 uspace)
v (array) – direction vector
left (float) – bracket lower end (nonpositive)
right (float) – bracket upper end (nonnegative)
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

class
ultranest.stepsampler.
AHARMSampler
(nsteps, adaptive_nsteps=False, max_nsteps=1000, region_filter=False, log=False, direction=<function generate_region_random_direction>, orthogonalise=True)[source]¶ Bases:
ultranest.stepsampler.StepSampler
Accelerated hitandrun/slice sampler, vectorised.
Uses region ellipsoid to propose a sequence of points on a randomly drawn line.
(in development)
Initialise vectorised hitandrun/slice sampler.
 Parameters
nsteps (int) – number of accepted steps until the sample is considered independent.
adaptive_nsteps (False, 'proposaldistance', 'movedistance') –
Select a strategy to adapt the number of steps. The strategies make sure that:
’movedistance’ (recommended): distance between start point and final position exceeds the mean distance between pairs of live points.
’movedistancemidway’: distance between start point and position in the middle of the chain exceeds the mean distance between pairs of live points.
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.
direction (function) – function that draws slice direction given a point and the current region.
orthogonalise (bool) – If true, make subsequent proposed directions orthogonal to each other.
log (file) – log file for sampler statistics, such as acceptance rate, proposal scale, number of steps, jump distance and distance between live points
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.
FilePointStore
[source]¶ Bases:
object
Base class for storing points in a file.

class
ultranest.store.
TextPointStore
(filepath, ncols)[source]¶ Bases:
ultranest.store.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).

class
ultranest.store.
HDF5PointStore
(filepath, ncols, **h5_file_args)[source]¶ Bases:
ultranest.store.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
= []¶

ultranest.utils module¶
Utility functions for logging and statistics.

ultranest.utils.
create_logger
(module_name, log_dir=None, level=20)[source]¶ Set up the logging channel module_name.
Append to
debug.log
in log_dir (if notNone
). 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)[source]¶ 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.
resample_equal
(samples, weights, rstate=None)[source]¶ 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,).
 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)[source]¶ 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)[source]¶ 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)[source]¶ Volume constant for an ndimensional sphere.
for n even: $$ (2pi)^(n /2) / (2 * 4 * … * n)$$ for n odd : $$2 * (2pi)^((n1)/2) / (1 * 3 * … * n)$$
 Parameters
n (int) – Dimensionality
 Returns
Volume
 Return type
float

ultranest.utils.
is_affine_transform
(a, b)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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.viz module¶
Visual impression of current exploration.

ultranest.viz.
round_parameterlimits
(plo, phi, paramlimitguess=None)[source]¶ 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)[source]¶ 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.
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)