UltraNest

https://johannesbuchner.github.io/UltraNest/
Admin
UltraNest is a Python package implementing advanced nested sampling techniques for Bayesian...
Tokens:279,290
Snippets:1,954
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### setup_start

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

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

```APIDOC
## setup_start(us, Ls, starting)

### Description
Initialize walker starting points.
For iteration zero, randomly selects a live point as starting point.

### Parameters
#### Parameters
- **us** (_np.array_ _(__(__nlive_ _,__ndim_ _)__)_) – live points
- **Ls** (_np.array_ _(__nlive_ _)_) – loglikelihoods live points
- **starting** (_np.array_ _(__nwalkers_ _,__dtype=bool_ _)_) – which walkers to initialize.
```

--------------------------------

### Install UltraNest from Source

Source: https://johannesbuchner.github.io/UltraNest/installation.html

After obtaining the source code (either by cloning or downloading), install UltraNest using the setup.py script.

```bash
python setup.py install

```

--------------------------------

### setup_brackets

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Pick starting direction and range for slice.

```APIDOC
## setup_brackets(mask_starting, region)

### Description
Pick starting direction and range for slice.

### Parameters
#### Parameters
- **mask_starting** (_np.array_ _(__nwalkers_ _,__dtype=bool_ _)_) – which walkers to set up.
- **region** (_MLFriends object_) – Region
```

--------------------------------

### UltraneSt Sampling Output Example 4

Source: https://johannesbuchner.github.io/UltraNest/example-line.html

Shows UltraneSt sampler progress, including sampling live points and widening roots, typical for the start of a run.

```text
[ultranest] Sampling 400 live points from prior ...
[ultranest] Widening roots to 474 live points (have 400 already) ...
[ultranest] Sampling 74 live points from prior ...
[ultranest] Widening roots to 560 live points (have 474 already) ...
[ultranest] Sampling 86 live points from prior ...

```

--------------------------------

### Install UltraNest using pip

Source: https://johannesbuchner.github.io/UltraNest/installation.html

This is the preferred method for installing the most recent stable release of UltraNest. Ensure pip is installed.

```bash
pip install ultranest

```

--------------------------------

### PopulationSliceSampler.setup_start

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/popstepsampler.html

Initializes walker starting points using live points from the current population.

```APIDOC
## PopulationSliceSampler.setup_start(self, us, Ls, starting)

### Description
Initialize walker starting points. For iteration zero, randomly selects a live point as starting point.

### Parameters
- **us** (np.array) - Live points with shape (nlive, ndim).
- **Ls** (np.array) - Log-likelihoods of live points with shape (nlive,).
- **starting** (np.array) - Boolean mask indicating which walkers to initialize.
```

--------------------------------

### Startup OtherSamplerProxy

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/pathsampler.html

Chooses a new random starting point for the sampler from the provided live points that satisfy the current region. Asserts that at least one point satisfies the region and initializes the 'last' attribute with the chosen starting point.

```python
def startup(self, region, us, Ls):
        """Choose a new random starting point."""
        if self.log:
            print("starting from scratch...")
        mask = region.inside(us)
        assert mask.any(), (
            "Not all of the live points satisfy the current region!",
            region.maxradiussq, region.u[~mask,:], region.unormed[~mask,:], us[~mask,:])
        i = np.random.randint(mask.sum())
        self.starti = i
        ui = us[mask,:][i]
        assert np.logical_and(ui > 0, ui < 1).all(), ui
        Li = Ls[mask][i]
        self.last = ui, Li
```

--------------------------------

### Set Up Local Development Environment

Source: https://johannesbuchner.github.io/UltraNest/contributing.html

Install your local copy of UltraNest into a virtual environment using `python setup.py develop`.

```bash
$ mkvirtualenv ultranest
$ cd ultranest/
$ python setup.py develop

```

--------------------------------

### Setup Current Parameters Array

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/popstepsampler.html

Initializes the `currentp` array, which stores the current parameter values for each walker. This is typically called before starting a new sampling iteration.

```python
def _setup_currentp(self, nparams):
        if self.log:
            print("setting currentp")
        self.currentp = np.zeros((self.popsize, nparams)) + np.nan
```

--------------------------------

### Install Cython and UltraNest

Source: https://johannesbuchner.github.io/UltraNest/installation.html

If you encounter a 'ModuleNotFoundError: No module named ‘Cython’', install Cython first, then install UltraNest.

```bash
pip install cython
pip install ultranest

```

--------------------------------

### Run Ultranest with Warm Start Initialization

Source: https://johannesbuchner.github.io/UltraNest/example-warmstart.html

Instantiate `ReactiveNestedSampler` with the warm-started functions and run the sampler.

```python
sampler = ReactiveNestedSampler(aux_paramnames, aux_log_likelihood, aux_prior_transform, vectorized=vectorized)
res = sampler.run(frac_remain=0.5)
```

--------------------------------

### Initialize Warm Start from Similar File

Source: https://johannesbuchner.github.io/UltraNest/example-warmstart.html

Use `warmstart_from_similar_file` to set up accelerated likelihood and prior transform functions based on a reference run.

```python
from ultranest.integrator import warmstart_from_similar_file

aux_paramnames, aux_log_likelihood, aux_prior_transform, vectorized = warmstart_from_similar_file(
    posterior_upoints_file, parameters, log_likelihood_with_background, prior_transform)
```

