tessl/pypi-ultranest

Fit and compare complex models reliably and rapidly with advanced nested sampling techniques for Bayesian inference.

Overview

Eval results

Files

ML Friends Regions

Name: tessl/pypi-ultranest
Author: tessl

Machine learning-based region definitions and parameter transformations for constraining nested sampling. These components provide efficient methods for defining likelihood regions and applying transformations to improve sampling efficiency in high-dimensional parameter spaces.

Capabilities

Core Region Classes

Base region implementations for constraining parameter space exploration.

class MLFriends:
    """
    Machine learning friends region using nearest neighbor analysis.
    
    Automatically determines constrained regions based on the distribution
    of live points, enabling efficient sampling in complex parameter spaces.
    """

class RobustEllipsoidRegion(MLFriends):
    """
    Robust ellipsoidal region with outlier handling.
    
    Combines ellipsoidal approximation with robust statistics to handle
    outliers and irregular likelihood contours effectively.
    """

class SimpleRegion(RobustEllipsoidRegion):
    """
    Simplified region implementation for basic constraints.
    
    Provides essential region functionality with minimal computational
    overhead for standard nested sampling applications.
    """

class WrappingEllipsoid:
    """
    Ellipsoid with support for wrapped/periodic parameters.
    
    Handles circular parameters (angles, phases) by wrapping the
    ellipsoidal region across parameter boundaries.
    """

Transform Layers

Hierarchical transformations for parameter space conditioning and dimensionality reduction.

class ScalingLayer:
    """
    Basic parameter scaling transformations.
    
    Applies scaling transformations to normalize parameter ranges
    and improve sampling efficiency across different scales.
    """

class AffineLayer(ScalingLayer):
    """
    Affine transformations including rotation and translation.
    
    Extends scaling with rotation and translation capabilities
    for handling correlated parameters and coordinate system changes.
    """

class LocalAffineLayer(AffineLayer):
    """
    Locally adaptive affine transformations.
    
    Applies different affine transformations in different regions
    of parameter space for optimal local conditioning.
    """

class MaxPrincipleGapAffineLayer(AffineLayer):
    """
    Affine layer based on maximum principle gap analysis.
    
    Uses gap statistics to determine optimal transformation
    parameters for maximum sampling efficiency.
    """

Region Analysis Functions

Utility functions for analyzing and manipulating regions and point distributions.

def find_nearby(points, query_point, region, **kwargs):
    """
    Find points near a query location within region constraints.
    
    Parameters:
    - points (array): Set of points to search
    - query_point (array): Location to search around
    - region: Constraining region
    
    Returns:
    array: Indices of nearby points
    """

def subtract_nearby(points, query_point, region, **kwargs):
    """
    Remove nearby points from a point set.
    
    Parameters:
    - points (array): Set of points to filter
    - query_point (array): Reference location
    - region: Constraining region
    
    Returns:
    array: Filtered point set with nearby points removed
    """

def compute_mean_pair_distance(points, **kwargs):
    """
    Compute mean pairwise distance in point set.
    
    Parameters:
    - points (array): Set of points for analysis
    
    Returns:
    float: Mean pairwise distance
    """

def bounding_ellipsoid(points, **kwargs):
    """
    Compute bounding ellipsoid for point set.
    
    Parameters:
    - points (array): Points to bound
    
    Returns:
    Ellipsoid parameters and transformation matrix
    """

Usage Examples

Basic Region Usage

from ultranest import ReactiveNestedSampler
from ultranest.mlfriends import RobustEllipsoidRegion

# Region selection is typically automatic within ReactiveNestedSampler
sampler = ReactiveNestedSampler(
    param_names=['x', 'y', 'z'],
    loglike=loglike,
    transform=prior_transform
)

# Manual region configuration (advanced usage)
# region = RobustEllipsoidRegion()
# sampler.region = region

Transform Layer Application

from ultranest.mlfriends import AffineLayer

# Transform layers are automatically configured based on
# parameter correlations and problem structure

Custom Region Analysis

import numpy as np
from ultranest.mlfriends import find_nearby, compute_mean_pair_distance

# Analyze point distribution
points = np.random.randn(1000, 3)  # Example points
query = np.array([0, 0, 0])

# Find nearby points
nearby_indices = find_nearby(points, query, region=None)

# Compute characteristic distance scale
mean_distance = compute_mean_pair_distance(points)

Advanced Region Configuration

Wrapped Parameters

For problems with circular parameters (angles, phases):

from ultranest.mlfriends import WrappingEllipsoid

# Configure wrapped parameters during sampler creation
sampler = ReactiveNestedSampler(
    param_names=['amplitude', 'phase', 'frequency'],
    loglike=loglike,
    transform=prior_transform,
    wrapped_params=[1]  # Phase parameter is circular
)

# Wrapping ellipsoid is automatically used for wrapped parameters

Multi-Scale Problems

For problems with parameters spanning different scales:

# Scaling layers are automatically applied based on parameter ranges
def prior_transform(cube):
    params = cube.copy()
    params[0] = cube[0] * 1e-6        # Small scale parameter
    params[1] = cube[1] * 1e6         # Large scale parameter  
    params[2] = cube[2] * 1.0         # Normal scale parameter
    return params

# ReactiveNestedSampler automatically handles scale differences
sampler = ReactiveNestedSampler(
    param_names=['small', 'large', 'normal'],
    loglike=loglike,
    transform=prior_transform
)

High-Dimensional Spaces

For problems with many parameters and complex correlations:

# LocalAffineLayer and advanced transformations are automatically
# selected for high-dimensional problems with complex structure

param_names = [f'param_{i}' for i in range(50)]  # 50 parameters

sampler = ReactiveNestedSampler(
    param_names=param_names,
    loglike=high_dim_loglike,
    transform=high_dim_prior_transform
)

# Advanced region analysis and transformations applied automatically

Region Selection Guidelines

Automatic Selection

The ReactiveNestedSampler automatically selects appropriate region types based on:

Parameter dimensionality: Higher dimensions use more sophisticated regions
Correlation structure: Correlated parameters trigger affine transformations
Wrapped parameters: Circular parameters activate wrapping ellipsoids
Likelihood complexity: Complex likelihoods use robust region methods

Manual Configuration

For specialized applications requiring manual control:

# Access region configuration after initialization
sampler = ReactiveNestedSampler(...)
current_region = sampler.region

# Modify region parameters (advanced usage)
# current_region.update_parameters(...)

Performance Tuning

Simple problems: SimpleRegion provides minimal overhead
Robust analysis: RobustEllipsoidRegion handles outliers and irregular contours
Correlated parameters: Affine layers improve efficiency for parameter correlations
Wrapped parameters: WrappingEllipsoid essential for circular parameter spaces

The ML Friends region system provides automatic adaptation to problem structure while allowing manual control for specialized applications. The reactive sampler selects optimal region configurations based on problem analysis during the sampling process.

Install with Tessl CLI