Configuration and references

class mftt.MapParams(total_order=None, component_params=None, optimization=None)[source]

Bases: object

Collect configuration for a full single-fidelity triangular map.

Parameters:

  • total_order (int, optional) – Total Hermite order used to generate every component basis. Supply this or component_params.

  • component_params (list of MapComponentParams, optional) – Explicit settings for components 1 through input_dim. Supply this or total_order.

  • optimization (OptimizationParams, optional) – Optimizer settings shared by component training. A default instance is created when omitted.

bind(input_dim)[source]

Bind this configuration to a data dimension and build components.

Parameters:

input_dim (int) – Positive training-data coordinate dimension.

Returns:

This configuration after validation and basis expansion.

Return type:

MapParams

Raises:

ValueError – If the dimension conflicts with existing settings or the basis specification is incomplete.

component_params: list[MapComponentParams] | None = None
optimization: OptimizationParams | None = None
total_order: int | None = None
class mftt.HierarchicalMapParams(fidelity_map_params=<factory>)[source]

Bases: object

Collect one MapParams configuration for each fidelity stage.

Parameters:

fidelity_map_params (list of MapParams) – One configuration per dataset in high-to-low order [X_0, ..., X_M]. Training proceeds from the final entry toward high fidelity.

fidelity_map_params: list[MapParams]
class mftt.NonHierarchicalMapParams(low_fidelity_map_params=<factory>, shift_order=0, scale_order=0, correction_order=0, optimization=<factory>, quadrature_rule=<factory>, sigma=30.0, rectifier_epsilon=0.0001, hf_weight=1.0, regularize_parent_terms=True)[source]

Bases: object

Collect basis orders and optimizer settings for the NHMF construction.

Parameters:

  • low_fidelity_map_params (list of MapParams) – One parent-map configuration for each dataset after high-fidelity X_0.

  • shift_order (int, default=0) – Total orders for the peer shift, monotone scale, and trainable corrections to pretrained low-fidelity parent maps.

  • scale_order (int, default=0) – Total orders for the peer shift, monotone scale, and trainable corrections to pretrained low-fidelity parent maps.

  • correction_order (int, default=0) – Total orders for the peer shift, monotone scale, and trainable corrections to pretrained low-fidelity parent maps.

  • optimization (OptimizationParams, optional) – Optimizer settings for the coupled high-fidelity fit.

  • quadrature_rule (QuadratureRule, optional) – Quadrature used by monotone peer components.

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

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

  • hf_weight (float, default=1.0) – Positive weight on the high-fidelity contribution to the objective.

  • regularize_parent_terms (bool, default=True) – Whether parent-derived terms contribute to coefficient regularization.

correction_order: int = 0
hf_weight: float = 1.0
low_fidelity_map_params: list[MapParams]
optimization: OptimizationParams
quadrature_rule: QuadratureRule
rectifier_epsilon: float = 0.0001
regularize_parent_terms: bool = True
scale_order: int = 0
shift_order: int = 0
sigma: float = 30.0
class mftt.OptimizationParams(optimizer='BFGS', reg_cst=0.0, gtol=1e-06, maxiter=1000)[source]

Bases: object

Collect optimizer settings shared across training routines.

Parameters:

  • optimizer ({"BFGS", "L-BFGS-B"}, default="BFGS") – SciPy optimizer used for component objectives.

  • reg_cst (float, default=0.0) – Nonnegative quadratic coefficient regularization constant.

  • gtol (float, default=1e-6) – Gradient-norm convergence tolerance.

  • maxiter (int, default=1000) – Maximum optimizer iterations.

gtol: float = 1e-06
maxiter: int = 1000
optimizer: Literal['BFGS', 'L-BFGS-B'] = 'BFGS'
reg_cst: float = 0.0
class mftt.Reference(logpdf_fn, score_fn=None)[source]

Bases: object

Wrap reference log-density and score evaluations.