--------------------------------

### UltraneSt Sampling Output Example 1

Source: https://johannesbuchner.github.io/UltraNest/example-line.html

Example output from the UltraneSt sampler during the initial stages of a run, showing the process of sampling live points and widening roots.

```text
[ultranest] Sampling 400 live points from prior ...
[ultranest] Widening roots to 427 live points (have 400 already) ...
[ultranest] Sampling 27 live points from prior ...
[ultranest] Widening roots to 455 live points (have 427 already) ...
[ultranest] Sampling 28 live points from prior ...

```

--------------------------------

### Get Info Dictionary

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/popstepsampler.html

Returns a dictionary containing information about the sampler. This is a placeholder method.

```python
dict(

# Inside GenericPopulationSampler class:
def get_info_dict(self):
    return dict(
```

--------------------------------

### Selecting a Starting Point in Ultranest Path Sampler

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/pathsampler.html

When no previous point is available, this code selects a new random starting point within the defined region. It asserts that at least one live point satisfies the region's constraints before proceeding.

```python
        # select starting point
        if Li is None:
            # choose a new random starting point
            mask = region.inside(us)
            assert mask.any(), (
                "None of the live points satisfies the current region!",
                region.maxradiussq, region.u, region.unormed, us)
            i = np.random.randint(mask.sum())
            self.starti = i
            ui = us[mask,:][i]
            if self.log:
                print("starting at", ui)
            assert np.logical_and(ui > 0, ui < 1).all(), ui
            Li = Ls[mask][i]
            self.start()
            self.history.append((ui, Li))
            self.last = (ui, Li)
```

--------------------------------

### UltraneSt Sampling Output Example 3

Source: https://johannesbuchner.github.io/UltraNest/example-line.html

Shows UltraneSt sampler progress, detailing the sampling of live points and the widening of roots during a run.

```text
[ultranest] Sampling 400 live points from prior ...
[ultranest] Widening roots to 437 live points (have 400 already) ...
[ultranest] Sampling 37 live points from prior ...
[ultranest] Widening roots to 477 live points (have 437 already) ...
[ultranest] Sampling 40 live points from prior ...

```

--------------------------------

### ReactiveNestedCalibrator Usage Example

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/calibrator.html

Demonstrates how to use ReactiveNestedCalibrator as a drop-in replacement for ReactiveNestedSampler. The `run` method will automatically calibrate the number of steps.

```python
sampler = ReactiveNestedCalibrator(my_param_names, my_loglike, my_transform)
sampler.stepsampler = SliceSampler(nsteps=10, generate_direction=region_oriented_direction)
sampler.run(min_num_livepoints=400)
```

--------------------------------

### DyHMCSampler Get Next Point

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/dyhmc.html

Generates a new sample point using the dynamic HMC algorithm, starting from a given live point and loglikelihood threshold.

```APIDOC
## __next__(self, region, Lmin, us, Ls, transform, loglike, ndraw=40, plot=False, tregion=None)

### Description
Get a new point.

### Parameters
#### Parameters
- **region**: MLFriends - The current region object.
- **Lmin**: float - The loglikelihood threshold.
- **us**: array of vectors - Current live points.
- **Ls**: array of floats - Current live point likelihoods.
- **transform**: function - The transformation function.
- **loglike**: function - The loglikelihood function.
- **ndraw** (int) - Number of draws to attempt simultaneously. Defaults to 40.
- **plot** (bool) - Whether to produce debug plots. Defaults to False.
- **tregion**: object - Optional region object for trajectory analysis.
```

--------------------------------

### Install UltraNest using Conda

Source: https://johannesbuchner.github.io/UltraNest/installation.html

For users who prefer the Conda package manager, UltraNest can be installed from the conda-forge channel.

```bash
conda install --channel conda-forge ultranest

```

--------------------------------

### Warmstart from Similar File

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/integrator.html

Initializes a new sampling run by loading samples from a previous run's output file, facilitating warm-starting.

```APIDOC
## warmstart_from_similar_file(usample_filename, param_names, loglike, transform, vectorized=False, min_num_samples=50)

### Description
Warmstart from a previous run.

### Method
`warmstart_from_similar_file(usample_filename, param_names, loglike, transform, vectorized=False, min_num_samples=50)`

### Parameters
#### Path Parameters
- **usample_filename** (str) - Required - 'directory/chains/weighted_post_untransformed.txt' contains posteriors in u-space (untransformed) of a previous run. Columns are weight, logl, param1, param2, ...
- **min_num_samples** (int) - Optional - minimum number of samples in the usample_filename file required. Too few samples will give a poor approximation.

#### Other Parameters
- **param_names**: list
- **loglike**: function
- **transform**: function
- **vectorized**: bool

### Returns
- **aux_param_names**: list - new parameter list
- **aux_loglikelihood**: function - new loglikelihood function
- **aux_transform**: function - new prior transform function
- **vectorized**: bool - whether the new functions are vectorized
```

--------------------------------

### Initialize and run UltraNest sampler with warm start

Source: https://johannesbuchner.github.io/UltraNest/example-warmstart.html

Initializes the UltraNest sampler with a reference run folder and the 'overwrite' resume option. It then runs the sampler and prints the results.

