Hypercube¶

Flexible prior distributions with hypercube mapping.

Overview¶

Hypercube 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.

Use Hypercube as the simulator (prior) for latent nodes when pairing with the Flow estimator.

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.priors import Hypercube

# Define priors for 3 parameters
prior = Hypercube(
    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.priors.Hypercube
  priors:
    - ['uniform', -10.0, 10.0]
    - ['normal', 0.0, 1.0]
  hypercube_range: [-2, 2]

Class Reference¶

Hypercube ¶

Hypercube(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 Hypercube 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/priors/hypercube.py

def __init__(self, priors=[], hypercube_range=[-2, 2]):
    """
    Initializes the Hypercube 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/priors/hypercube.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/priors/hypercube.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/priors/hypercube.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()