0
# Step Sampling Techniques
1

2
Modular step sampling algorithms for efficient exploration of parameter spaces within nested sampling. UltraNest provides various sampling techniques that can be customized based on the problem geometry and likelihood structure.
3

4
## Capabilities
5

6
### Base Step Samplers
7

8
Foundation classes for implementing custom step sampling algorithms.
9

10
```python { .api }
11
class StepSampler:
12
    """Base class for all step samplers."""
13

14
class MHSampler(StepSampler):
15
    """Metropolis-Hastings sampler for general parameter space exploration."""
16

17
class SliceSampler(StepSampler):
18
    """Slice sampler providing robust sampling for complex geometries."""
19
```
20

21
### Convenience Samplers
22

23
Pre-configured sampler factory functions combining sampling algorithms with direction generators for common use cases.
24

25
```python { .api }
26
def CubeMHSampler(*args, **kwargs):
27
    """Metropolis-Hastings sampler with cube-oriented direction generation."""
28

29
def RegionMHSampler(*args, **kwargs):
30
    """Metropolis-Hastings sampler with region-oriented directions."""
31

32
def CubeSliceSampler(*args, **kwargs):
33
    """Slice sampler using axis-aligned directions."""
34

35
def RegionSliceSampler(*args, **kwargs):
36
    """Slice sampler with region-adaptive directions."""
37

38
def BallSliceSampler(*args, **kwargs):
39
    """Slice sampler constrained to ball geometry."""
40

41
def RegionBallSliceSampler(*args, **kwargs):
42
    """Slice sampler combining region and ball constraints."""
43
```
44

45
### Direction Generation Functions
46

47
Functions for generating sampling directions based on different geometric strategies.
48

49
```python { .api }
50
def generate_random_direction(ui, region, scale=1):
51
    """
52
    Generate random direction for sampling moves.
53
    
54
    Parameters:
55
    - ui: Current point in unit cube
56
    - region: Current constraining region
57
    - scale (float): Direction scaling factor
58
    
59
    Returns:
60
    array: Random direction vector
61
    """
62

63
def generate_cube_oriented_direction(ui, region, scale=1):
64
    """
65
    Generate axis-aligned direction for cube-oriented sampling.
66
    
67
    Parameters:
68
    - ui: Current point in unit cube
69
    - region: Current constraining region  
70
    - scale (float): Direction scaling factor
71
    
72
    Returns:
73
    array: Axis-aligned direction vector
74
    """
75

76
def generate_region_oriented_direction(ui, region, scale=1):
77
    """
78
    Generate direction oriented towards region structure.
79
    
80
    Parameters:
81
    - ui: Current point in unit cube
82
    - region: Current constraining region
83
    - scale (float): Direction scaling factor
84
    
85
    Returns:
86
    array: Region-oriented direction vector
87
    """
88

89
def generate_region_random_direction(ui, region, scale=1):
90
    """
91
    Generate random direction within region constraints.
92
    
93
    Parameters:
94
    - ui: Current point in unit cube
95
    - region: Current constraining region
96
    - scale (float): Direction scaling factor
97
    
98
    Returns:
99
    array: Random region-constrained direction
100
    """
101

102
def generate_mixture_random_direction(ui, region, scale=1):
103
    """
104
    Generate direction using mixture of strategies.
105
    
106
    Parameters:
107
    - ui: Current point in unit cube
108
    - region: Current constraining region
109
    - scale (float): Direction scaling factor
110
    
111
    Returns:
112
    array: Mixed strategy direction vector
113
    """
114
```
115

116
### Direction Generators
117

118
Classes for systematic direction generation with adaptive behavior.
119

120
```python { .api }
121
class SequentialDirectionGenerator:
122
    """Generate directions in sequential patterns."""
123

124
class SequentialRegionDirectionGenerator:
125
    """Generate region-based sequential directions."""
126

127
class OrthogonalDirectionGenerator:
128
    """Generate orthogonal direction sets."""
129

130
class SpeedVariableGenerator:
131
    """Adaptive speed control for direction generation."""
132
```
133

134
### Population Samplers
135

136
Advanced samplers that work with multiple points simultaneously for improved efficiency.
137

138
```python { .api }
139
class PopulationRandomWalkSampler:
140
    """Population-based random walk sampler."""
141

142
class PopulationSliceSampler:
143
    """Population-based slice sampler."""
144

145
class PopulationSimpleSliceSampler:
146
    """Simplified population slice sampler."""
147
```
148

