TriangularMap

The single-fidelity map learns a monotone triangular transport from one target dataset to the prescribed reference distribution.

class mftt.TriangularMap(train_data, params, *, reference=None, standardization=None)

Bases: object

Represent a triangular transport from a target density to a reference.

Parameters:

• train_data (array-like, shape (n_samples, input_dim)) – Raw target samples from the density to be transported.

• params (MapParams) – Basis and optimization configuration.

• reference (Reference, optional) – Reference density eta. The standard normal is used when omitted.

• standardization (StandardizationParams, optional) – Precomputed raw-coordinate standardization. By default it is fitted from train_data.

Notes

Public methods accept raw coordinates. evaluate maps the target to eta and inverse pulls reference samples back to the target.

property coefficients: MapCoefficients

Expose the full map coefficients in structured form.

property coeffs: ndarray

Return all component coefficients as one flat vector.

component_log_det(x, component_indices)

Evaluate selected diagonal log-determinant terms on raw inputs.

Parameters:

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

• component_indices (iterable of int) – Zero-based triangular component indices whose diagonal terms are summed. Indices must lie in [0, input_dim).

Returns:

Sum of requested raw-coordinate diagonal log-Jacobian terms.

Return type:

numpy.ndarray, shape (n_samples,)

component_log_det_standardized(x_std, component_indices)

Evaluate selected diagonal log-determinant terms on standardized inputs.

Parameters:

• x_std (array-like, shape (n_samples, input_dim)) – Standardized target coordinates.

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

Returns:

Sum of requested standardized-coordinate log-Jacobian terms.

Return type:

numpy.ndarray, shape (n_samples,)

conditional_pullback_logpdf(x, fixed_indices)

Evaluate a learned conditional log-density for a fixed prefix.

Parameters:

• x (array-like, shape (n_samples, input_dim)) – Raw target coordinates, including fixed and free entries.

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

Returns:

Conditional log density of the remaining coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

Raises:

ValueError – If indices are not a leading prefix.

conditional_pullback_pdf(x, fixed_indices)

Evaluate a learned conditional density for a fixed prefix.

Parameters:

• x (array-like, shape (n_samples, input_dim)) – Raw target coordinates, including fixed and free entries.

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

Returns:

Conditional density of the 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 by clamp-and-invert.

Parameters:

• n_samples (int) – Number of conditional draws.

• fixed_indices (iterable of int) – Leading coordinate prefix [0, ..., m - 1] to condition on.

• fixed_values (array-like, shape (m,) or (n_samples, m)) – Raw target 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 target samples, optionally with diagnostics.

Return type:

numpy.ndarray or InverseResult

Raises:

ValueError – If fixed_indices are not a leading coordinate prefix.

Notes

Arbitrary-coordinate conditionals require a map with a different variable ordering or a general conditional inference method.

evaluate(x)

Map raw target samples to reference samples.

Parameters:

x (array-like, shape (n_samples, input_dim)) – Target-space samples.

Returns:

Reference-space coordinates.

Return type:

numpy.ndarray, shape (n_samples, input_dim)

evaluate_standardized(x_std)

Evaluate the map on already-standardized target inputs.

Parameters:

x_std (array-like, shape (n_samples, input_dim)) – Target samples standardized with this map’s fitted parameters.

Returns:

Reference-space coordinates.

Return type:

numpy.ndarray, shape (n_samples, input_dim)

classmethod from_multi_index_sets(train_data, multi_index_sets, reference=None, optimization=None, sigma=30.0, rectifier_epsilon=0.0001, quadrature_rule=None)

Construct a map from explicit per-component multi-index sets.

Parameters:

• train_data (array-like, shape (n_samples, input_dim)) – Raw target training samples.

• multi_index_sets (sequence of sequence of tuple of int) – One Hermite multi-index collection for each triangular component.

• reference (Reference, optional) – Reference density; defaults to the standard normal.

• optimization (OptimizationParams, optional) – Component-optimization configuration.

• sigma (float, default=30.0) – Hermite normalization scale.

• rectifier_epsilon (float, default=1e-4) – Positive monotonicity-rectifier floor.

• quadrature_rule (QuadratureRule, optional) – Quadrature rule for monotone component integrals.

Returns:

Untrained map configured with the supplied bases.

Return type:

TriangularMap

gradient_aao_precomp(coeffs, reg_cst=None)

Evaluate the analytic AAO gradient using cached training data.

Parameters:

• coeffs (array-like, shape (n_coefficients,)) – Candidate flattened map coefficients.

• reg_cst (float, optional) – Quadratic regularization constant; defaults to configured value.

Returns:

Gradient of the regularized all-at-once objective.

Return type:

