HierarchicalTriangularMap

The hierarchical map composes stagewise transports across an ordered fidelity hierarchy using changing-reference or fixed-reference training.

class mftt.HierarchicalTriangularMap(train_data, hierarchical_params)

Bases: object

Compose stagewise triangular maps across a fidelity hierarchy.

Parameters:

• train_data (list of array-like) – Datasets ordered [X_0, ..., X_M] with high fidelity first. Each has shape (n_samples_i, input_dim).

• hierarchical_params (HierarchicalMapParams) – One single-fidelity configuration per dataset.

Notes

train() selects the changing-reference or fixed-reference formulation. The trained composition maps pi_0 to eta.

TRAINING_METHODS = {'changing_reference', 'fixed_reference'}

property coefficients: HierarchicalMapCoefficients

Expose structured coefficients for each trained stage map.

component_log_det(x, component_indices)

Evaluate selected composed diagonal log-determinant terms.

Parameters:

• x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target coordinates.

• component_indices (iterable of int) – Zero-based diagonal component indices to sum.

Returns:

Raw-coordinate sum of selected composed diagonal log-Jacobian terms.

Return type:

numpy.ndarray, shape (n_samples,)

conditional_pullback_logpdf(x, fixed_indices)

Evaluate a conditional high-fidelity log-density for a fixed prefix.

Parameters:

• x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity coordinates.

• fixed_indices (iterable of int) – Leading high-fidelity coordinate prefix conditioned on.

Returns:

Conditional log density of remaining coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

conditional_pullback_pdf(x, fixed_indices)

Evaluate a conditional high-fidelity density for a fixed prefix.

Parameters:

• x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity coordinates.

• fixed_indices (iterable of int) – Leading high-fidelity coordinate prefix conditioned on.

Returns:

Conditional density of remaining coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

conditional_sample(n_samples, fixed_indices, fixed_values, random_state=None, max_iter=100, tol=1e-08, inverse_options=None, return_diagnostics=False)

Draw exact prefix-conditioned samples under the hierarchy.

Parameters:

• n_samples (int) – Number of conditional draws.

• fixed_indices (iterable of int) – Leading high-fidelity coordinate prefix [0, ..., m - 1].

• fixed_values (array-like, shape (m,) or (n_samples, m)) – Raw high-fidelity values for the fixed prefix.

• random_state (int, numpy.random.Generator, or None, optional) – Random source for unfixed reference coordinates.

• max_iter (int, default=100) – Maximum inverse iterations per component and row.

• tol (float, default=1e-8) – Absolute scalar inverse residual tolerance.

• inverse_options (InverseOptions, optional) – Additional inverse resource limits.

• return_diagnostics (bool, default=False) – Return InverseResult instead of only samples.

Returns:

Raw conditional high-fidelity samples, optionally with diagnostics.

Return type:

numpy.ndarray or InverseResult

Raises:

ValueError – If the conditioning indices are not a leading prefix.

evaluate(x)

Map high-fidelity target samples through the hierarchy to eta.

Parameters:

x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target coordinates.

Returns:

Reference-space coordinates.

Return type:

numpy.ndarray, shape (n_samples, input_dim)

property evaluation_order: list[int]

Return the stage order used by the currently trained hierarchy.

inverse(z, max_iter=100, tol=1e-08, fixed_indices=None, fixed_values=None, max_batch_rows=None, inverse_options=None, return_diagnostics=False)

Invert the full hierarchy from reference space to high fidelity.

Parameters:

• z (array-like, shape (n_samples, input_dim)) – Reference-space coordinates.

• max_iter (int, default=100) – Maximum inverse iterations per component and row.

• tol (float, default=1e-8) – Absolute scalar inverse residual tolerance.

• fixed_indices (iterable of int, optional) – Leading high-fidelity coordinate prefix to clamp.

• fixed_values (array-like, shape (m,) or (n_samples, m), optional) – Raw values of fixed high-fidelity coordinates.

• max_batch_rows (int, optional) – Maximum rows solved in one batch.

• inverse_options (InverseOptions, optional) – Additional inverse resource limits.

• return_diagnostics (bool, default=False) – Return InverseResult instead of only values.

Returns:

Raw high-fidelity coordinates, optionally with diagnostics.

Return type:

numpy.ndarray or InverseResult

Raises:

• ValueError – If shapes or leading-prefix conditioning are invalid.

• RuntimeError – If inversion fails and diagnostics were not requested.

log_det(x)

Evaluate the composed log determinant in target coordinates.

Parameters:

x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target coordinates.

Returns:

log |det dS/dx| for the complete hierarchy.

Return type:

numpy.ndarray, shape (n_samples,)

property maps: list[TriangularMap]

Return trained stage maps in fidelity order.

partial_evaluations(x)

Return states after high-fidelity pre-standardization and each stage.

Parameters:

x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target coordinates.

Returns:

Standardized high-fidelity input followed by the state after each stage in evaluation order.

Return type:

list of numpy.ndarray

pullback_logpdf(x)

Evaluate the learned high-fidelity target log-density.

Parameters:

x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target coordinates.

Returns:

Learned high-fidelity target log density.

Return type:

numpy.ndarray, shape (n_samples,)

pullback_pdf(x)

Evaluate the learned high-fidelity target density.

Parameters:

x (array-like, shape (n_samples, input_dim)) – Raw high-fidelity target coordinates.

Returns:

Learned high-fidelity target density.

Return type:

numpy.ndarray, shape (n_samples,)

pushforward_logpdf(z, target)

Evaluate a target’s pushforward log-density through the hierarchy.

Parameters:

• z (array-like, shape (n_samples, input_dim)) – Reference-space coordinates.

• target (callable) – Function accepting raw high-fidelity coordinates and returning one target log-density value per row.

Returns:

Pushforward log density in reference coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

pushforward_pdf(z, target)

Evaluate a target’s pushforward density through the hierarchy.

Parameters:

• z (array-like, shape (n_samples, input_dim)) – Reference-space coordinates.

• target (callable) – Function accepting raw high-fidelity coordinates and returning target log-density values per row.

Returns:

Pushforward density in reference coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

sample(n_samples, random_state=None, max_iter=100, tol=1e-08, inverse_options=None, return_diagnostics=False)

Draw unconditional high-fidelity samples from the hierarchy.

Parameters:

• n_samples (int) – Number of reference draws to invert.

• random_state (int, numpy.random.Generator, or None, optional) – Random source for standard-normal reference draws.

• max_iter (int, default=100) – Maximum inverse iterations per component and row.

• tol (float, default=1e-8) – Absolute scalar inverse residual tolerance.

• inverse_options (InverseOptions, optional) – Additional inverse resource limits.

• return_diagnostics (bool, default=False) – Return InverseResult instead of only samples.

Returns:

Raw high-fidelity samples, optionally with diagnostics.

Return type:

numpy.ndarray or InverseResult

property stages: list[HierarchicalStageState]

Return the configured stage states in fidelity order.

train(method=None, optimization=None, verbose=False)

Train the hierarchy stage-by-stage.

Parameters:

• method ({"changing_reference", "fixed_reference"}, optional) – Hierarchical formulation from manuscript Section 4.1.

• optimization (OptimizationParams, optional) – Optimizer settings applied to each stage.

• verbose (bool, default=False) – Print stage completion messages.

Notes

Training data are provided in high-to-low fidelity order, but training always proceeds from the lowest fidelity stage upward.