```python
from ultranest import ReactiveNestedSampler

reference_run_folder = 'blackbody-alldata'
sampler_ref = ReactiveNestedSampler(parameters, log_likelihood, prior_transform, log_dir=reference_run_folder, resume='overwrite')
results_ref = sampler_ref.run(frac_remain=0.5)
sampler_ref.print_results()
```

--------------------------------

### SpeedVariableGenerator full update example

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Example of using `np.ones` to ensure a full update of all parameters in every step when using `SpeedVariableGenerator`.

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

--------------------------------

### Basic UltraNest Usage

Source: https://johannesbuchner.github.io/UltraNest/using-ultranest.html

Import the library, initialize the ReactiveNestedSampler with parameter names, likelihood, and prior transform functions, run the sampler, and print the results. Set resume=True to continue a previous analysis.

```python
import ultranest

sampler = ultranest.ReactiveNestedSampler(param_names, my_likelihood, my_prior_transform,
    log_dir="myanalysis", resume=True)
result = sampler.run()
sampler.print_results()

```

--------------------------------

### Initialize Ultrane.st Integrator

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/integrator.html

Sets up the nested sampler with parameter names, log-likelihood function, and optional transformations. Handles resume logic and MPI setup.

```python
def __init__(self,
                 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=[],
                 ):
        """Set up nested sampler.

        Parameters
        -----------
        param_names: list of str, names of the parameters.
            Length gives dimensionality of the sampling problem.
        loglike: function
            log-likelihood function.
            Receives multiple parameter vectors, returns vector of likelihood.
        transform: function
            parameter transform from unit cube to physical parameters.
            Receives multiple cube vectors, returns multiple parameter vectors.
        derived_param_names: list of str
            Additional derived parameters created by transform. (empty by default)
        log_dir: str
            where to store output files
        resume: 'resume', 'overwrite' or 'subfolder'
            if 'overwrite', overwrite previous data.
            if 'subfolder', create a fresh subdirectory in log_dir.
            if 'resume' or True, continue previous run if available.
        wrapped_params: list of bools
            indicating whether this parameter wraps around (circular parameter).
        num_live_points: int
            Number of live points
        vectorized: bool
            If true, loglike and transform function can receive arrays
            of points.
        run_num: int
            unique run number. If None, will be automatically incremented.

        """
        self.paramnames = list(param_names)
        x_dim = len(self.paramnames)
        self.num_live_points = num_live_points
        self.sampler = 'nested'
        self.x_dim = x_dim
        self.derivedparamnames = derived_param_names
        num_derived = len(self.derivedparamnames)
        self.num_params = x_dim + num_derived
        self.volfactor = vol_prefactor(self.x_dim)
        if wrapped_params is None:
            self.wrapped_axes = []
        else:
            self.wrapped_axes = np.where(wrapped_params)[0]

        assert resume or resume in ('overwrite', 'subfolder', 'resume'), "resume should be one of 'overwrite' 'subfolder' or 'resume'"
        append_run_num = resume == 'subfolder'
        resume = resume == 'resume' or resume

        if not vectorized:
            transform = vectorize(transform)
            loglike = vectorize(loglike)

        if transform is None:
            self.transform = lambda x: x
        else:
            self.transform = transform

        u = np.random.uniform(size=(2, self.x_dim))
        p = self.transform(u)
        assert p.shape == (2, self.num_params), ("Error in transform function: returned shape is %s, expected %s" % (p.shape, (2, self.num_params)))
        logl = loglike(p)
        assert np.logical_and(u > 0, u < 1).all(), ("Error in transform function: u was modified!")
        assert np.shape(logl) == (2,), ("Error in loglikelihood function: returned shape is %s, expected %s" % (p.shape, (2, self.num_params)))
        assert np.isfinite(logl).all(), ("Error in loglikelihood function: returned non-finite number: %s for input u=%s p=%s" % (logl, u, p))

        def safe_loglike(x):
            """Call likelihood function safely wrapped to avoid non-finite values."""
            x = np.asarray(x)
            logl = loglike(x)
            assert np.isfinite(logl).all(), (
                'User-provided loglikelihood returned non-finite value:',
                logl[~np.isfinite(logl)][0],
                "for input value:",
                x[~np.isfinite(logl),:][0,:])
            return logl

        self.loglike = safe_loglike

        self.use_mpi = False
        try:
            from mpi4py import MPI
            self.comm = MPI.COMM_WORLD
            self.mpi_size = self.comm.Get_size()
            self.mpi_rank = self.comm.Get_rank()
            if self.mpi_size > 1:
                self.use_mpi = True
        except Exception:
            self.mpi_size = 1
            self.mpi_rank = 0

        self.log = self.mpi_rank == 0
        self.log_to_disk = self.log and log_dir is not None

        if self.log and log_dir is not None:
            self.logs = make_run_dir(log_dir, run_num, append_run_num=append_run_num)
            log_dir = self.logs['run_dir']
        else:
            log_dir = None

        self.logger = create_logger(__name__ + '.' + type(self).__name__, log_dir=log_dir)

        if self.log:
            self.logger.info('Num live points [%d]', self.num_live_points)

        if self.log_to_disk:
            # self.pointstore = TextPointStore(os.path.join(self.logs['results'], 'points.tsv'), 2 + self.x_dim + self.num_params)

```