Parameters:

  • logpdf_fn (callable) – Function accepting a batch with shape (n_samples, input_dim) and returning one log-density value per row.

  • score_fn (callable, optional) – Function on the same batch returning the gradient of the log density with shape (n_samples, input_dim). It is required for analytic AAO gradients.

evaluate_logpdf(x)[source]

Evaluate the reference log-density on a batch of reference samples.

Parameters:

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

Returns:

Log-density values.

Return type:

numpy.ndarray, shape (n_samples,)

evaluate_score(x)[source]

Evaluate the reference score on a batch of reference samples.

Parameters:

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

Returns:

Gradients of the reference log density.

Return type:

numpy.ndarray, shape (n_samples, input_dim)

Raises:

ValueError – If this reference was created without a score function.

classmethod from_scipy(executable)[source]

Build a reference wrapper from a frozen SciPy distribution.

Parameters:

executable (scipy.stats frozen distribution) – Distribution exposing logpdf. A distribution exposing mean and cov also receives an analytic score function.

Returns:

Adapter using the distribution’s log density and, when available, its Gaussian score.

Return type:

Reference

Raises:

TypeError – If the unfrozen SciPy multivariate_normal constructor is used.

logpdf_fn: Callable[[ndarray], ndarray]
score_fn: Callable[[ndarray], ndarray] | None = None
classmethod standard_normal(input_dim)[source]

Build a standard normal reference.

Parameters:

input_dim (int) – Dimension of the reference coordinates.

Returns:

Standard normal reference with identity covariance.

Return type:

Reference

class mftt.BasisSpec(input_dim, total_order=None, multi_indices=None, sigma=30.0)[source]

Bases: object

Describe a Hermite basis through an order or explicit multi-indices.

Parameters:

  • input_dim (int) – Number of coordinates visible to this triangular component.

  • total_order (int, optional) – Maximum total Hermite order. Required when multi_indices is not supplied.

  • multi_indices (list of tuple of int, optional) – Explicit basis multi-indices, each of length input_dim.

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

input_dim: int
multi_indices: list[tuple[int, ...]] | None = None
normalization: ndarray
sigma: float = 30.0
total_order: int | None = None
class mftt.MapComponentParams(input_dim, basis_spec, quadrature_rule=<factory>, rectifier_epsilon=0.0001, initialization='identity')[source]

Bases: object

Collect basis and quadrature settings for one triangular component.

Parameters:

  • input_dim (int) – Number of coordinates visible to component k.

  • basis_spec (BasisSpec) – Hermite basis; it must include the final-coordinate linear seed.

  • quadrature_rule (QuadratureRule, optional) – Rule used by the monotone integral.

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

  • initialization (str, default="identity") – Initial coefficient construction. "identity" preserves the final-coordinate linear seed.

basis_spec: BasisSpec
initialization: str = 'identity'
input_dim: int
quadrature_rule: QuadratureRule
rectifier_epsilon: float = 0.0001
class mftt.QuadratureRule(points, weights, num_points)[source]

Bases: object

Store quadrature nodes and weights used in monotone integrals.

Parameters:

  • points (array-like, shape (num_points,)) – Quadrature nodes on the reference interval.

  • weights (array-like, shape (num_points,)) – Corresponding quadrature weights.

  • num_points (int) – Number of nodes and weights.

classmethod legendre(num_points=10)[source]

Construct a Gauss-Legendre quadrature rule.

Parameters:

num_points (int, default=10) – Number of Gauss-Legendre nodes.

Returns:

Rule with nodes and weights on [-1, 1].

Return type:

QuadratureRule

num_points: int
points: ndarray
weights: ndarray
class mftt.StandardizationParams(mean, std)[source]

Bases: object

Store per-coordinate mean and standard deviation values.

Parameters:

  • mean (array-like, shape (input_dim,)) – Coordinate means in raw target coordinates.

  • std (array-like, shape (input_dim,)) – Strictly positive coordinate standard deviations. Standardization is (x - mean) / std; these values are fitted map state.

mean: ndarray
std: ndarray