149
### Population Direction Functions
150

151
Direction generation functions optimized for population-based sampling.
152

153
```python { .api }
154
def generate_cube_oriented_direction_scaled(*args, **kwargs):
155
    """Generate scaled cube-oriented directions for populations."""
156

157
def generate_random_direction(*args, **kwargs):
158
    """Generate random directions for population sampling."""
159

160
def generate_region_oriented_direction(*args, **kwargs):
161
    """Generate region-oriented directions for populations."""
162

163
def generate_region_random_direction(*args, **kwargs):
164
    """Generate region-random directions for populations."""
165
```
166

167
## Advanced Sampling Algorithms
168

169
### Dynamic Hamiltonian Monte Carlo
170

171
High-performance sampling using Hamiltonian dynamics for smooth likelihood surfaces.
172

173
```python { .api }
174
class DynamicHMCSampler:
175
    """Dynamic Hamiltonian Monte Carlo sampler for smooth posteriors."""
176

177
class FlattenedProblem:
178
    """Flattened problem formulation for HMC sampling."""
179
```
180

181
### No-U-Turn Sampler (NUTS)
182

183
Adaptive Hamiltonian Monte Carlo that automatically tunes step sizes and trajectory lengths.
184

185
```python { .api }
186
class ClockedNUTSSampler:
187
    """No-U-Turn sampler with clock-based termination."""
188

189
class ClockedBisectSampler:
190
    """Bisection sampler with clock-based timing."""
191

192
class ClockedStepSampler:
193
    """Clock-based step sampler for precise control."""
194
```
195

196
### Trajectory Samplers
197

198
Specialized samplers for trajectory-based exploration.
199

200
```python { .api }
201
class SingleJumper:
202
    """Single-jump trajectory sampler."""
203

204
class DirectJumper:
205
    """Direct trajectory jumping."""
206

207
class IntervalJumper:
208
    """Interval-based trajectory sampling."""
209
```
210

211
### Path Samplers
212

213
Samplers that use path-based exploration strategies.
214

215
```python { .api }
216
class SamplingPathSliceSampler(StepSampler):
217
    """Path-based slice sampling algorithm."""
218

219
class SamplingPathStepSampler(StepSampler):
220
    """Path-based step sampling algorithm."""
221
```
222

223
## Usage Examples
224

225
### Custom Step Sampler Configuration
226

227
```python
228
from ultranest import ReactiveNestedSampler
229
from ultranest.stepsampler import RegionSliceSampler
230

231
# Create sampler with custom step sampler
232
sampler = ReactiveNestedSampler(
233
    param_names=['x', 'y', 'z'],
234
    loglike=loglike,
235
    transform=prior_transform
236
)
237

238
# Configure step sampler (done automatically by ReactiveNestedSampler)
239
# Manual configuration would be:
240
# step_sampler = RegionSliceSampler()
241
# sampler.stepsampler = step_sampler
242
```
243

244
### Population-Based Sampling
245

246
```python
247
from ultranest.popstepsampler import PopulationSliceSampler
248

249
# Population sampling is typically configured automatically
250
# based on problem dimensionality and structure
251
```
252

253
### Advanced Sampling for Smooth Posteriors
254

255
```python
256
from ultranest.dyhmc import DynamicHMCSampler
257

258
# HMC sampling is automatically selected for smooth,
259
# differentiable likelihood functions when beneficial
260
```
261

262
## Sampler Selection Guidelines
263

264
### Problem-Dependent Recommendations
265

266
- **General problems**: ReactiveNestedSampler automatically selects appropriate step samplers
267
- **High-dimensional smooth**: Dynamic HMC samplers for differentiable likelihoods  
268
- **Complex geometries**: Region-oriented slice samplers
269
- **Multimodal distributions**: Mixed direction generation with random components
270
- **Constrained parameters**: Ball slice samplers for bounded regions
271
- **Circular parameters**: Wrapped parameter handling with appropriate direction generators
272

273
### Performance Considerations
274

275
- **Population samplers**: More efficient for high-dimensional problems
276
- **HMC/NUTS**: Best for smooth, differentiable posteriors
277
- **Slice samplers**: Robust for complex, irregular likelihood surfaces
278
- **MH samplers**: Simple and reliable for general use
279

280
The ReactiveNestedSampler automatically selects and adapts step sampling strategies based on the problem characteristics, making manual configuration unnecessary for most applications.