--------------------------------

### Calculate Warm Start Speed-up

Source: https://johannesbuchner.github.io/UltraNest/example-warmstart.html

Quantify the speed-up achieved by warm starting by comparing the number of likelihood calls between the reference and warm-started runs.

```python
print("Speed-up of warm-start: %d%%" % ((results_ref['ncall'] / res['ncall'] - 1)*100))
```

--------------------------------

### SpeedVariableGenerator step_matrix example

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Example of configuring the `step_matrix` for `SpeedVariableGenerator` to control which parameters are updated in each step. This matrix can be a boolean matrix or a list of slices.

```python
[[True, True], [False, True], [False, True]]
```

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

--------------------------------

### ultranest.integrator.warmstart_from_similar_file

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Initializes a new UltraNest run by warm-starting from the posterior samples of a previous run, facilitating efficient continuation or modification of analyses.

```APIDOC
## ultranest.integrator.warmstart_from_similar_file

### Description
Warmstart from a previous run.

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

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

See `ultranest.hotstart.get_auxiliary_contbox_parameterization()` for more information. The remaining parameters have the same meaning as in `ReactiveNestedSampler`.

### Parameters
#### Path Parameters
- **usample_filename** (str) - Required - ‘directory/chains/weighted_post_untransformed.txt’ contains posteriors in u-space (untransformed) of a previous run. Columns are weight, logl, param1, param2, …
#### Query Parameters
- **min_num_samples** (int) - Optional - minimum number of samples in the usample_filename file required. Too few samples will give a poor approximation.
- **param_names** (list) - Required
- **loglike** (function) - Required
- **transform** (function) - Required
- **vectorized** (bool) - Optional

### Returns
- **aux_param_names** (list) - new parameter list
- **aux_loglikelihood** (function) - new loglikelihood function
- **aux_transform** (function) - new prior transform function
- **vectorized** (bool) - whether the new functions are vectorized
```

--------------------------------

### Scale Jitter Function Example

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

A user-supplied function to randomly adjust the slice width. This example uses a truncated normal distribution to generate a random factor.

```python
lambda : scipy.stats.truncnorm.rvs(-0.5, 5., loc=0, scale=1)+1.()
```

--------------------------------

### Hot Start: Using Previous Results for Initialization

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/hotstart.html

This snippet demonstrates how to load previous run results and use them to initialize a new UltraNest run. The `resume` parameter takes the loaded results, and `continue_from` specifies whether to resume from the posterior distribution or the best point found in the previous run.

```python
import ultranest

# Load results from a previous run
results = ultranest.load_results("previous_run_results.json")

# Define the model and parameters for the new run
def my_model(params):
    # Your model definition here
    return -0.5 * (params['x']**2 + params['y']**2)

params = [
    {'name': 'x', 'lower': -5, 'upper': 5},
    {'name': 'y', 'lower': -5, 'upper': 5}
]

# Initialize and run UltraNest, resuming from the loaded results
# 'continue_from' can be 'resume' or 'resume_from_best'
# 'resume' uses the posterior distribution from the previous run
# 'resume_from_best' uses the maximum likelihood point from the previous run

# Example: resuming from the posterior distribution
# ultranest.run(model=my_model, params=params, results_dir='hot_start_run', 
#                 resume=results, continue_from='resume', n_live_points=1000)

# Example: resuming from the best point found in the previous run
# ultranest.run(model=my_model, params=params, results_dir='hot_start_run_best', 
#                 resume=results, continue_from='resume_from_best', n_live_points=1000)

print("Hot start configuration prepared.")

```

--------------------------------

### Start New Sampling Chain

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/stepsampler.html

Resets the sampler's history and rejection count to start a new sampling chain. This is useful for restarting the sampling process or exploring a new region.

```python
def new_chain(self, region=None):
        """Start a new path, reset statistics."""
        self.history = []
        self.nrejects = 0
```

--------------------------------

### Populate and Return Sample

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/popstepsampler.html

Retrieves and returns a prepared sample from the sampler's internal storage.

```python
u, p, L = self.prepared_samples.pop(0)
return u, p, L, nc
```

--------------------------------

### Create Weighted Posterior File for Warm Start

Source: https://johannesbuchner.github.io/UltraNest/example-warmstart.html

Generate a text file containing equally weighted posterior samples in u-space. This file is used to initialize a warm start run.

```python
weights = np.ones((len(usamples), 1)) / len(usamples)
logl = np.zeros(len(usamples)).reshape((-1, 1))

np.savetxt(
    'custom-weighted_post_untransformed.txt',
    np.hstack((weights, logl, usamples)),
    header=' '.join(['weight', 'logl'] + parameters),
    fmt='%f'
)
```

--------------------------------

### Initialize Ultrane.st Sampler

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/integrator.html

Initializes the Ultrane.st sampler with various configuration options. Supports MPI for distributed computing and configurable logging and storage backends.

