0
# UltraNest
1

2
UltraNest is a Python library that implements advanced nested sampling techniques for Bayesian inference. It enables scientists and researchers to fit complex models to data, constrain model parameters through posterior probability distributions, and compare different models using Bayesian evidence calculations. The library specializes in Monte Carlo nested sampling methods that are particularly effective for high-dimensional parameter spaces and complex likelihood functions.
3

4
## Package Information
5

6
- **Package Name**: ultranest
7
- **Language**: Python
8
- **Installation**: `pip install ultranest`
9

10
## Core Imports
11

12
```python
13
import ultranest
14
from ultranest import ReactiveNestedSampler, NestedSampler
15
```
16

17
Common imports for sampling:
18

19
```python
20
from ultranest import ReactiveNestedSampler, read_file, vectorize, warmstart_from_similar_file
21
```
22

23
## Basic Usage
24

25
```python
26
import numpy as np
27
from ultranest import ReactiveNestedSampler
28

29
# Define parameter names
30
param_names = ['x', 'y', 'z']
31

32
# Define log-likelihood function
33
def loglike(theta):
34
    """Log-likelihood function for your model"""
35
    x, y, z = theta
36
    # Your likelihood calculation here
37
    return -0.5 * (x**2 + y**2 + z**2)
38

39
# Define parameter transformation (unit cube to physical parameters)
40
def prior_transform(cube):
41
    """Transform from unit cube [0,1] to parameter space"""
42
    params = cube.copy()
43
    # Transform each parameter, e.g., uniform [-10, 10]
44
    params[0] = cube[0] * 20 - 10  # x
45
    params[1] = cube[1] * 20 - 10  # y  
46
    params[2] = cube[2] * 20 - 10  # z
47
    return params
48

49
# Create and run sampler
50
sampler = ReactiveNestedSampler(
51
    param_names, 
52
    loglike, 
53
    transform=prior_transform
54
)
55

56
# Run the sampling
57
result = sampler.run()
58

59
# Print results
60
sampler.print_results()
61

62
# Access results
63
print("Evidence (log Z):", result['logz'])
64
print("Parameter estimates:", result['posterior']['mean'])
65
```
66

67
## Architecture
68

69
UltraNest's modular architecture enables flexible Bayesian inference workflows:
70

71
- **Core Samplers**: ReactiveNestedSampler (adaptive) and NestedSampler (traditional) provide the main nested sampling algorithms
72
- **Step Samplers**: Modular sampling techniques (Metropolis-Hastings, Slice Sampling, HMC) for efficient parameter space exploration
73
- **ML Friends Regions**: Machine learning-based region definitions and transformations for constraining parameter spaces
74
- **Storage Backends**: Flexible data storage options (HDF5, CSV, TSV) for results persistence
75
- **Visualization**: Built-in plotting capabilities for posterior analysis and diagnostics
76

77
This design allows researchers to customize every aspect of the sampling process while maintaining ease of use for standard applications.
78

79
## Capabilities
80

81
### Core Nested Samplers
82

83
Main nested sampling implementations for Bayesian parameter estimation and model comparison. ReactiveNestedSampler provides adaptive sampling ideal for most applications, while NestedSampler offers traditional nested sampling with fixed live points.
84

85
```python { .api }
86
class ReactiveNestedSampler:
87
    def __init__(
88
        self,
89
        param_names: list,
90
        loglike: callable,
91
        transform: callable = None,
92
        derived_param_names: list = [],
93
        wrapped_params: list = None,
94
        resume: str = 'subfolder',
95
        run_num: int = None,
96
        log_dir: str = None,
97
        num_test_samples: int = 2,
98
        draw_multiple: bool = True,
99
        num_bootstraps: int = 30,
100
        vectorized: bool = False,
101
        ndraw_min: int = 128,
102
        ndraw_max: int = 65536,
103
        storage_backend: str = 'hdf5',
104
        warmstart_max_tau: float = -1
105
    ): ...
106
    
107
    def run(self, **kwargs): ...
108
    def run_iter(self, **kwargs): ...
109
    def print_results(self, use_unicode: bool = True): ...
110
    def plot(self): ...
111
    def plot_corner(self): ...
112
    def plot_trace(self): ...
113
    def plot_run(self): ...
114
    def store_tree(self): ...
115
    
116
    @property
117
    def results(self): ...
118
    @property
119
    def stepsampler(self): ...
120

121
class NestedSampler:
122
    def __init__(
123
        self,
124
        param_names: list,
125
        loglike: callable,
126
        transform: callable = None,
127
        derived_param_names: list = [],
128
        resume: str = 'subfolder',
129
        run_num: int = None,
130
        log_dir: str = 'logs/test',
131
        num_live_points: int = 1000,
132
        vectorized: bool = False,
133
        wrapped_params: list = []
134
    ): ...
135
    
136
    def run(self, **kwargs): ...
137
    def print_results(self): ...
138
    def plot(self): ...
139
```
140

