HypercubeMappingPrior¶

Flexible prior distributions with hypercube mapping.

Overview¶

HypercubeMappingPrior maps between a hypercube domain and various target distributions. This enables uniform treatment of different prior types during training while preserving the original distribution semantics.

Supported Distributions¶

Type	Parameters	Description
`uniform`	`low`, `high`	Uniform distribution
`normal`	`mean`, `std`	Gaussian distribution
`cosine`	`low`, `high`	Distribution with pdf proportional to sin(angle)
`sine`	`low`, `high`	Inverse sine mapping
`uvol`	`low`, `high`	Uniform-in-volume
`triangular`	`a`, `c`, `b`	Triangular distribution (min, mode, max)

Usage¶

from falcon.contrib import HypercubeMappingPrior

# Define priors for 3 parameters
prior = HypercubeMappingPrior(
    priors=[
        ('uniform', -10.0, 10.0),
        ('normal', 0.0, 1.0),
        ('triangular', -1.0, 0.0, 1.0),
    ]
)

# Sample from prior
samples = prior.simulate_batch(1000)

# Transform to/from hypercube space
u = prior.inverse(samples)   # To hypercube
x = prior.forward(u)         # From hypercube

YAML Configuration¶

simulator:
  _target_: falcon.contrib.HypercubeMappingPrior
  priors:
    - ['uniform', -10.0, 10.0]
    - ['normal', 0.0, 1.0]
  hypercube_range: [-2, 2]

Class Reference¶

HypercubeMappingPrior ¶

HypercubeMappingPrior(priors=[], hypercube_range=[-2, 2])

Maps a set of univariate priors between a hypercube domain and their target distributions.

This class supports a bi-directional transformation

forward: maps from a hypercube domain (default range [-2, 2]) to the target distributions.
inverse: maps from the target distribution domain back to the hypercube.

Supported distribution types and their required parameters

"uniform": Linear mapping from [0, 1] to [low, high]. Parameters: low, high.
"cosine": Uses an acos transform for distributions with pdf ∝ sin(angle). Parameters: low, high.
"sine": Uses an asin transform for a similar angular mapping. Parameters: low, high.
"uvol": Uniform-in-volume transformation. Parameters: low, high.
"normal": Maps using the inverse CDF (probit function) for a normal distribution. Parameters: mean, std.
"triangular": Maps to a triangular distribution via its inverse CDF. Parameters: a (min), c (mode), b (max).

Priors should be provided as a list of tuples

(dist_type, param1, param2, ...)

For example, a uniform prior would be ("uniform", low, high) and a triangular prior would be ("triangular", a, c, b).

Initializes the HypercubeMappingPrior object.

Parameters:

Name	Type	Description	Default
`priors`	`list`	List of tuples defining each prior. Each tuple starts with a string specifying the distribution type, followed by its parameters.	`[]`
`hypercube_range`	`list or tuple`	The range of the hypercube domain (default: [-2, 2]).	`[-2, 2]`

Source code in falcon/contrib/hypercubemappingprior.py

def __init__(self, priors=[], hypercube_range=[-2, 2]):
    """
    Initializes the HypercubeMappingPrior object.

    Args:
        priors (list): List of tuples defining each prior. Each tuple starts with a string specifying
                       the distribution type, followed by its parameters.
        hypercube_range (list or tuple): The range of the hypercube domain (default: [-2, 2]).
    """
    self.priors = priors
    self.param_dim = len(priors)
    self.hypercube_range = hypercube_range

forward ¶

forward(u)

Applies the forward transformation to a batch of input values.

The input tensor u should have shape (..., n_params), where the last dimension corresponds to different parameters (each in the hypercube_range). First, the values are rescaled to [0,1] and then mapped into the corresponding target distributions.

Parameters:

Name	Type	Description	Default
`u`	`Tensor`	Tensor of shape (..., n_params) with values in the hypercube_range.	required

Returns:

Type	Description
	torch.Tensor: Tensor of shape (..., n_params) with values in the target distribution domains.

Source code in falcon/contrib/hypercubemappingprior.py

def forward(self, u):
    """
    Applies the forward transformation to a batch of input values.

    The input tensor u should have shape (..., n_params), where the last dimension
    corresponds to different parameters (each in the hypercube_range). First, the values
    are rescaled to [0,1] and then mapped into the corresponding target distributions.

    Args:
        u (torch.Tensor): Tensor of shape (..., n_params) with values in the hypercube_range.

    Returns:
        torch.Tensor: Tensor of shape (..., n_params) with values in the target distribution domains.
    """
    # Rescale u from hypercube_range to [0, 1]
    u = (u - self.hypercube_range[0]) / (
        self.hypercube_range[1] - self.hypercube_range[0]
    )
    epsilon = 1e-6
    u = torch.clamp(u, epsilon, 1.0 - epsilon).double()

    transformed_list = []
    for i, prior in enumerate(self.priors):
        dist_type = prior[0]
        params = prior[1:]  # Support arbitrary number of parameters per prior
        u_i = u[..., i]
        x_i = self._forward_transform(u_i, dist_type, *params)
        transformed_list.append(x_i)

    return torch.stack(transformed_list, dim=-1)

inverse ¶

inverse(x)

Applies the inverse transformation to a batch of values from the target distributions.

The input tensor x should have shape (..., n_params). Each value is mapped back to [0,1] and then rescaled to the hypercube_range.

Parameters:

Name	Type	Description	Default
`x`	`Tensor`	Tensor of shape (..., n_params) with values in the target distribution domains.	required

Returns:

Type	Description
	torch.Tensor: Tensor of shape (..., n_params) with values in the hypercube_range.

Source code in falcon/contrib/hypercubemappingprior.py

def inverse(self, x):
    """
    Applies the inverse transformation to a batch of values from the target distributions.

    The input tensor x should have shape (..., n_params). Each value is mapped back to [0,1]
    and then rescaled to the hypercube_range.

    Args:
        x (torch.Tensor): Tensor of shape (..., n_params) with values in the target distribution domains.

    Returns:
        torch.Tensor: Tensor of shape (..., n_params) with values in the hypercube_range.
    """
    inv_list = []
    for i, prior in enumerate(self.priors):
        dist_type = prior[0]
        params = prior[1:]
        x_i = x[..., i]
        u_i = self._inverse_transform(x_i, dist_type, *params)
        inv_list.append(u_i)

    u = torch.stack(inv_list, dim=-1)
    u = (
        u * (self.hypercube_range[1] - self.hypercube_range[0])
        + self.hypercube_range[0]
    )
    return u

simulate_batch ¶

simulate_batch(batch_size)

Generates a batch of samples from the target distributions.

Parameters:

Name	Type	Description	Default
`batch_size`	`int`	Number of samples to generate.	required

Returns:

Type	Description
	torch.Tensor: Tensor of shape (n_samples, n_params) with samples in the target distributions.

Source code in falcon/contrib/hypercubemappingprior.py

def simulate_batch(self, batch_size):
    """
    Generates a batch of samples from the target distributions.

    Args:
        batch_size (int): Number of samples to generate.

    Returns:
        torch.Tensor: Tensor of shape (n_samples, n_params) with samples in the target distributions.
    """
    # Generate random samples in the hypercube_range
    u = (
        torch.rand(batch_size, len(self.priors))
        * (self.hypercube_range[1] - self.hypercube_range[0])
        + self.hypercube_range[0]
    )
    u = (
        torch.rand(batch_size, len(self.priors), dtype=torch.float64)
        * (self.hypercube_range[1] - self.hypercube_range[0])
        + self.hypercube_range[0]
    )
    return self.forward(u).numpy()