```python
x_dim = len(self.paramnames)

self.sampler = 'reactive-nested'
self.x_dim = x_dim
self.transform_layer_class = LocalAffineLayer if x_dim > 1 else ScalingLayer
self.derivedparamnames = derived_param_names
self.num_bootstraps = int(num_bootstraps)
num_derived = len(self.derivedparamnames)
self.num_params = x_dim + num_derived
if wrapped_params is None:
    self.wrapped_axes = []
else:
    assert len(wrapped_params) == self.x_dim, ("wrapped_params has the number of entries:", wrapped_params, ", expected", self.x_dim)
    self.wrapped_axes = np.where(wrapped_params)[0]

self.use_mpi = False
try:
    from mpi4py import MPI
    self.comm = MPI.COMM_WORLD
    self.mpi_size = self.comm.Get_size()
    self.mpi_rank = self.comm.Get_rank()
    if self.mpi_size > 1:
        self.use_mpi = True
        self._setup_distributed_seeds()
except Exception:
    self.mpi_size = 1
    self.mpi_rank = 0

self.log = self.mpi_rank == 0
self.log_to_disk = self.log and log_dir is not None
self.log_to_pointstore = self.log_to_disk

assert resume in (True, 'overwrite', 'subfolder', 'resume', 'resume-similar'), \
    "resume should be one of 'overwrite' 'subfolder', 'resume' or 'resume-similar'"
append_run_num = resume == 'subfolder'
resume_similar = resume == 'resume-similar'
resume = resume in ('resume-similar', 'resume', True)

if self.log and log_dir is not None:
    self.logs = make_run_dir(log_dir, run_num, append_run_num=append_run_num)
    log_dir = self.logs['run_dir']
else:
    log_dir = None

if self.log:
    self.logger = create_logger('ultranest', log_dir=log_dir)
    self.logger.debug('ReactiveNestedSampler: dims=%d+%d, resume=%s, log_dir=%s, backend=%s, vectorized=%s, nbootstraps=%s, ndraw=%s..%s' % (
        x_dim, num_derived, resume, log_dir, storage_backend, vectorized,
        num_bootstraps, ndraw_min, ndraw_max,
    ))
self.root = TreeNode(id=-1, value=-np.inf)

self.pointpile = PointPile(self.x_dim, self.num_params)
if self.log_to_pointstore:
    storage_filename = os.path.join(self.logs['results'], 'points.' + storage_backend)
    storage_num_cols = 3 + self.x_dim + self.num_params
    if storage_backend == 'tsv':
        self.pointstore = TextPointStore(storage_filename, storage_num_cols)
        self.pointstore.delimiter = '\n'
    elif storage_backend == 'csv':
        self.pointstore = TextPointStore(storage_filename, storage_num_cols)
        self.pointstore.delimiter = ','
    elif storage_backend == 'hdf5':
        self.pointstore = HDF5PointStore(storage_filename, storage_num_cols, mode='a' if resume else 'w')
    else:
        # use custom backend
        self.pointstore = storage_backend
else:
    self.pointstore = NullPointStore(3 + self.x_dim + self.num_params)
self.ncall = self.pointstore.ncalls
self.ncall_region = 0

if not vectorized:
    if transform is not None:
        transform = vectorize(transform)
    loglike = vectorize(loglike)
    draw_multiple = False

self.draw_multiple = draw_multiple
self.ndraw_min = ndraw_min
self.ndraw_max = ndraw_max
self.build_tregion = transform is not None
if not self._check_likelihood_function(transform, loglike, num_test_samples):
    assert self.log_to_disk
    if resume_similar and self.log_to_disk:
        assert storage_backend == 'hdf5', 'resume-similar is only supported for HDF5 files'
        assert 0 <= warmstart_max_tau <= 1, 'warmstart_max_tau parameter needs to be set to a value between 0 and 1'
        # close
        self.pointstore.close()
        del self.pointstore
        # rewrite points file
        if self.log:
            self.logger.info('trying to salvage points from previous, different run ...')
        resume_from_similar_file(
            log_dir, x_dim, loglike, transform,
            ndraw=ndraw_min if vectorized else 1,
            max_tau=warmstart_max_tau, verbose=False)
        self.pointstore = HDF5PointStore(
            os.path.join(self.logs['results'], 'points.hdf5'),
            3 + self.x_dim + self.num_params, mode='a' if resume else 'w')
    elif resume:
        raise Exception("Cannot resume because loglikelihood function changed, "

```

--------------------------------

### UltraneSt Sampling Output Example 2

Source: https://johannesbuchner.github.io/UltraNest/example-line.html

Shows UltraneSt sampler progress, including sampling live points and widening roots, similar to initial stages of a run.

```text
[ultranest] Sampling 400 live points from prior ...
[ultranest] Widening roots to 487 live points (have 400 already) ...
[ultranest] Sampling 87 live points from prior ...
[ultranest] Widening roots to 592 live points (have 487 already) ...
[ultranest] Sampling 105 live points from prior ...

```

--------------------------------

### TextPointStore Initialization

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/store.html

Initializes a TextPointStore to load and append points to a text file. Opens the file in append binary mode and sets format and delimiter.

```python
def __init__(self, filepath, ncols):
    """Load and append to storage at *filepath*.

    The file should contain *ncols* columns (Lmin, L, and others).
    """
    self.ncols = int(ncols)
    self.nrows = 0
    self.stack_empty = True
    self._load(filepath)
    self.fileobj = open(filepath, 'ab')  # noqa: SIM115
    self.fmt = '%.18e'
    self.delimiter = '\t'
```

--------------------------------

### Warm-start from Similar File

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/integrator.html