141
[Core Samplers](./core-samplers.md)
142

143
### Step Sampling Techniques
144

145
Modular step sampling algorithms for efficient exploration of parameter spaces within nested sampling. Includes Metropolis-Hastings, slice sampling, and specialized direction generators for different problem geometries.
146

147
```python { .api }
148
class StepSampler: ...
149
class MHSampler(StepSampler): ...
150
class SliceSampler(StepSampler): ...
151

152
def CubeMHSampler(*args, **kwargs): ...
153
def RegionMHSampler(*args, **kwargs): ...
154
def CubeSliceSampler(*args, **kwargs): ...
155
def RegionSliceSampler(*args, **kwargs): ...
156
def BallSliceSampler(*args, **kwargs): ...
157
def RegionBallSliceSampler(*args, **kwargs): ...
158

159
def generate_random_direction(ui, region, scale=1): ...
160
def generate_cube_oriented_direction(ui, region, scale=1): ...
161
def generate_region_oriented_direction(ui, region, scale=1): ...
162
```
163

164
[Step Samplers](./step-samplers.md)
165

166
### ML Friends Regions
167

168
Machine learning-based region definitions and parameter transformations for constraining nested sampling. Provides efficient methods for defining likelihood regions and applying transformations to improve sampling efficiency.
169

170
```python { .api }
171
class MLFriends: ...
172
class RobustEllipsoidRegion(MLFriends): ...
173
class SimpleRegion(RobustEllipsoidRegion): ...
174
class WrappingEllipsoid: ...
175

176
class ScalingLayer: ...
177
class AffineLayer(ScalingLayer): ...
178
class LocalAffineLayer(AffineLayer): ...
179
```
180

181
[ML Friends Regions](./ml-friends-regions.md)
182

183
### Plotting and Visualization
184

185
Built-in plotting capabilities for posterior analysis, convergence diagnostics, and model comparison. Generate corner plots, trace plots, and run diagnostics to interpret nested sampling results.
186

187
```python { .api }
188
def cornerplot(results, **kwargs): ...
189
def runplot(results, **kwargs): ...
190
def traceplot(results, **kwargs): ...
191

192
class PredictionBand: ...
193
```
194

195
[Plotting](./plotting.md)
196

197
### Utilities and File I/O
198

199
Essential utilities for data processing, file operations, and integration with other tools. Includes vectorization helpers, logging setup, and compatibility layers.
200

201
```python { .api }
202
def read_file(log_dir: str, x_dim: int, **kwargs): ...
203
def warmstart_from_similar_file(
204
    usample_filename: str,
205
    param_names: list,
206
    loglike: callable,
207
    transform: callable,
208
    vectorized: bool = False,
209
    min_num_samples: int = 50
210
): ...
211
def vectorize(function: callable): ...
212
def create_logger(module_name: str, log_dir: str = None, level=logging.INFO): ...
213
def resample_equal(samples, weights, rstate=None): ...
214
def quantile(x, q, weights=None): ...
215
```
216

217
[Utilities](./utilities.md)
218

219
## Configuration Options
220

221
### Storage Backends
222
- `'hdf5'`: HDF5 file storage (recommended for performance)
223
- `'tsv'`: Tab-separated values (human-readable)
224
- `'csv'`: Comma-separated values (compatible)
225

226
### Resume Strategies
227
- `'resume'`: Continue from existing run
228
- `'resume-similar'`: Resume from similar run configuration
229
- `'overwrite'`: Start fresh, overwriting existing files
230
- `'subfolder'`: Create new subfolder for each run
231

232
## Error Handling
233

234
UltraNest functions may raise various exceptions:
235

236
- **ValueError**: Invalid parameter values or configurations
237
- **FileNotFoundError**: Missing required files during resume operations
238
- **MemoryError**: Insufficient memory for large parameter spaces
239
- **RuntimeError**: Sampling convergence issues or numerical errors
240

241
Always wrap sampler creation and execution in appropriate exception handling for robust analysis pipelines.