numpy.ndarray, shape (n_coefficients,)

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

Map reference-space samples back to target space.

Parameters:

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

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

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

• fixed_indices (iterable of int, optional) – Leading target-coordinate prefix [0, ..., m - 1] to clamp.

• fixed_values (array-like, shape (m,) or (n_samples, m), optional) – Raw target values for fixed_indices. Required when indices are supplied and broadcast from one row when one-dimensional.

• max_batch_rows (int, optional) – Maximum rows solved in one inverse batch; bounds workspace memory.

• inverse_options (InverseOptions, optional) – Additional bracket, evaluation, and time limits.

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

Returns:

Raw target coordinates, or values together with inversion diagnostics when requested.

Return type:

numpy.ndarray or InverseResult

Raises:

• ValueError – If coordinate shapes are invalid or conditioned indices are not a leading prefix.

• RuntimeError – If a solve fails and diagnostics were not requested.

Notes

When fixed_indices are supplied, the inverse solve clamps those target-space coordinates and samples the remaining coordinates conditionally under the learned triangular map. They must form the leading prefix [0, ..., m - 1].

max_batch_rows bounds inversion workspace memory by solving independent row batches. Chunked and unchunked solves can differ at the requested numerical tolerance because convergence is checked per batch.

log_det(x)

Evaluate the log absolute determinant on raw target inputs.

Parameters:

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

Returns:

log |det dS/dx| including raw-coordinate standardization.

Return type:

numpy.ndarray, shape (n_samples,)

log_det_aao_precomp()

Evaluate the training-data log determinant from caches.

Return type:

ndarray

log_det_standardized(x_std)

Evaluate the log determinant on standardized target inputs.

Parameters:

x_std (array-like, shape (n_samples, input_dim)) – Target coordinates standardized with this map’s fitted parameters.

Returns:

Log determinant in standardized target coordinates.

Return type:

numpy.ndarray, shape (n_samples,)

objective_aao_precomp(coeffs, reg_cst=None)

Evaluate the all-at-once KL objective with cached bases.

Parameters:

• coeffs (array-like, shape (n_coefficients,)) – Candidate flattened map coefficients.

• reg_cst (float, optional) – Quadratic regularization constant; defaults to configured value.

Returns:

Regularized training objective.

Return type:

float

optimization_diagnostics()

Return the most recent optimizer summaries for the trained map.

Return type:

dict[str, object]

precompute_training_data()

Build or reuse per-component caches for the training dataset.

Return type:

list[ComponentCache]

pullback_logpdf(x)

Evaluate the learned target log-density on raw inputs.

Parameters:

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

Returns:

Learned target log density log eta(S(x)) + log |det dS/dx|.

Return type:

numpy.ndarray, shape (n_samples,)

pullback_pdf(x)

Evaluate the learned target density on raw inputs.

Parameters:

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

Returns:

Learned target density.

Return type:

numpy.ndarray, shape (n_samples,)

pullback_score(x)

Evaluate the score of the learned target density on raw inputs.

Parameters:

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

Returns:

Raw-coordinate gradient of the learned target log density.

Return type:

numpy.ndarray, shape (n_samples, input_dim)

pullback_score_standardized(x_std)

Evaluate the learned target score on standardized inputs.

Parameters:

x_std (array-like, shape (n_samples, input_dim)) – Target coordinates standardized with the fitted map state.

Returns:

Standardized-coordinate gradient of the learned log density.

Return type:

numpy.ndarray, shape (n_samples, input_dim)

pushforward_logpdf(z, target)

Evaluate a target’s pushforward log-density on reference inputs.

Parameters:

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

• target (callable) – Function accepting raw target 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 on reference inputs.

Parameters:

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

• target (callable) – Function accepting raw target 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 target-space samples from the learned map.

Parameters:

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

• random_state (int, numpy.random.Generator, or None, optional) – Random source passed to numpy.random.default_rng.

• 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 target samples, optionally with inversion diagnostics.

Return type:

numpy.ndarray or InverseResult

set_coeffs(coeffs)

Assign a flattened coefficient vector to all components.

Parameters:

coeffs (array-like, shape (n_coefficients,)) – Concatenated component coefficients in map order.

train(optimization=None, verbose=False)

Train components sequentially on one dataset.

Parameters:

• optimization (OptimizationParams, optional) – Optimizer settings overriding those stored in params.

• verbose (bool, default=False) – Print one completion message per triangular component.

train_aao(optimization=None, verbose=False)

Train the whole map jointly with analytic AAO gradients.

Parameters:

• optimization (OptimizationParams, optional) – Optimizer settings overriding the configured values.

• verbose (bool, default=False) – Print a completion message after optimization.