Loads samples from a previous run's 'weighted_post_untransformed.txt' file to warm-start a new sampler. Ensures a minimum number of samples are loaded for a reliable approximation.

```python
def warmstart_from_similar_file(
    usample_filename,
    param_names,
    loglike,
    transform,
    vectorized=False,
    min_num_samples=50
):
    """Warmstart from a previous run.

    Usage::

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

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

    See :py:func:`ultranest.hotstart.get_auxiliary_contbox_parameterization`
    for more information.

    The remaining parameters have the same meaning as in :py:class:`ReactiveNestedSampler`.

    Parameters
    ------------
    usample_filename: str
        'directory/chains/weighted_post_untransformed.txt'
        contains posteriors in u-space (untransformed) of a previous run.
        Columns are weight, logl, param1, param2, ...
    min_num_samples: int
        minimum number of samples in the usample_filename file required.
        Too few samples will give a poor approximation.

    Other Parameters
    -----------------
    param_names: list
    loglike: function
    transform: function
    vectorized: bool

    Returns
    ---------
    aux_param_names: list
        new parameter list
    aux_loglikelihood: function
        new loglikelihood function
    aux_transform: function
        new prior transform function
    vectorized: bool
        whether the new functions are vectorized
    """
    # load samples
    try:
        with open(usample_filename) as f:
            old_param_names = f.readline().lstrip('#').strip().split()
            auxiliary_usamples = np.loadtxt(f)
    except IOError:
        warnings.warn('not hot-resuming, could not load file "%s"' % usample_filename, stacklevel=2)
        return param_names, loglike, transform, vectorized
```

--------------------------------

### ultranest.samplingpath.distances

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Computes the intersection points of a line (starting from the origin) with a sphere.

```APIDOC
## distances(_direction_, _center_, _r=1_)

### Description
Compute sphere-line intersection.

### Parameters
#### Path Parameters
- **direction** (_vector_) – direction vector (line starts at 0)
- **center** (_vector_) – center of sphere (coordinate vector)
- **r** (_float_) – radius of sphere

### Returns
- **tpos, tneg** (_floats_) – the positive and negative coordinate along the l vector where r is intersected. If no intersection, throws AssertError.
```

--------------------------------

### BreadthFirstIterator Reset

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Resets the BreadthFirstIterator to start exploration from the top of the tree.

```python
def reset(self):
    """(Re)start exploration from the top."""
    pass
```

--------------------------------

### Run Ultrane.st Sampler

Source: https://johannesbuchner.github.io/UltraNest/example-intrinsic-distribution.html

Execute the sampler to perform nested sampling. The initial run explores the parameter space with a default number of live points.

```python
result = sampler.run()
```

--------------------------------

### new_chain

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/stepsampler.html

Starts a new sampling chain and resets associated statistics.

```APIDOC
## new_chain

### Description
Start a new path, reset statistics.

### Parameters
None
```

--------------------------------

### Initialize and Run Ultranest Sampler

Source: https://johannesbuchner.github.io/UltraNest/example-sine-line.html

Initializes the Ultranest sampler with the defined parameters, likelihood, prior transform, and wrapped parameters. It then runs the sampling process to obtain posterior distributions and evidence.

```python
from ultranest import ReactiveNestedSampler

sampler = ReactiveNestedSampler(parameters, log_likelihood, prior_transform,
    wrapped_params=[False, False, False, True],
)
```

```python
result = sampler.run(min_num_live_points=400, dKL=np.inf, min_ess=100)
```

--------------------------------

### ClockedNUTSSampler.sample_chain_point

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Gets a point on the track between two given points (inclusive).

```APIDOC
## ultranest.flatnuts.ClockedNUTSSampler.sample_chain_point(_a_, _b_)

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

### Method
sample_chain_point

### Parameters
* **a** (array) - Required - starting point
* **b** (array) - Required - end point

### Returns
* **newpoint** (tuple) - tuple of point_coordinates and loglikelihood
* **is_independent** (bool) - always True
```

--------------------------------

### move

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/pathsampler.html

Advances the move by getting the point corresponding to the next index.

```APIDOC
## move

### Description
Advance the move by getting the point corresponding to the next index determined by `movei`.

### Method
`move(ui, region, ndraw=1, plot=False)`

### Parameters
#### Path Parameters
- **ui** (array) - Current point.
- **region** (MLFriends) - The region object.
- **ndraw** (int, optional) - Number of draws. Defaults to 1.
- **plot** (bool, optional) - Whether to produce debug plots. Defaults to False.

### Returns
- array: The proposed point.
```

--------------------------------

### ultranest.viz.LivePointsWidget.initialize

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Initializes and displays the LivePointsWidget for notebooks.

```APIDOC
## ultranest.viz.LivePointsWidget.initialize

### Description
Set up and display the LivePointsWidget. This widget shows where the live points are currently in parameter space.

### Parameters
#### Path Parameters
- **paramnames** (list of str) - Required - Parameter names.
- **width** (int) - Required - Number of html table columns.
```

--------------------------------

### Get Point from Pile

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/netiter.html

Retrieves a point from the internal storage given its index.

```python
def getu(self, i):
        """Get cube point(s) with index(indices) `i`."""
        return self.us[i]
```

```python
def getp(self, i):
        """Get parameter point(s) with index(indices) `i`."""
        return self.ps[i]
```

