NonHierarchicalTriangularMap

The non-hierarchical map combines peer low-fidelity transports with learned high-fidelity shift and scale terms, with optional trainable corrections to the pretrained low-fidelity parent maps.

class mftt.NonHierarchicalTriangularMap(train_data, nhmf_params)

Bases: object

Represent a peer NHMF transport with low-fidelity parent maps.

Parameters:

• train_data (list of array-like) – Datasets ordered [X_0, ..., X_M]. X_0 is high fidelity and has shape (n_0, input_dim); remaining datasets are peer parents.

• nhmf_params (NonHierarchicalMapParams) – Parent-map configurations and coupled shift, scale, and trainable parent-correction settings.

Notes

Parent maps are pretrained and incorporated through the monotonicity- preserving shift and scale terms from Section 4.2. When use_corrections=True, the coupled map also learns correction terms applied to those pretrained low-fidelity parent maps.

property coefficients: NHMFMapCoefficients

Expose structured coefficients for the coupled NHMF map.

component_log_det(x, component_indices)

Evaluate selected diagonal log-determinant terms on raw HF inputs.

Parameters:

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

• component_indices (iterable of int) – Zero-based triangular component indices whose terms are summed.

Returns:

Sum of selected raw-coordinate 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 target 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 target 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 high-fidelity samples.

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 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 to the reference.

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)

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 NHMF transport from reference to high-fidelity space.

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 inverse 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

log_det(x)

Evaluate the high-fidelity log determinant on raw inputs.

Parameters:

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

Returns:

log |det dS/dx| in raw target coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

pullback_logpdf(x)

Evaluate the learned high-fidelity log-density on raw inputs.

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 density on raw inputs.

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 NHMF map.

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 NHMF map.

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 NHMF transport.

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

train(use_corrections=True, optimization=None, verbose=False)

Train the NHMF map with or without corrected parent terms.

Parameters:

• use_corrections (bool, default=True) – Allow trainable correction terms applied to the pretrained low-fidelity parent maps. Set to False to use only the parent-informed shift and scale terms.

• optimization (OptimizationParams, optional) – Override the settings stored in nhmf_params.

• verbose (bool, default=False) – Print parent and component training progress.