--------------------------------

### Import ultranest.solvecompat as solve

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Import the ultranest solvecompat module as a drop-in replacement for pymultinest.solve.

```python
from ultranest.solvecompat import pymultinest_solve_compat as solve

# is a drop-in replacement for

from pymultinest.solve import solve
```

--------------------------------

### SliceSampler Move Method - Initial Interval Setup

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/stepsampler.html

Advances the slice sampling process. If the interval is not yet defined, it generates a direction and sets initial left and right bounds for the slice, preparing for the sampling step.

```python
def move(self, ui, region, ndraw=1, plot=False):
        """Advance the slice sampling move. see :py:meth:`StepSampler.move`."""
        if self.interval is None:
            v = self.generate_direction(ui, region)

            # expand direction until it is surely outside
            left = -self.scale
            right = self.scale
            self.found_left = False
            self.found_right = False
            u = 0

            self.interval = (v, left, right, u)

        else:
            v, left, right, u = self.interval

        if plot:
            plt.plot([(ui + v * left)[0], (ui + v * right)[0]],
                     [(ui + v * left)[1], (ui + v * right)[1]],
                     ':o', color='k', lw=2, alpha=0.3)

        # shrink direction if outside
        if not self.found_left:
            xj = ui + v * left

            if not self.region_filter or inside_region(region, xj.reshape((1, -1)), ui):
                return xj.reshape((1, -1))
            else:
                self.found_left = True

        if not self.found_right:
            xj = ui + v * right

            if not self.region_filter or inside_region(region, xj.reshape((1, -1)), ui):

```

--------------------------------

### Initialize Ultrane.st Sampler

Source: https://johannesbuchner.github.io/UltraNest/example-intrinsic-distribution.html

Initialize the ReactiveNestedSampler with parameters, log-likelihood function, and prior transform. This sets up the core of the nested sampling process.

```python
import ultranest

sampler = ultranest.ReactiveNestedSampler(parameters, log_likelihood, prior_transform)
```

--------------------------------

### Warm start

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Reweights an existing nested sampling run onto a new loglikelihood function.

```APIDOC
## Warm start

Reweight existing nested sampling run onto a new loglikelihood.

### Parameters

* **param_names** (_list_ _of_ _strings_) – Names of the parameters
* **loglike** (_function_) – New likelihood function
* **points** (_np.array_ _of_ _shape_ _(__npoints_ _,__ndim_ _)_) – Equally weighted (unless logw is passed) posterior points
* **logl** (_np.array_ _(__npoints_ _)_) – Previously likelihood values of points
* **logw** (_np.array_ _(__npoints_ _)_) – Log-weights of existing points.
* **logz** (_float_) – Previous evidence / marginal likelihood value.
* **logzerr** (_float_) – Previous evidence / marginal likelihood uncertainty.
* **upoints** (_np.array_ _of_ _shape_ _(__npoints_ _,__ndim_ _)_) – Posterior points before transformation.
* **vectorized** (_bool_) – Whether loglike function is vectorized
* **batchsize** (_int_) – Number of points simultaneously passed to vectorized loglike function
* **log_weight_threshold** (_float_) – Lowest log-weight to consider

### Returns

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

### Return type

dict
```

--------------------------------

### Initialize DyCHMC Sampler

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/dychmc.html

Initializes the DyCHMC sampler with parameters controlling step size, adaptation, and trajectory exploration. Raises ValueError if adaptive_nsteps is not a valid option.

```python
def __init__(self, scale, nsteps, adaptive_nsteps=False, delta=0.9, nudge=1.04):
        self.history = []
        self.nsteps = nsteps
        self.scale = scale
        self.nudge = nudge
        self.nsteps_nudge = 1.01
        adaptive_nsteps_options = (False, 'proposal-total-distances-NN', 'proposal-summed-distances-NN',
            'proposal-total-distances', 'proposal-summed-distances',
            'move-distance', 'move-distance-midway', 'proposal-summed-distances-min-NN',
            'proposal-variance-min', 'proposal-variance-min-NN')

        if adaptive_nsteps not in adaptive_nsteps_options:
            raise ValueError("adaptive_nsteps must be one of: %s, not '%s'" % (adaptive_nsteps_options, adaptive_nsteps))
        self.adaptive_nsteps = adaptive_nsteps
        self.mean_pair_distance = np.nan
        self.delta = delta
        self.massmatrix = 1
        self.invmassmatrix = 1

        self.logstat = []
        self.logstat_labels = ['acceptance_rate', 'reflect_fraction', 'stepsize', 'treeheight']
        if adaptive_nsteps:
            self.logstat_labels += ['jump-distance', 'reference-distance']
        self.logstat_trajectory = []
```

--------------------------------

### Get current likelihood threshold

Source: https://johannesbuchner.github.io/UltraNest/debugging.html

Access the current minimum likelihood threshold the sampler is operating at.

```python
sampler.Lmin
```

--------------------------------

### Initialize and Run Sampler

Source: https://johannesbuchner.github.io/UltraNest/using-ultranest.html

Initializes the ReactiveNestedSampler with the defined parameter names, likelihood, and prior transform functions, then runs the sampling process.

```python
import ultranest

sampler = ultranest.ReactiveNestedSampler(param_names, my_likelihood, my_prior_transform)


```

```python
result = sampler.run()
sampler.print_results()

```

--------------------------------

### Initialize NestedSampler

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Set up the `NestedSampler` by providing essential functions like log-likelihood and parameter transformation, along with configuration options for output directory and resume behavior.

```python
from ultranest.integrator import NestedSampler

sampler = NestedSampler(
    param_names=["x", "y"],
    loglike=lambda x: -0.5 * (x**2).sum(axis=1),
    transform=lambda x: x, # Identity transform for simplicity
    resume='subfolder',
    log_dir='logs/test',
    num_live_points=1000,
    vectorized=False,
)
```

--------------------------------

### region_changed

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/dychmc.html

Reacts to a change in the sampling region by adjusting the step size and recreating the problem setup.

```APIDOC
## region_changed

### Description
React to change of region.

### Parameters
- **Ls** (array of floats) - Live point likelihoods in the new region.
- **region** (MLFriends region object) - The new region object.
```

--------------------------------

### Island Class Call

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/stepsampler.html

Selects a live point as a chain starting point within the island structure.

```APIDOC
## Island.__call__

### Description
Select live point as chain starting point.

### Parameters
#### Path Parameters
- **us** (array) - positions of live points
- **Ls** (array) - likelihood of live points
- **Lmin** (float) - current log-likelihood threshold

### Returns
- **i** (int) - index of live point selected.
```

--------------------------------

### Run a Subset of Tests

Source: https://johannesbuchner.github.io/UltraNest/contributing.html

Execute a specific subset of tests, for example, tests within the `tests.test_utils` module.

```bash
$ PYTHONPATH=. pytest tests.test_utils

```

--------------------------------

### PopulationSliceSampler.__init__

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/popstepsampler.html

Initializes the PopulationSliceSampler with parameters for walker population, steps, direction generation, and scale adaptation.

```APIDOC
## PopulationSliceSampler.__init__

### Description
Initializes the PopulationSliceSampler with parameters for walker population, steps, direction generation, and scale adaptation.

### Parameters
#### Parameters
- **popsize** (int) - number of walkers to maintain
- **nsteps** (int) - number of steps to take until the found point is accepted as independent. To find the right value, see :py:class:`ultranest.calibrator.ReactiveNestedCalibrator`
- **generate_direction** (function `(u, region, scale) -> v`) - function such as `generate_unit_directions`, which generates a random slice direction.
- **scale** (float) - initial guess scale for the length of the slice
- **scale_adapt_factor** (float) - smoothing factor for updating scale.
- **log** (bool) - not used
- **logfile** (file object or None) - file to write log information to
```

--------------------------------

### Get String Representation of DyHMCSampler

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/dyhmc.html

Returns a string representation of the DyHMCSampler object, including the number of steps.

```python
def __str__(self):
        """Get string representation."""
        return type(self).__name__ + '(nsteps=%d)' % self.nsteps
```

--------------------------------

### Initialize UltraNest ReactiveNestedSampler

Source: https://johannesbuchner.github.io/UltraNest/performance.html

Sets up the ReactiveNestedSampler with parameter names, the vectorized log-likelihood function, and an optional transformation function. Resume functionality is enabled, and `vectorized=True` is specified to leverage the vectorized likelihood.

```python
from ultranest import ReactiveNestedSampler

def transform(x):
    return x

paramnames = ['param%d' % (i+1) for i in range(ndim)]

sampler = ReactiveNestedSampler(paramnames, loglike, transform=transform, 
    log_dir=args.log_dir + 'RNS-%dd' % ndim, resume=True,
    vectorized=True)
```

--------------------------------

### Problem Setup for DyCHMC

Source: https://johannesbuchner.github.io/UltraNest/_modules/ultranest/dychmc.html

Sets up auxiliary distributions and mass matrices based on the current region's transform layer. Handles different layer types and their properties.

```python
        # problem dimensionality
        layer = region.transformLayer

        if hasattr(layer, 'invT'):
            self.invmassmatrix = layer.cov
            self.massmatrix = np.linalg.inv(self.invmassmatrix)
        elif hasattr(layer, 'std'):
            if np.shape(layer.std) == () and layer.std == 1:
                self.massmatrix = 1
                self.invmassmatrix = 1
            else:
                # invmassmatrix: covariance
                self.invmassmatrix = np.diag(layer.std[0]**2)
                self.massmatrix = np.diag(layer.std[0]**-2)
                print(self.invmassmatrix.shape, layer.std)
```

--------------------------------

### Test MPI communication

Source: https://johannesbuchner.github.io/UltraNest/debugging.html

Executes a simple MPI command to verify that your MPI installation is working correctly and that cores can communicate.

```bash
!mpiexec -np 4 python3 -c 'from mpi4py import MPI; print(MPI.COMM_WORLD.Get_rank(), MPI.COMM_WORLD.Get_size())'
```

--------------------------------

### Initialize AffineLayer

Source: https://johannesbuchner.github.io/UltraNest/ultranest.html

Initializes an AffineLayer for affine whitening transformation. Parameters can be learned from points using the `optimize()` method.

```python
AffineLayer(_ctr =0_, _T =1_, _invT =1_, _nclusters =1_, _wrapped_dims =[]_, _clusterids =None_)
```
Tokens:
Raw