Source code for romtools.workflows.inverse.vi.mf_drivers

r"""
Multifidelity variational inference drivers.

This module extends the single-fidelity Gaussian variational inference
workflow with multifidelity Monte Carlo control variates and adaptive
reduced-order models. A correlated low-fidelity model is used to reduce the
variance of ELBO gradient and Hessian estimators while retaining a
high-fidelity target distribution.

.. rubric:: Theory

``run_mf_vi`` extends the single-fidelity VI formulation to a two-level
multifidelity setting. The target objective is still the Gaussian VI ELBO

.. math::

   \max_{\zeta}\;
   \mathbb{E}_{\theta \sim q(\theta;\zeta)}
   \left[
   \log p(y,\theta) - \log q(\theta;\zeta)
   \right],

but gradient and curvature estimates are formed by coupling a high-fidelity
model with a correlated low-fidelity surrogate, typically a ROM.

As in :func:`run_vi`, the routine is derivative-free with respect to the
forward model and uses score-function estimators:

.. math::

   g(\zeta)
   =
   \mathbb{E}_{\theta \sim q(\theta;\zeta)}
   \left[
   \mathcal{L}(\theta;\zeta)\,
   \nabla_{\zeta}\log q(\theta;\zeta)
   \right],

.. math::

   H(\zeta)
   =
   \mathbb{E}_{\theta \sim q(\theta;\zeta)}
   \left[
   \mathcal{L}(\theta;\zeta)
   \left(
   \nabla_{\zeta}\log q\,\nabla_{\zeta}\log q^{\top}
   + \nabla_{\zeta}^2 \log q
   \right)
   \right],

where :math:`\mathcal{L}(\theta;\zeta)` denotes the ELBO integrand.

.. rubric:: Multifidelity Control Variates

At each iteration, the code draws a high-fidelity sample set
:math:`\mathcal{S}^{\mathrm{HF}}` and a larger low-fidelity sample set
:math:`\mathcal{S}^{\mathrm{LF}}`, with the high-fidelity samples reused as a
subset of the low-fidelity pool. Writing

.. math::

   \Xi_g^{\mathrm{HF}}(\theta;\zeta)
   :=
   \mathcal{L}^{\mathrm{HF}}(\theta;\zeta)\,
   \nabla_{\zeta}\log q(\theta;\zeta),

.. math::

   \Xi_g^{\mathrm{LF}}(\theta;\zeta)
   :=
   \mathcal{L}^{\mathrm{LF}}(\theta;\zeta)\,
   \nabla_{\zeta}\log q(\theta;\zeta),

the multifidelity gradient estimator has the control-variate form

.. math::

   \widehat g_{\mathrm{MF}}
   =
   \left\langle \Xi_g^{\mathrm{HF}} \right\rangle_{\mathcal{S}^{\mathrm{HF}}}
   +
   A
   \left(
   \left\langle \Xi_g^{\mathrm{LF}} \right\rangle_{\mathcal{S}^{\mathrm{LF}}}
   -
   \left\langle \Xi_g^{\mathrm{LF}} \right\rangle_{\mathcal{S}^{\mathrm{HF}}}
   \right).

The same construction is used for the Hessian estimator by replacing
:math:`\Xi_g` with the corresponding second-order score-function quantity. In
expectation, these estimators match the single-fidelity high-fidelity
estimators, but their variance can be much lower when the ROM remains well
correlated with the FOM.

This is the role of the ``use_mfmc_control_variate`` and
``mfmc_control_variate_mode`` options. The implementation supports scalar,
componentwise, and matrix-valued control-variate coefficients.
For ``score_function_entropy_strategy="joint"``, fitted gradient coefficients
are set to zero when the measured high-fidelity variance is at roundoff. This
avoids amplifying ROM noise at an exact high-fidelity fixed point. Explicitly
fixed coefficients requested through ``use_mfmc_control_variate=False`` are
preserved.

.. rubric:: Adaptive ROM Use

The low-fidelity model is refreshed on the fly using high-fidelity training
data generated by accepted VI iterations. The routine evaluates the current
ROM on the coupled high-fidelity sample set, estimates its relative QoI
error, and rebuilds the ROM when that error exceeds the requested tolerance.
This keeps the low-fidelity correction informative as the variational
distribution moves.

.. rubric:: Relation to ``run_vi``

If no extra ROM samples are used, or if the low-fidelity correction is turned
off, the method reduces toward the single-fidelity score-function VI
workflow. The optimizer, line search, parameter-bound handling, and optional
Newton curvature model are otherwise shared with :func:`run_vi`.
"""

import copy
import os
import time
import warnings
from typing import Optional, Tuple

from .common import _compute_standard_error, _normalize_mfmc_control_variate_mode

import numpy as np

from romtools.workflows.model_execution import require_supported_concurrency
from romtools.workflows.inverse.vi.gains import loo_acv_estimator, gain_folds, validate_gain_num_folds, normalize_strategy, regularized_matrix_gain, validate_gain_sampling
from romtools.workflows.inverse.vi.gains import (
    history_weights, fit_history_gain, gaussian_history_kernels,
    append_training_batch, importance_weights, sample_ids,
)
from romtools.workflows.inverse.vi.adaptation import (
    stage_delayed_rom, activate_delayed_rom, mf_vi_restart_data,
    validate_mf_vi_restart, restore_mf_vi_state,
)
from romtools.hpc.dispatchers import BaseDispatcher, resolve_dispatcher, resolve_local_dispatcher
from romtools.workflows.inverse.vi.evaluation import run_vi_iteration
from romtools.workflows.inverse._inverse_utils import require_relative_or_absolute_path
from romtools.workflows.inverse.vi.rom_substeps import (
    apply_diagonal_rom_substeps, validate_rom_substeps, rom_substeps_enabled,
    restore_rom_substeps, rom_substep_restart_data,
)
from romtools.workflows.inverse.vi.optimization import (
    AdamSolver,
    SteepestDescentSolver,
    VIAdamOptimizerConfig,
    VIGradientOptimizerConfig,
    VINewtonOptimizerConfig,
    VILegacyLineSearchConfig,
    VIStochasticNonmonotoneLineSearchConfig,
    _normalize_line_search_method as _normalize_line_search_method_shared,
    _normalize_newton_hessian_type,
    _normalize_newton_curvature_strategy,
    _normalize_newton_metric,
    _normalize_newton_regularization_strategy,
    _resolve_line_search_config,
    _resolve_optimizer_config,
)
from romtools.workflows.inverse.vi.drivers import (
    _append_vi_history,
    _compute_component_standard_error,
    _compute_correlation_cholesky_from_samples,
    _compute_gaussian_log_density_data,
    _compute_variational_log_densities,
    _compute_gradient_signal_to_noise_ratio,
    _clip_variational_log_std,
    _enforce_variational_log_std_bounds,
    _compute_gradient_norm,
    _compute_adam_fisher_diagonal,
    _compute_adam_diagnostics,
    _compute_leave_one_out_baseline,
    _compute_log_likelihoods,
    _compute_log_likelihood_precision_operator,
    _compute_optimal_baseline,
    _compute_relative_mse,
    _compute_log_prior_and_joint_terms,
    _convert_physical_moments_to_optimizer_moments,
    _compute_newton_metric_scale,
    _compute_newton_step,
    _backtrack_adaptive_newton_controls,
    _restore_adaptive_newton_regularization,
    _scheduled_newton_regularization,
    _get_state_hessian,
    _average_hessians,
    _limit_mean_update,
    _compute_update_directions,
    _compute_variational_std,
    _draw_parameter_samples,
    _get_persisted_variational_mean,
    _initialize_variational_from_mean_cov,
    _normalize_baseline_method,
    _normalize_bounded_parameter_handling,
    _normalize_transform_map,
    _normalize_sampling_method,
    _normalize_score_function_entropy_strategy,
    _print_gradient_signal_to_noise_ratio,
    _print_vi_parameters,
    _initialize_vi_history,
    _load_vi_history_from_restart,
    _pack_vi_history,
    _resolve_elbo_scaling_factor,
    _initial_expected_misfit_scale,
    _restore_initial_expected_misfit_scale,
    _resolve_parameter_bounds,
    _prune_old_restart_files,
    _resolve_restart_file,
    _restore_variational_mean_from_restart,
    _save_vi_history,
    _validate_gaussian_parameter_spaces,
    _write_iteration_stats_file,
)
from romtools.workflows.model_builders import QoiModelBuilderWithTrainingData
from romtools.workflows.models import QoiModel
from romtools.workflows.parameter_spaces import (
    GaussianParameterSpace,
    MultivariateGaussianParameterSpace,
)


def _compute_rom_relative_error(rom_qois: np.ndarray, fom_qois: np.ndarray, epsilon: float = 1e-16) -> float:
    denominator = np.linalg.norm(fom_qois)
    if denominator <= epsilon:
        return float(np.linalg.norm(rom_qois - fom_qois))
    return float(np.linalg.norm(rom_qois - fom_qois) / denominator)


def _normalize_rom_retraining_strategy(value):
    return normalize_strategy(value, 'rom_retraining_strategy', ('same_sample', 'delayed'))


def _normalize_mfmc_fixed_gain(value):
    if (isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, float, np.integer, np.floating))
            or not np.isfinite(value)):
        raise ValueError('mfmc_fixed_gain must be a finite real scalar.')
    return float(value)


def _constant_mfmc_gain(value, shape, mode):
    value = _normalize_mfmc_fixed_gain(value)
    mode = _normalize_mfmc_control_variate_mode(mode)
    if mode == 'scalar':
        return np.array(value)
    if mode == 'matrix':
        return value*np.eye(int(np.prod(shape)))
    return np.full(shape, value)


def _validate_gain_sample_size(value):
    if value is not None and (isinstance(value, (bool, np.bool_))
            or not isinstance(value, (int, np.integer)) or value < 1):
        raise ValueError('gain_sample_size must be None or a positive integer.')
    return None if value is None else int(value)


def _normalize_hessian_gain_estimation_strategy(value):
    return normalize_strategy(value, 'hessian_gain_estimation_strategy', ('same_sample',))


def _normalize_gradient_gain_estimation_strategy(value):
    return normalize_strategy(value, 'gradient_gain_estimation_strategy', ('same_sample', 'loo', 'k_fold', 'history', 'independent'))


def _build_iteration_training_data(run_directory_base: str,
                                   parameter_samples: np.ndarray,
                                   qoi_results) -> Tuple[list, np.ndarray, np.ndarray]:
    sample_count = parameter_samples.shape[0]
    training_dirs = [f'{run_directory_base}{sample_index}' for sample_index in range(sample_count)]
    training_parameters = parameter_samples.copy()
    training_qois = qoi_results['qois'].T.copy()
    return training_dirs, training_parameters, training_qois


def _append_training_data(training_dirs: list,
                          training_parameters: np.ndarray,
                          training_qois: np.ndarray,
                          iteration_dirs: list,
                          iteration_parameters: np.ndarray,
                          iteration_qois: np.ndarray) -> Tuple[list, np.ndarray, np.ndarray]:
    if training_parameters is None or training_qois is None:
        return copy.deepcopy(iteration_dirs), iteration_parameters.copy(), iteration_qois.copy()
    return (
        list(training_dirs) + list(iteration_dirs),
        np.vstack([training_parameters, iteration_parameters]),
        np.vstack([training_qois, iteration_qois]),
    )


def _compute_mfmc_alpha(high_terms: np.ndarray,
                        low_terms: np.ndarray,
                        epsilon: float = 1e-12,
                        mode: str = "componentwise") -> np.ndarray:
    trailing_shape = high_terms.shape[1:]
    high_flat = high_terms.reshape(high_terms.shape[0], -1)
    low_flat = low_terms.reshape(low_terms.shape[0], -1)
    mode = _normalize_mfmc_control_variate_mode(mode)
    centered_high = high_flat - np.mean(high_flat, axis=0, keepdims=True)
    centered_low = low_flat - np.mean(low_flat, axis=0, keepdims=True)
    if mode == "componentwise":
        covariance = np.mean(centered_high * centered_low, axis=0)
        low_variance = np.mean(centered_low ** 2, axis=0)
        # Fall back to no control variate when low-fidelity variance is near zero.
        alphas = np.zeros_like(covariance)
        nonzero = low_variance > epsilon
        alphas[nonzero] = covariance[nonzero] / low_variance[nonzero]
        return alphas.reshape(trailing_shape)
    if mode == "scalar":
        numerator = np.sum(np.mean(centered_high * centered_low, axis=0))
        denominator = np.sum(np.mean(centered_low ** 2, axis=0))
        if denominator <= epsilon:
            return np.array(0.0)
        return np.array(numerator / denominator)

    covariance_low = (centered_low.T @ centered_low) / low_flat.shape[0]
    covariance_cross = (centered_low.T @ centered_high) / low_flat.shape[0]
    return regularized_matrix_gain(covariance_low, covariance_cross, epsilon, max_rank=low_flat.shape[0]-1)


def _mfmc_gradient_estimator(high_terms: np.ndarray,
                             low_terms_base: np.ndarray,
                             low_terms_extra: np.ndarray,
                             use_control_variate: bool,
                             control_variate_mode: str,
                             high_variance_reference_terms: np.ndarray = None,
                             mfmc_fixed_gain: float = 1.0,
                             ) -> Tuple[np.ndarray, np.ndarray]:
    # Gain-fitting predictions affect alpha only; correction means use the final ROM.
    trailing_shape = high_terms.shape[1:]
    high_flat = high_terms.reshape(high_terms.shape[0], -1)
    control_variate_mode = _normalize_mfmc_control_variate_mode(control_variate_mode)
    if low_terms_extra is None or low_terms_extra.shape[0] == 0:
        if control_variate_mode == "scalar":
            alpha = np.array(0.0)
        elif control_variate_mode == "matrix":
            alpha = np.zeros((high_flat.shape[1], high_flat.shape[1]))
        else:
            alpha = np.zeros(trailing_shape)
        return (
            np.mean(high_flat, axis=0).reshape(trailing_shape),
            alpha,
        )

    low_base_flat = low_terms_base.reshape(low_terms_base.shape[0], -1)
    if use_control_variate:
        alpha = _compute_mfmc_alpha(
            high_terms,
            low_terms_base,
            mode=control_variate_mode,
        )
        if high_variance_reference_terms is not None:
            high_reference_flat = high_variance_reference_terms.reshape(
                high_variance_reference_terms.shape[0], -1
            )
            high_standard_deviation = np.std(high_flat, axis=0)
            reference_rms = np.sqrt(np.mean(high_reference_flat ** 2, axis=0))
            negligible = high_standard_deviation <= (
                64.0 * np.finfo(float).eps
                * np.maximum(reference_rms, np.finfo(float).tiny)
            )
            if control_variate_mode == "matrix":
                alpha[:, negligible] = 0.0
            elif control_variate_mode == "scalar":
                if np.all(negligible):
                    alpha = np.array(0.0)
            else:
                alpha = np.asarray(alpha).copy()
                alpha.reshape(-1)[negligible] = 0.0
    else:
        alpha = _constant_mfmc_gain(mfmc_fixed_gain, trailing_shape, control_variate_mode)

    # Hierarchical low-fidelity correction using independent low-fidelity samples.
    # low_terms_full = [low_terms_base; low_terms_extra] with low_terms_base size
    # matched to the high-fidelity sample count.
    low_extra_flat = low_terms_extra.reshape(low_terms_extra.shape[0], -1)
    low_terms_full = np.vstack([low_base_flat, low_extra_flat])
    low_mean_delta = np.mean(low_terms_full, axis=0) - np.mean(low_base_flat, axis=0)
    if control_variate_mode == "matrix":
        estimate_flat = np.mean(high_flat, axis=0) + low_mean_delta @ alpha
    elif control_variate_mode == "scalar":
        estimate_flat = np.mean(high_flat, axis=0) + alpha.item() * low_mean_delta
    else:
        alpha_flat = alpha.reshape(-1)
        estimate_flat = (
            np.mean(high_flat, axis=0)
            + alpha_flat * low_mean_delta
        )
    return estimate_flat.reshape(trailing_shape), alpha


def _compute_mfmc_reinforce_gradients(optimizer_samples_fom: np.ndarray,
                                      optimizer_samples_rom_base: np.ndarray,
                                      optimizer_samples_rom_extra: np.ndarray,
                                      variational_mean: np.ndarray,
                                      variational_std: np.ndarray,
                                      fom_log_likelihoods: np.ndarray,
                                      rom_log_likelihoods_base: np.ndarray,
                                      rom_log_likelihoods_extra: np.ndarray,
                                      baseline_method: str,
                                      use_mfmc_control_variate: bool,
                                      mfmc_control_variate_mode: str = "componentwise",
                                      variational_correlation_cholesky: np.ndarray = None,
                                      elbo_scaling_factor: float = 1.0,
                                      score_function_entropy_strategy: str = 'analytic',
                                      gradient_gain_estimation_strategy: str = 'same_sample',
                                      force_unit_gain: bool = False,
                                      return_gain_samples: bool = False,
                                      gain_history_data=None,
                                      gain_num_folds: int = 5,
                                      gain_independent_data=None,
                                      mfmc_fixed_gain: float = 1.0):
    gradient_gain_estimation_strategy = _normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy)
    def _compute_mfmc_estimator_standard_error(high_terms: np.ndarray,
                                               low_terms_base: np.ndarray,
                                               low_terms_extra: np.ndarray,
                                               alpha: np.ndarray,
                                               control_variate_mode: str) -> np.ndarray:
        trailing_shape = high_terms.shape[1:]
        high_flat = high_terms.reshape(high_terms.shape[0], -1)
        if low_terms_extra is None or low_terms_extra.shape[0] == 0:
            return _compute_component_standard_error(high_flat).reshape(trailing_shape)

        low_base_flat = low_terms_base.reshape(low_terms_base.shape[0], -1)
        low_extra_flat = low_terms_extra.reshape(low_terms_extra.shape[0], -1)
        ratio = low_extra_flat.shape[0] / (low_base_flat.shape[0] + low_extra_flat.shape[0])
        control_variate_mode = _normalize_mfmc_control_variate_mode(control_variate_mode)
        if control_variate_mode == "matrix":
            beta_matrix = ratio * alpha
            corrected_high_terms = high_flat - low_base_flat @ beta_matrix
            projected_low_extra = low_extra_flat @ beta_matrix
            low_extra_standard_error = _compute_component_standard_error(projected_low_extra)
        elif control_variate_mode == "scalar":
            beta_scalar = ratio * alpha.item()
            corrected_high_terms = high_flat - beta_scalar * low_base_flat
            low_extra_standard_error = abs(beta_scalar) * _compute_component_standard_error(low_extra_flat)
        else:
            alpha_flat = alpha.reshape(-1)
            beta_flat = ratio * alpha_flat
            corrected_high_terms = high_flat - beta_flat[None, :] * low_base_flat
            low_extra_standard_error = np.abs(beta_flat) * _compute_component_standard_error(low_extra_flat)
        corrected_high_standard_error = _compute_component_standard_error(corrected_high_terms)
        return np.sqrt(
            corrected_high_standard_error ** 2
            + low_extra_standard_error ** 2
        ).reshape(trailing_shape)

    # Build score-function terms for either diagonal or fixed-correlation Gaussian families.
    def _compute_scores(optimizer_samples: np.ndarray):
        centered = optimizer_samples - variational_mean[None, :]
        normalized = centered / variational_std[None, :]
        if variational_correlation_cholesky is None:
            score_mean = centered / (variational_std[None, :] ** 2)
            score_log_std = normalized ** 2 - 1.0
        else:
            correlation_solve = np.linalg.solve(
                variational_correlation_cholesky,
                normalized.transpose(),
            )
            correlation_inverse_times_normalized = np.linalg.solve(
                variational_correlation_cholesky.transpose(),
                correlation_solve,
            ).transpose()
            score_mean = correlation_inverse_times_normalized / variational_std[None, :]
            score_log_std = normalized * correlation_inverse_times_normalized - 1.0
        return score_mean, score_log_std

    score_mean_fom, score_log_std_fom = _compute_scores(optimizer_samples_fom)
    score_mean_rom_base, score_log_std_rom_base = _compute_scores(optimizer_samples_rom_base)

    # Additional low-fidelity samples are optional; if absent we fall back to single-level MC.
    if optimizer_samples_rom_extra is not None and optimizer_samples_rom_extra.shape[0] > 0:
        score_mean_rom_extra, score_log_std_rom_extra = _compute_scores(optimizer_samples_rom_extra)
    else:
        score_mean_rom_extra = None
        score_log_std_rom_extra = None

    # Keep objective scaling consistent with ELBO scaling used in other VI paths.
    scaled_fom_log_likelihoods = elbo_scaling_factor * fom_log_likelihoods
    scaled_rom_log_likelihoods_base = elbo_scaling_factor * rom_log_likelihoods_base
    scaled_rom_log_likelihoods_extra = elbo_scaling_factor * rom_log_likelihoods_extra

    entropy_strategy = _normalize_score_function_entropy_strategy(
        score_function_entropy_strategy
    )
    fom_weights = scaled_fom_log_likelihoods
    rom_base_weights = scaled_rom_log_likelihoods_base
    rom_extra_weights = scaled_rom_log_likelihoods_extra
    fom_log_q = None
    if entropy_strategy == 'joint':
        fom_log_q = _compute_variational_log_densities(
            optimizer_samples_fom,
            variational_mean,
            variational_std,
            variational_correlation_cholesky,
        )
        fom_weights = fom_weights - elbo_scaling_factor * fom_log_q
        rom_base_weights = (
            rom_base_weights
            - elbo_scaling_factor * _compute_variational_log_densities(
                optimizer_samples_rom_base,
                variational_mean,
                variational_std,
                variational_correlation_cholesky,
            )
        )
        if optimizer_samples_rom_extra is not None and optimizer_samples_rom_extra.shape[0] > 0:
            rom_extra_weights = (
                rom_extra_weights
                - elbo_scaling_factor * _compute_variational_log_densities(
                    optimizer_samples_rom_extra,
                    variational_mean,
                    variational_std,
                    variational_correlation_cholesky,
                )
            )

    if _normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy) in ('loo', 'k_fold', 'history', 'independent'):
        references = None
        if entropy_strategy == 'joint':
            reference_weights = np.abs(scaled_fom_log_likelihoods) + np.abs(elbo_scaling_factor*fom_log_q)
            references = (reference_weights[:, None]*np.abs(score_mean_fom),
                          reference_weights[:, None]*np.abs(score_log_std_fom))
        separate_fit = (_normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy) in ('history', 'independent') and use_mfmc_control_variate
                       and not force_unit_gain and len(rom_extra_weights) > 0)
        gain_fit_data = gain_independent_data if gradient_gain_estimation_strategy == 'independent' else gain_history_data
        if separate_fit and gradient_gain_estimation_strategy == 'independent' and gain_fit_data is None:
            raise ValueError('Independent gain estimation requires a separate paired gain dataset.')
        if separate_fit:
            history_high, history_low = history_weights(gain_fit_data, elbo_scaling_factor, entropy_strategy)
            history_scores = gaussian_history_kernels(gain_fit_data)[0]
        estimates = []
        gains = []
        samples = []
        for index, (scores, extra_scores) in enumerate((
                (score_mean_fom, score_mean_rom_extra), (score_log_std_fom, score_log_std_rom_extra))):
            fixed_gain = (fit_history_gain(history_high, history_low, history_scores[index],
                                           baseline_method, mfmc_control_variate_mode,
                                           sample_weights=gain_fit_data.get('importance_weights'))
                          if separate_fit else None)
            estimate, gain, gain_samples = loo_acv_estimator(
                fom_weights, rom_base_weights, rom_extra_weights, scores,
                np.zeros((0, variational_mean.size)) if extra_scores is None else extra_scores,
                baseline_method, mfmc_control_variate_mode,
                force_unit_gain=force_unit_gain and use_mfmc_control_variate,
                high_reference_terms=None if references is None else references[index],
                fixed_gain=(fixed_gain if use_mfmc_control_variate else
                            _constant_mfmc_gain(mfmc_fixed_gain, scores.shape[1:], mfmc_control_variate_mode)),
                num_folds=gain_num_folds if gradient_gain_estimation_strategy == 'k_fold' else None,
            )
            estimates.append(estimate)
            gains.append(gain)
            samples.append(gain_samples)
        if entropy_strategy == 'analytic':
            estimates[1] += elbo_scaling_factor
        result = (estimates[0], estimates[1], np.full_like(variational_mean, np.nan),
                  np.full_like(variational_mean, np.nan), gains[0], gains[1], np.nan,
                  np.full(2*variational_mean.size, np.nan))
        return result + (dict(mean=samples[0], log_std=samples[1]),) if return_gain_samples else result

    # Compute shared baselines and centered likelihood weights.
    # Baselines are estimated from FOM statistics and reused for ROM terms.
    baseline_method = _normalize_baseline_method(baseline_method)
    if baseline_method == 'optimal':
        baseline_mean = _compute_optimal_baseline(fom_weights, score_mean_fom)
        baseline_log_std = _compute_optimal_baseline(fom_weights, score_log_std_fom)
        centered_fom_log_likelihoods = fom_weights
        centered_rom_log_likelihoods_base = rom_base_weights
        centered_rom_log_likelihoods_extra = rom_extra_weights
    elif baseline_method == 'loo':
        baseline_mean = np.zeros_like(variational_mean)
        baseline_log_std = np.zeros_like(variational_mean)
        centered_fom_log_likelihoods = (
            fom_weights - _compute_leave_one_out_baseline(fom_weights)
        )
        centered_rom_log_likelihoods_base = (
            rom_base_weights - _compute_leave_one_out_baseline(rom_base_weights)
        )
        centered_rom_log_likelihoods_extra = (
            rom_extra_weights - _compute_leave_one_out_baseline(rom_extra_weights)
        )
    else:
        baseline_mean = np.zeros_like(variational_mean)
        baseline_log_std = np.zeros_like(variational_mean)
        centered_fom_log_likelihoods = fom_weights
        centered_rom_log_likelihoods_base = rom_base_weights
        centered_rom_log_likelihoods_extra = rom_extra_weights

    # High and low base terms share the main optimizer samples.
    high_mean_terms = (centered_fom_log_likelihoods[:, None] - baseline_mean[None, :]) * score_mean_fom
    low_mean_terms_base = (
        centered_rom_log_likelihoods_base[:, None] - baseline_mean[None, :]
    ) * score_mean_rom_base
    high_log_std_terms = (
        centered_fom_log_likelihoods[:, None] - baseline_log_std[None, :]
    ) * score_log_std_fom
    low_log_std_terms_base = (
        centered_rom_log_likelihoods_base[:, None] - baseline_log_std[None, :]
    ) * score_log_std_rom_base

    if score_mean_rom_extra is None:
        low_mean_terms_extra = None
        low_log_std_terms_extra = None
    else:
        low_mean_terms_extra = (
            centered_rom_log_likelihoods_extra[:, None] - baseline_mean[None, :]
        ) * score_mean_rom_extra
        low_log_std_terms_extra = (
            (centered_rom_log_likelihoods_extra[:, None] - baseline_log_std[None, :]) * score_log_std_rom_extra
        )

    # Estimate E[FOM term] with a hierarchical low-fidelity correction:
    # mean(FOM) + alpha * (mean(ROM_full) - mean(ROM_base)).
    gradient_mean, alpha_mean = _mfmc_gradient_estimator(
        high_mean_terms,
        low_mean_terms_base,
        low_mean_terms_extra,
        use_mfmc_control_variate and not force_unit_gain,
        mfmc_control_variate_mode,
        (
            (np.abs(scaled_fom_log_likelihoods)[:, None]
             + np.abs(elbo_scaling_factor * fom_log_q)[:, None])
            * np.abs(score_mean_fom)
            if entropy_strategy == 'joint' else None
        ),
        mfmc_fixed_gain=1.0 if force_unit_gain and use_mfmc_control_variate else mfmc_fixed_gain,
    )
    gradient_log_std, alpha_log_std = _mfmc_gradient_estimator(
        high_log_std_terms,
        low_log_std_terms_base,
        low_log_std_terms_extra,
        use_mfmc_control_variate and not force_unit_gain,
        mfmc_control_variate_mode,
        (
            (np.abs(scaled_fom_log_likelihoods)[:, None]
             + np.abs(elbo_scaling_factor * fom_log_q)[:, None])
            * np.abs(score_log_std_fom)
            if entropy_strategy == 'joint' else None
        ),
        mfmc_fixed_gain=1.0 if force_unit_gain and use_mfmc_control_variate else mfmc_fixed_gain,
    )
    gradient_standard_error_mean = _compute_mfmc_estimator_standard_error(
        high_mean_terms,
        low_mean_terms_base,
        low_mean_terms_extra,
        alpha_mean,
        mfmc_control_variate_mode,
    )
    gradient_standard_error_log_std = _compute_mfmc_estimator_standard_error(
        high_log_std_terms,
        low_log_std_terms_base,
        low_log_std_terms_extra,
        alpha_log_std,
        mfmc_control_variate_mode,
    )
    # Entropy gradient contribution for log-std parameters.
    if entropy_strategy == 'analytic':
        gradient_log_std += elbo_scaling_factor
    gradient_signal_to_noise_ratio = _compute_gradient_signal_to_noise_ratio(
        np.concatenate([gradient_mean, gradient_log_std]),
        np.concatenate([
            gradient_standard_error_mean.reshape(-1),
            gradient_standard_error_log_std.reshape(-1),
        ]),
    )
    result = (
        gradient_mean,
        gradient_log_std,
        baseline_mean,
        baseline_log_std,
        alpha_mean,
        alpha_log_std,
        gradient_signal_to_noise_ratio,
        np.concatenate([
            gradient_standard_error_mean.reshape(-1),
            gradient_standard_error_log_std.reshape(-1),
        ]),
    )
    gain_samples = dict(
        mean=np.broadcast_to(alpha_mean, (optimizer_samples_fom.shape[0],) + np.shape(alpha_mean)),
        log_std=np.broadcast_to(alpha_log_std, (optimizer_samples_fom.shape[0],) + np.shape(alpha_log_std)),
    )
    return result + (gain_samples,) if return_gain_samples else result


def _compute_mfmc_reinforce_hessian_diagonal(optimizer_samples_fom: np.ndarray,
                                             optimizer_samples_rom_base: np.ndarray,
                                             optimizer_samples_rom_extra: np.ndarray,
                                             variational_mean: np.ndarray,
                                             variational_std: np.ndarray,
                                             fom_log_likelihoods: np.ndarray,
                                             rom_log_likelihoods_base: np.ndarray,
                                             rom_log_likelihoods_extra: np.ndarray,
                                             baseline_method: str,
                                             use_mfmc_control_variate: bool,
                                             mfmc_control_variate_mode: str = "componentwise",
                                             variational_correlation_cholesky: np.ndarray = None,
                                             elbo_scaling_factor: float = 1.0,
                                             hessian_gain_estimation_strategy: str = 'same_sample',
                                             force_unit_gain: bool = False,
                                             return_gain_samples: bool = False,
                                             mfmc_fixed_gain: float = 1.0):
    hessian_full = _compute_mfmc_reinforce_hessian_full(
        optimizer_samples_fom,
        optimizer_samples_rom_base,
        optimizer_samples_rom_extra,
        variational_mean,
        variational_std,
        fom_log_likelihoods,
        rom_log_likelihoods_base,
        rom_log_likelihoods_extra,
        baseline_method,
        use_mfmc_control_variate,
        mfmc_control_variate_mode,
        variational_correlation_cholesky,
        elbo_scaling_factor,
        hessian_gain_estimation_strategy,
        force_unit_gain,
        mfmc_fixed_gain=mfmc_fixed_gain,
    )
    dimensionality = variational_mean.size
    hessian_diagonal_mean = np.diag(hessian_full[:dimensionality, :dimensionality])
    hessian_diagonal_log_std = np.diag(hessian_full[dimensionality:, dimensionality:])
    return hessian_diagonal_mean, hessian_diagonal_log_std


def _compute_mfmc_reinforce_hessian_full(optimizer_samples_fom: np.ndarray,
                                         optimizer_samples_rom_base: np.ndarray,
                                         optimizer_samples_rom_extra: np.ndarray,
                                         variational_mean: np.ndarray,
                                         variational_std: np.ndarray,
                                         fom_log_likelihoods: np.ndarray,
                                         rom_log_likelihoods_base: np.ndarray,
                                         rom_log_likelihoods_extra: np.ndarray,
                                         baseline_method: str,
                                         use_mfmc_control_variate: bool,
                                         mfmc_control_variate_mode: str = "componentwise",
                                         variational_correlation_cholesky: np.ndarray = None,
                                         elbo_scaling_factor: float = 1.0,
                                         hessian_gain_estimation_strategy: str = 'same_sample',
                                         force_unit_gain: bool = False,
                                         return_gain_samples: bool = False,
                                         mfmc_fixed_gain: float = 1.0):
    _normalize_hessian_gain_estimation_strategy(hessian_gain_estimation_strategy)
    dimensionality = variational_mean.size
    correlation_inverse = None
    second_mean_template = None
    if variational_correlation_cholesky is not None:
        identity = np.eye(dimensionality)
        correlation_solve = np.linalg.solve(variational_correlation_cholesky, identity)
        correlation_inverse = np.linalg.solve(
            variational_correlation_cholesky.transpose(),
            correlation_solve,
        )
        inverse_std_outer = 1.0 / (variational_std[:, None] * variational_std[None, :])
        second_mean_template = -correlation_inverse * inverse_std_outer

    def _compute_hessian_scores(optimizer_samples: np.ndarray):
        centered = optimizer_samples - variational_mean[None, :]
        normalized = centered / variational_std[None, :]
        if variational_correlation_cholesky is None:
            score_mean = centered / (variational_std[None, :] ** 2)
            score_log_std = normalized ** 2 - 1.0
        else:
            correlation_solve_samples = np.linalg.solve(
                variational_correlation_cholesky,
                normalized.transpose(),
            )
            correlation_inverse_times_normalized = np.linalg.solve(
                variational_correlation_cholesky.transpose(),
                correlation_solve_samples,
            ).transpose()
            score_mean = correlation_inverse_times_normalized / variational_std[None, :]
            score_log_std = normalized * correlation_inverse_times_normalized - 1.0

        score_mean_outer = score_mean[:, :, None] * score_mean[:, None, :]
        score_log_std_outer = score_log_std[:, :, None] * score_log_std[:, None, :]
        score_cross_outer = score_mean[:, :, None] * score_log_std[:, None, :]
        if variational_correlation_cholesky is None:
            second_mean = np.zeros_like(score_mean_outer)
            second_log_std = np.zeros_like(score_log_std_outer)
            second_cross = np.zeros_like(score_cross_outer)
            index = np.arange(dimensionality)
            second_mean[:, index, index] = -1.0 / (variational_std ** 2)
            second_log_std[:, index, index] = -2.0 * (normalized ** 2)
            second_cross[:, index, index] = -2.0 * score_mean
        else:
            sample_count = optimizer_samples.shape[0]
            second_mean = np.broadcast_to(
                second_mean_template,
                (sample_count, dimensionality, dimensionality),
            ).copy()

            outer_normalized = normalized[:, :, None] * normalized[:, None, :]
            second_log_std = -(outer_normalized * correlation_inverse[None, :, :])
            index = np.arange(dimensionality)
            second_log_std[:, index, index] -= (
                normalized * correlation_inverse_times_normalized
            )

            second_cross = -(
                (normalized[:, None, :] * correlation_inverse[None, :, :])
                / variational_std[None, :, None]
            )
            second_cross[:, index, index] -= score_mean

        mean_scores = score_mean_outer + second_mean
        log_std_scores = score_log_std_outer + second_log_std
        cross_scores = score_cross_outer + second_cross
        return mean_scores, log_std_scores, cross_scores

    scaled_fom_log_likelihoods = elbo_scaling_factor * fom_log_likelihoods
    scaled_rom_log_likelihoods_base = elbo_scaling_factor * rom_log_likelihoods_base
    scaled_rom_log_likelihoods_extra = elbo_scaling_factor * rom_log_likelihoods_extra

    high_mean_scores, high_log_std_scores, high_cross_scores = _compute_hessian_scores(
        optimizer_samples_fom,
    )
    low_mean_scores_base, low_log_std_scores_base, low_cross_scores_base = _compute_hessian_scores(
        optimizer_samples_rom_base,
    )
    baseline_method = _normalize_baseline_method(baseline_method)
    if baseline_method == 'optimal':
        dimensionality = variational_mean.size
        baseline_hessian_mean = _compute_optimal_baseline(
            scaled_fom_log_likelihoods,
            high_mean_scores.reshape(high_mean_scores.shape[0], -1),
        ).reshape(dimensionality, dimensionality)
        baseline_hessian_log_std = _compute_optimal_baseline(
            scaled_fom_log_likelihoods,
            high_log_std_scores.reshape(high_log_std_scores.shape[0], -1),
        ).reshape(dimensionality, dimensionality)
        baseline_hessian_cross = _compute_optimal_baseline(
            scaled_fom_log_likelihoods,
            high_cross_scores.reshape(high_cross_scores.shape[0], -1),
        ).reshape(dimensionality, dimensionality)
        centered_fom_weights_mean = (
            scaled_fom_log_likelihoods[:, None, None] - baseline_hessian_mean[None, :, :]
        )
        centered_fom_weights_log_std = (
            scaled_fom_log_likelihoods[:, None, None] - baseline_hessian_log_std[None, :, :]
        )
        centered_fom_weights_cross = (
            scaled_fom_log_likelihoods[:, None, None] - baseline_hessian_cross[None, :, :]
        )
        centered_rom_base_weights_mean = (
            scaled_rom_log_likelihoods_base[:, None, None] - baseline_hessian_mean[None, :, :]
        )
        centered_rom_base_weights_log_std = (
            scaled_rom_log_likelihoods_base[:, None, None] - baseline_hessian_log_std[None, :, :]
        )
        centered_rom_base_weights_cross = (
            scaled_rom_log_likelihoods_base[:, None, None] - baseline_hessian_cross[None, :, :]
        )
        centered_rom_extra_weights_mean = (
            scaled_rom_log_likelihoods_extra[:, None, None] - baseline_hessian_mean[None, :, :]
        )
        centered_rom_extra_weights_log_std = (
            scaled_rom_log_likelihoods_extra[:, None, None] - baseline_hessian_log_std[None, :, :]
        )
        centered_rom_extra_weights_cross = (
            scaled_rom_log_likelihoods_extra[:, None, None] - baseline_hessian_cross[None, :, :]
        )
    elif baseline_method == 'loo':
        centered_fom_weights = (
            scaled_fom_log_likelihoods - _compute_leave_one_out_baseline(scaled_fom_log_likelihoods)
        )
        centered_rom_base_weights = (
            scaled_rom_log_likelihoods_base
            - _compute_leave_one_out_baseline(scaled_rom_log_likelihoods_base)
        )
        centered_rom_extra_weights = (
            scaled_rom_log_likelihoods_extra
            - _compute_leave_one_out_baseline(scaled_rom_log_likelihoods_extra)
        )
        centered_fom_weights_mean = centered_fom_weights[:, None, None]
        centered_fom_weights_log_std = centered_fom_weights[:, None, None]
        centered_fom_weights_cross = centered_fom_weights[:, None, None]
        centered_rom_base_weights_mean = centered_rom_base_weights[:, None, None]
        centered_rom_base_weights_log_std = centered_rom_base_weights[:, None, None]
        centered_rom_base_weights_cross = centered_rom_base_weights[:, None, None]
        centered_rom_extra_weights_mean = centered_rom_extra_weights[:, None, None]
        centered_rom_extra_weights_log_std = centered_rom_extra_weights[:, None, None]
        centered_rom_extra_weights_cross = centered_rom_extra_weights[:, None, None]
    else:
        centered_fom_weights_mean = scaled_fom_log_likelihoods[:, None, None]
        centered_fom_weights_log_std = scaled_fom_log_likelihoods[:, None, None]
        centered_fom_weights_cross = scaled_fom_log_likelihoods[:, None, None]
        centered_rom_base_weights_mean = scaled_rom_log_likelihoods_base[:, None, None]
        centered_rom_base_weights_log_std = scaled_rom_log_likelihoods_base[:, None, None]
        centered_rom_base_weights_cross = scaled_rom_log_likelihoods_base[:, None, None]
        centered_rom_extra_weights_mean = scaled_rom_log_likelihoods_extra[:, None, None]
        centered_rom_extra_weights_log_std = scaled_rom_log_likelihoods_extra[:, None, None]
        centered_rom_extra_weights_cross = scaled_rom_log_likelihoods_extra[:, None, None]

    high_mean_terms = centered_fom_weights_mean * high_mean_scores
    low_mean_terms_base = centered_rom_base_weights_mean * low_mean_scores_base
    high_log_std_terms = centered_fom_weights_log_std * high_log_std_scores
    low_log_std_terms_base = centered_rom_base_weights_log_std * low_log_std_scores_base
    high_cross_terms = centered_fom_weights_cross * high_cross_scores
    low_cross_terms_base = centered_rom_base_weights_cross * low_cross_scores_base
    if optimizer_samples_rom_extra is not None and optimizer_samples_rom_extra.shape[0] > 0:
        low_mean_scores_extra, low_log_std_scores_extra, low_cross_scores_extra = _compute_hessian_scores(
            optimizer_samples_rom_extra,
        )
        low_mean_terms_extra = centered_rom_extra_weights_mean * low_mean_scores_extra
        low_log_std_terms_extra = centered_rom_extra_weights_log_std * low_log_std_scores_extra
        low_cross_terms_extra = centered_rom_extra_weights_cross * low_cross_scores_extra
    else:
        low_mean_terms_extra = None
        low_log_std_terms_extra = None
        low_cross_terms_extra = None

    hessian_diagonal_mean, alpha_mean = _mfmc_gradient_estimator(
        high_mean_terms,
        low_mean_terms_base,
        low_mean_terms_extra,
        use_mfmc_control_variate and not force_unit_gain,
        mfmc_control_variate_mode,
        mfmc_fixed_gain=1.0 if force_unit_gain and use_mfmc_control_variate else mfmc_fixed_gain,
    )
    hessian_diagonal_log_std, alpha_log_std = _mfmc_gradient_estimator(
        high_log_std_terms,
        low_log_std_terms_base,
        low_log_std_terms_extra,
        use_mfmc_control_variate and not force_unit_gain,
        mfmc_control_variate_mode,
        mfmc_fixed_gain=1.0 if force_unit_gain and use_mfmc_control_variate else mfmc_fixed_gain,
    )
    hessian_cross, alpha_cross = _mfmc_gradient_estimator(
        high_cross_terms,
        low_cross_terms_base,
        low_cross_terms_extra,
        use_mfmc_control_variate and not force_unit_gain,
        mfmc_control_variate_mode,
        mfmc_fixed_gain=1.0 if force_unit_gain and use_mfmc_control_variate else mfmc_fixed_gain,
    )

    hessian_full = np.block([
        [hessian_diagonal_mean, hessian_cross],
        [hessian_cross.transpose(), hessian_diagonal_log_std],
    ])
    hessian_full = 0.5 * (hessian_full + hessian_full.transpose())
    hessian_full = np.nan_to_num(hessian_full, nan=0.0, posinf=0.0, neginf=0.0)
    gain_samples = {name: np.broadcast_to(gain, (optimizer_samples_fom.shape[0],) + np.shape(gain))
                    for name, gain in (('mean', alpha_mean), ('log_std', alpha_log_std), ('cross', alpha_cross))}
    return (hessian_full, gain_samples) if return_gain_samples else hessian_full


def _normalize_line_search_method(line_search_method: str) -> str:
    return _normalize_line_search_method_shared(line_search_method)


def _compute_mfmc_standard_error(fom_terms: np.ndarray,
                                 rom_terms_base: np.ndarray,
                                 rom_terms_extra: np.ndarray) -> float:
    high = np.asarray(fom_terms, dtype=float)
    low = np.asarray(rom_terms_base, dtype=float)
    extra = np.asarray(rom_terms_extra, dtype=float)
    if extra.size == 0:
        return _compute_standard_error(high)
    if high.ndim != 1 or low.shape != high.shape or extra.ndim != 1 or high.size == 0:
        raise ValueError('MF uncertainty requires matching nonempty paired HF/LF vectors.')
    n, m = high.size, extra.size
    ratio = m / (n + m)
    # Var(mean(H) + r*(mean(L_extra)-mean(L_paired))). Center
    # before forming paired residuals to preserve small variations at large offsets.
    residual = (high-high[0])-ratio*(low-low[0])
    paired_se = _compute_standard_error(residual)
    extra_se = _compute_standard_error(extra-extra[0])
    return float(np.hypot(paired_se, ratio*extra_se))


def _compute_state_elbo_standard_error(state, elbo_scaling_factor: float) -> float:
    mfmc_joint_standard_error = _compute_mfmc_standard_error(
        state['log_joint_terms_fom'],
        state['log_joint_terms_rom_base'],
        state['log_joint_terms_rom_only'],
    )
    return abs(elbo_scaling_factor) * mfmc_joint_standard_error


def _select_mf_elbo_reference(elbo_history, standard_error_history, window):
    """Select the first maximum and its own uncertainty in the recent window."""
    start = max(0, len(elbo_history)-window)
    index = start+int(np.argmax(elbo_history[start:]))
    return float(elbo_history[index]), float(standard_error_history[index])


def _restore_mf_elbo_uncertainty_history(restart_data, elbo_history, state, scale,
                                         require_history=False):
    """Restore aligned histories; unused legacy/Adam history can restart locally."""
    errors = restart_data.get('accepted_elbo_standard_error_history')
    if errors is None:
        if require_history:
            raise ValueError('restart_file is missing accepted ELBO uncertainty history.')
        return [float(state['elbo'])], [_compute_state_elbo_standard_error(state, scale)]
    values = np.asarray(elbo_history, dtype=float)
    errors = np.asarray(errors, dtype=float)
    if (values.ndim != 1 or values.size == 0 or errors.shape != values.shape
            or not np.all(np.isfinite(values)) or not np.all(np.isfinite(errors))
            or np.any(errors < 0)):
        raise ValueError('restart_file has inconsistent accepted ELBO uncertainty history.')
    return values.tolist(), errors.tolist()


def _save_mf_vi_restart(restart_path: str,
                        state,
                        variational_mean: np.ndarray,
                        variational_log_std: np.ndarray,
                        variational_distribution: str,
                        prior_mean: np.ndarray,
                        prior_covariance: np.ndarray,
                        variational_correlation_cholesky: np.ndarray,
                        elbo_scaling_factor: float,
                        elbo_relative_tolerance: float,
                        initial_elbo_reference: float,
                        iteration: int,
                        step_size: float,
                        bounded_parameter_handling: str,
                        transform_map: str,
                        optimization_method: str,
                        mfmc_control_variate_mode: str,
                        score_function_entropy_strategy: str,
                        parameter_mins: np.ndarray = None,
                        parameter_maxes: np.ndarray = None,
                        transform_interior_margin: float = 0.0,
                        vi_history=None,
                        sampling_method: str = None,
                        max_mean_update_std: float = None,
                        newton_curvature_strategy: str = 'same_sample',
                        newton_hessian_num_samples: int = None,
                        newton_hessian_averaging_factor: float = 0.9,
                        current_newton_additive_regularization: float = None,
                        newton_adaptive_regularization: bool = False,
                        newton_regularization_increase_factor: float = 5.0,
                        newton_regularization_decrease_factor: float = 1.25,
                        newton_regularization_max_multiplier: float = 1e4,
                        running_hessian: np.ndarray = None,
                        accepted_elbo_history=None,
                        adam_restart_data=None,
                        adam_gradient_method: str = None,
                        rom_substep_start_iteration: int = 0,
                        rom_substep_end_iteration: Optional[int] = None,
                        num_rom_substeps: int = 0,
                        dispatcher: Optional[BaseDispatcher] = None,
                        accepted_elbo_standard_error_history=None,
                        newton_additive_regularization_growth_factor: float = 1.0,
                        initial_newton_additive_regularization: float = 0.0,
                        newton_additive_regularization_max: float = None,
                        line_search_method=None):
    persisted_variational_mean = _get_persisted_variational_mean(
        variational_mean,
        bounded_parameter_handling,
        parameter_mins,
        parameter_maxes,
        transform_interior_margin,
        transform_map,
    )
    save_data = dict(
        line_search_method=line_search_method,
        log_likelihoods=state['log_likelihoods_fom'],
        log_priors=state['log_priors_fom'],
        mean_relative_mse=float(state['mean_relative_mse']),
        variational_mean=persisted_variational_mean,
        variational_mean_coordinates='physical',
        variational_log_std=variational_log_std,
        variational_distribution=variational_distribution,
        prior_mean=prior_mean,
        prior_covariance=prior_covariance,
        elbo_scaling_factor=elbo_scaling_factor,
        elbo_relative_tolerance=(
            np.nan if elbo_relative_tolerance is None else float(elbo_relative_tolerance)
        ),
        initial_elbo_reference=float(initial_elbo_reference),
        iteration=iteration,
        step_size=step_size,
        bounded_parameter_handling=bounded_parameter_handling,
        transform_map=transform_map,
        optimization_method=optimization_method,
        mfmc_control_variate_mode=mfmc_control_variate_mode,
        score_function_entropy_strategy=score_function_entropy_strategy,
        sampling_method=sampling_method,
        max_mean_update_std=(
            np.nan if max_mean_update_std is None else float(max_mean_update_std)
        ),
        newton_curvature_strategy=newton_curvature_strategy,
        newton_hessian_num_samples=(
            -1 if newton_hessian_num_samples is None else int(newton_hessian_num_samples)
        ),
        newton_hessian_averaging_factor=float(newton_hessian_averaging_factor),
        current_newton_additive_regularization=(
            np.nan
            if current_newton_additive_regularization is None
            else float(current_newton_additive_regularization)
        ),
        newton_additive_regularization_max=(
            np.inf if newton_additive_regularization_max is None
            else float(newton_additive_regularization_max)
        ),
        newton_additive_regularization_growth_factor=float(
            newton_additive_regularization_growth_factor
        ),
        initial_newton_additive_regularization=float(
            initial_newton_additive_regularization
        ),
        newton_adaptive_regularization=bool(newton_adaptive_regularization),
        newton_regularization_decrease_factor=float(
            newton_regularization_decrease_factor
        ),
        newton_regularization_increase_factor=float(
            newton_regularization_increase_factor
        ),
        newton_regularization_max_multiplier=float(
            newton_regularization_max_multiplier
        ),
        training_directories=np.array(state['training_dirs']),
        rom_training_directories=np.array(state['rom_training_dirs']),
        training_parameters=state['training_parameters'],
        training_qois=state['training_qois'],
        rom_training_parameters=state['rom_training_parameters'],
        rom_training_qois=state['rom_training_qois'],
        gradient_signal_to_noise_ratio=float(state.get('gradient_signal_to_noise_ratio', np.nan)),
        rng_state=np.array(np.random.get_state(), dtype=object),
    )
    save_data.update(rom_substep_restart_data(
        rom_substep_start_iteration, rom_substep_end_iteration, num_rom_substeps,
    ))
    if running_hessian is not None:
        save_data['running_hessian'] = running_hessian
    if accepted_elbo_history is not None:
        save_data['accepted_elbo_history'] = np.asarray(accepted_elbo_history)
    if accepted_elbo_standard_error_history is not None:
        save_data['accepted_elbo_standard_error_history'] = np.asarray(accepted_elbo_standard_error_history)
    restart_state_mapping = {
        'optimizer_samples': 'optimizer_samples',
        'parameter_samples': 'parameter_samples',
        'parameter_samples_fom': 'parameter_samples_fom',
        'parameter_samples_rom_base': 'parameter_samples_rom_base',
        'parameter_samples_rom_only': 'parameter_samples_rom_only',
        'qois': 'qois_fom',
        'mean_qoi': 'mean_qoi_fom',
        'errors': 'errors_fom',
        'qois_rom_base': 'qois_rom_base',
        'qois_rom_only': 'qois_rom_only',
        'log_likelihoods': 'log_likelihoods_fom',
        'log_priors': 'log_priors_fom',
        'log_joint_terms': 'log_joint_terms_fom',
        'log_likelihoods_rom_base': 'log_likelihoods_rom_base',
        'log_joint_terms_rom_base': 'log_joint_terms_rom_base',
        'log_likelihoods_rom_only': 'log_likelihoods_rom_only',
        'log_joint_terms_rom_only': 'log_joint_terms_rom_only',
        'gradient_mean': 'gradient_mean',
        'gradient_log_std': 'gradient_log_std',
        'gradient_standard_error': 'gradient_standard_error',
        'hessian_diagonal_mean': 'hessian_diagonal_mean',
        'hessian_diagonal_log_std': 'hessian_diagonal_log_std',
        'hessian_full': 'hessian_full',
        'update_direction_mean': 'update_direction_mean',
        'update_direction_log_std': 'update_direction_log_std',
        'baseline_mean': 'baseline_mean',
        'baseline_log_std': 'baseline_log_std',
        'entropy': 'entropy',
        'elbo': 'elbo',
        'mean_misfit': 'mean_misfit',
        'mfmc_alpha_mean': 'mfmc_alpha_mean',
        'mfmc_alpha_log_std': 'mfmc_alpha_log_std',
        'rom_error': 'rom_error',
        'rom_rebuilt_this_iteration': 'rom_rebuilt_this_iteration',
    }
    for restart_key, state_key in restart_state_mapping.items():
        if state_key in state and state[state_key] is not None:
            save_data[restart_key] = state[state_key]
    if vi_history is not None:
        save_data.update(_pack_vi_history(vi_history))
    if variational_correlation_cholesky is not None:
        save_data['variational_correlation_cholesky'] = variational_correlation_cholesky
    if adam_restart_data is not None:
        save_data.update(adam_restart_data)
        save_data['adam_gradient_method'] = adam_gradient_method
    save_data.update(mf_vi_restart_data(state))
    resolve_dispatcher(dispatcher).np_savez(restart_path, **save_data)


def _evaluate_mf_vi_state(model: QoiModel,
                          rom_model,
                          rom_model_builder: QoiModelBuilderWithTrainingData,
                          observations: np.ndarray,
                          observations_covariance: np.ndarray,
                          iteration_directory: str,
                          parameter_names,
                          variational_mean: np.ndarray,
                          variational_log_std: np.ndarray,
                          prior_mean: np.ndarray,
                          prior_precision_operator: np.ndarray,
                          prior_covariance_log_det: float,
                          fom_sample_size: int,
                          rom_extra_sample_size: int,
                          fom_evaluation_concurrency: int,
                          rom_evaluation_concurrency: int,
                          covariance_regularization: float,
                          baseline_method: str,
                          use_mfmc_control_variate: bool,
                          mfmc_control_variate_mode: str,
                          variational_correlation_cholesky: np.ndarray,
                          elbo_scaling_factor: float,
                          gradient_method: str,
                          bounded_parameter_handling: str,
                          min_variational_std: float,
                          max_variational_std: float,
                          parameter_mins: np.ndarray,
                          parameter_maxes: np.ndarray,
                          transform_interior_margin: float,
                          transform_map: str,
                          rom_tolerance: float,
                          max_rom_training_dirs: int,
                          rom_retraining_strategy: str,
                          gradient_gain_estimation_strategy: str,
                          training_dirs: list,
                          training_parameters: np.ndarray,
                          training_qois: np.ndarray,
                          rom_training_dirs: list,
                          rom_training_parameters: np.ndarray,
                          rom_training_qois: np.ndarray,
                          log_likelihood_precision_operator: np.ndarray = None,
                          sampling_method: str = 'mc',
                          dispatcher: Optional[BaseDispatcher] = None,
                          score_function_entropy_strategy: str = 'analytic',
                          allow_rom_retraining: bool = True,
                          gain_history_state=None,
                          gain_num_folds: int = 5,
                          hessian_gain_estimation_strategy: str = "same_sample",
                          gain_sample_size=None,
                          mfmc_fixed_gain: float = 1.0):
    dispatcher = resolve_dispatcher(dispatcher)
    rom_dispatcher = resolve_local_dispatcher(dispatcher)
    rom_retraining_strategy = _normalize_rom_retraining_strategy(rom_retraining_strategy)
    hessian_gain_estimation_strategy = _normalize_hessian_gain_estimation_strategy(hessian_gain_estimation_strategy)
    mfmc_fixed_gain = _normalize_mfmc_fixed_gain(mfmc_fixed_gain)
    gain_sample_size = _validate_gain_sample_size(gain_sample_size)
    gradient_gain_estimation_strategy = _normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy)
    if gradient_gain_estimation_strategy == 'k_fold':
        validate_gain_num_folds(gain_num_folds)
    gain_history_data = None

    def prepare_history_data(active_rom, reuse_predictions):
        if gain_history_state is None or not gain_history_state.get('gain_training_batches'):
            raise ValueError('History gain estimation requires the accepted HF training window.')
        history = gain_history_state
        batches = history['gain_training_batches']
        historical_parameters = np.concatenate([batch['parameter_samples'] for batch in batches])
        historical_optimizer = np.concatenate([batch['optimizer_samples'] for batch in batches])
        ids = [identifier for batch in batches for identifier in batch['sample_ids']]
        priors = np.concatenate([batch['log_priors'] for batch in batches])
        jacobians = np.concatenate([batch['log_transform_jacobian'] for batch in batches])
        cache = {}
        if reuse_predictions and active_rom is history['rom_model']:
            previous_data = history.get('gain_history_data')
            if previous_data is not None:
                cache.update(zip(previous_data['sample_ids'], previous_data['low_log_joint']))
            cache.update(zip(sample_ids(history['gain_iteration_directory'], len(history['parameter_samples_fom'])),
                             history['log_joint_terms_rom_base']))
        missing = np.array([identifier not in cache for identifier in ids])
        low_joint = np.array([cache.get(identifier, 0.0) for identifier in ids])
        if np.any(missing):
            history_results = run_vi_iteration(
                active_rom, observations, f'{iteration_directory}/run_rom_gain_history_',
                parameter_names, historical_parameters[missing], rom_evaluation_concurrency, rom_dispatcher,
            )
            history_ll, _ = _compute_log_likelihoods(
                history_results['errors'], observations_covariance, covariance_regularization,
                precision_operator=log_likelihood_precision_operator,
            )
            low_joint[missing] = history_ll+priors[missing]+jacobians[missing]
        target_std, _ = _compute_variational_std(variational_log_std, min_variational_std, max_variational_std)
        probabilities, log_weights, ess = importance_weights(
            historical_optimizer, variational_mean, target_std, variational_correlation_cholesky, batches,
        )
        target_cholesky = (np.diag(target_std) if variational_correlation_cholesky is None
                           else target_std[:, None]*variational_correlation_cholesky)
        return dict(
            optimizer_samples=historical_optimizer, parameter_samples=historical_parameters,
            high_log_joint=np.concatenate([batch['high_log_joint'] for batch in batches]),
            low_log_joint=low_joint, mean=variational_mean.copy(), std=target_std.copy(),
            correlation_cholesky=variational_correlation_cholesky,
            cholesky=target_cholesky, source_directory=batches[-1]['source_directory'],
            source_directories=[batch['source_directory'] for batch in batches], sample_ids=ids,
            importance_weights=probabilities, log_importance_weights=log_weights,
            effective_sample_size=ess, gain_fallback=ess < 2-1e-12,
            proposal_distributions=[dict(mean=batch['mean'].copy(), std=batch['std'].copy(),
                                         correlation_cholesky=batch['correlation_cholesky'],
                                         sample_count=len(batch['parameter_samples'])) for batch in batches],
        )

    if (gradient_gain_estimation_strategy == 'history' and rom_model is not None
            and rom_retraining_strategy == 'delayed' and use_mfmc_control_variate
            and rom_extra_sample_size > 0):
        # Freeze the historical fitting data before drawing this trial's samples.
        gain_history_data = prepare_history_data(rom_model, True)

    run_directory_base = f'{iteration_directory}/run_fom_sample_set_0_'
    optimizer_samples_fom, parameter_samples_fom = _draw_parameter_samples(
        variational_mean,
        variational_log_std,
        fom_sample_size,
        min_variational_std,
        max_variational_std,
        bounded_parameter_handling,
        parameter_mins,
        parameter_maxes,
        transform_interior_margin=transform_interior_margin,
        transform_map=transform_map,
        variational_correlation_cholesky=variational_correlation_cholesky,
        sampling_method=sampling_method,
    )

    rom_retraining_strategy = _normalize_rom_retraining_strategy(rom_retraining_strategy)
    hessian_gain_estimation_strategy = _normalize_hessian_gain_estimation_strategy(hessian_gain_estimation_strategy)
    mfmc_fixed_gain = _normalize_mfmc_fixed_gain(mfmc_fixed_gain)
    gain_sample_size = _validate_gain_sample_size(gain_sample_size)
    gradient_gain_estimation_strategy = _normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy)
    if gradient_gain_estimation_strategy == 'k_fold':
        validate_gain_num_folds(gain_num_folds)
    validate_gain_sampling(gradient_gain_estimation_strategy, _normalize_sampling_method(sampling_method))
    optimizer_samples_rom_base = optimizer_samples_fom.copy()
    parameter_samples_rom_base = parameter_samples_fom.copy()
    delayed_adaptation = rom_retraining_strategy == 'delayed'
    bootstrap_rom = rom_model is None

    if rom_extra_sample_size > 0:
        optimizer_samples_rom_extra, parameter_samples_rom_extra = _draw_parameter_samples(
            variational_mean,
            variational_log_std,
            rom_extra_sample_size,
            min_variational_std,
            max_variational_std,
            bounded_parameter_handling,
            parameter_mins,
            parameter_maxes,
            transform_interior_margin=transform_interior_margin,
            transform_map=transform_map,
            variational_correlation_cholesky=variational_correlation_cholesky,
            sampling_method=sampling_method,
        )
    else:
        optimizer_samples_rom_extra = np.zeros((0, variational_mean.size))
        parameter_samples_rom_extra = np.zeros((0, variational_mean.size))

    run_directory_base = f'{iteration_directory}/run_fom_sample_set_0_'
    fom_results = run_vi_iteration(
        model,
        observations,
        run_directory_base,
        parameter_names,
        parameter_samples_fom,
        fom_evaluation_concurrency,
        dispatcher,
    )
    iteration_training_dirs, iteration_training_parameters, iteration_training_qois = _build_iteration_training_data(
        run_directory_base,
        parameter_samples_fom,
        fom_results,
    )
    candidate_training_dirs, candidate_training_parameters, candidate_training_qois = _append_training_data(
        training_dirs,
        training_parameters,
        training_qois,
        iteration_training_dirs,
        iteration_training_parameters,
        iteration_training_qois,
    )

    rom_model_candidate = rom_model
    candidate_rom_training_dirs = copy.deepcopy(rom_training_dirs)
    candidate_rom_training_parameters = (
        None if rom_training_parameters is None else rom_training_parameters.copy()
    )
    candidate_rom_training_qois = None if rom_training_qois is None else rom_training_qois.copy()

    if rom_model_candidate is None:
        candidate_rom_training_dirs = candidate_training_dirs[-max_rom_training_dirs:]
        candidate_rom_training_parameters = candidate_training_parameters[-max_rom_training_dirs:]
        candidate_rom_training_qois = candidate_training_qois[-max_rom_training_dirs:]
        rom_model_candidate = rom_model_builder.build_from_training_dirs(
            iteration_directory,
            candidate_rom_training_dirs,
            candidate_rom_training_parameters,
            candidate_rom_training_qois,
        )

    run_directory_base = f'{iteration_directory}/run_rom_sample_set_0_'
    rom_results_base = run_vi_iteration(
        rom_model_candidate,
        observations,
        run_directory_base,
        parameter_names,
        parameter_samples_rom_base,
        rom_evaluation_concurrency,
        rom_dispatcher,
    )
    rom_error = _compute_rom_relative_error(
        rom_results_base['mean-qoi'][:, None],
        fom_results['mean-qoi'][:, None],
    )
    rom_rebuilt_this_iteration = bootstrap_rom

    if rom_error >= rom_tolerance and not delayed_adaptation and not bootstrap_rom and allow_rom_retraining:
        candidate_rom_training_dirs = candidate_training_dirs[-max_rom_training_dirs:]
        candidate_rom_training_parameters = candidate_training_parameters[-max_rom_training_dirs:]
        candidate_rom_training_qois = candidate_training_qois[-max_rom_training_dirs:]
        print(
            "Retraining ROM: "
            f"iteration_directory={iteration_directory}, "
            f"rom_error={rom_error:.5e}, "
            f"rom_tolerance={rom_tolerance:.5e}, "
            f"training_samples={len(candidate_rom_training_dirs)}"
        )
        rom_model_candidate = rom_model_builder.build_from_training_dirs(
            iteration_directory,
            candidate_rom_training_dirs,
            candidate_rom_training_parameters,
            candidate_rom_training_qois,
        )
        rom_rebuilt_this_iteration = True
        rom_results_base = run_vi_iteration(
            rom_model_candidate,
            observations,
            run_directory_base,
            parameter_names,
            parameter_samples_rom_base,
            rom_evaluation_concurrency,
            rom_dispatcher,
        )
        rom_error = _compute_rom_relative_error(
            rom_results_base['mean-qoi'][:, None],
            fom_results['mean-qoi'][:, None],
        )

    if rom_extra_sample_size > 0:
        run_directory_base = f'{iteration_directory}/run_rom_sample_set_1_'
        rom_results_extra = run_vi_iteration(
            rom_model_candidate,
            observations,
            run_directory_base,
            parameter_names,
            parameter_samples_rom_extra,
            rom_evaluation_concurrency,
            rom_dispatcher,
        )
    else:
        rom_results_extra = {
            'qois': np.zeros((fom_results['qois'].shape[0], 0)),
            'mean-qoi': fom_results['mean-qoi'],
            'errors': np.zeros((fom_results['errors'].shape[0], 0)),
        }

    if log_likelihood_precision_operator is None:
        log_likelihood_precision_operator = _compute_log_likelihood_precision_operator(
            observations_covariance,
            covariance_regularization,
        )

    if (gradient_gain_estimation_strategy == 'history' and not bootstrap_rom
            and use_mfmc_control_variate and rom_extra_sample_size > 0
            and (gain_history_data is None or rom_rebuilt_this_iteration)):
        gain_history_data = prepare_history_data(rom_model_candidate, not rom_rebuilt_this_iteration)

    fom_log_likelihoods, fom_misfits = _compute_log_likelihoods(
        fom_results['errors'],
        observations_covariance,
        covariance_regularization,
        precision_operator=log_likelihood_precision_operator,
    )
    if elbo_scaling_factor is None:
        elbo_scaling_factor = _initial_expected_misfit_scale(fom_misfits)
    rom_log_likelihoods_base, _ = _compute_log_likelihoods(
        rom_results_base['errors'],
        observations_covariance,
        covariance_regularization,
        precision_operator=log_likelihood_precision_operator,
    )
    if rom_extra_sample_size > 0:
        rom_log_likelihoods_extra, _ = _compute_log_likelihoods(
            rom_results_extra['errors'],
            observations_covariance,
            covariance_regularization,
            precision_operator=log_likelihood_precision_operator,
        )
    else:
        rom_log_likelihoods_extra = np.zeros(0)

    fom_log_priors, fom_log_transform_jacobian, fom_log_joint_terms = (
        _compute_log_prior_and_joint_terms(
            fom_log_likelihoods,
            parameter_samples_fom,
            optimizer_samples_fom,
            prior_mean,
            prior_precision_operator,
            prior_covariance_log_det,
            bounded_parameter_handling,
            parameter_mins,
            parameter_maxes,
            transform_interior_margin,
            transform_map,
        )
    )
    rom_log_priors_base, rom_log_transform_jacobian_base, rom_log_joint_terms_base = (
        _compute_log_prior_and_joint_terms(
            rom_log_likelihoods_base,
            parameter_samples_rom_base,
            optimizer_samples_rom_base,
            prior_mean,
            prior_precision_operator,
            prior_covariance_log_det,
            bounded_parameter_handling,
            parameter_mins,
            parameter_maxes,
            transform_interior_margin,
            transform_map,
        )
    )
    if rom_extra_sample_size > 0:
        rom_log_priors_extra, rom_log_transform_jacobian_extra, rom_log_joint_terms_extra = (
            _compute_log_prior_and_joint_terms(
                rom_log_likelihoods_extra,
                parameter_samples_rom_extra,
                optimizer_samples_rom_extra,
                prior_mean,
                prior_precision_operator,
                prior_covariance_log_det,
                bounded_parameter_handling,
                parameter_mins,
                parameter_maxes,
                transform_interior_margin,
                transform_map,
            )
        )
    else:
        rom_log_priors_extra = np.zeros(0)
        rom_log_transform_jacobian_extra = np.zeros(0)
        rom_log_joint_terms_extra = np.zeros(0)

    variational_std, variational_log_std = _compute_variational_std(
        variational_log_std,
        min_variational_std,
        max_variational_std,
    )
    gain_independent_data = None
    if (gradient_gain_estimation_strategy == 'independent' and not bootstrap_rom
            and use_mfmc_control_variate and rom_extra_sample_size > 0):
        count = fom_sample_size if gain_sample_size is None else gain_sample_size
        gain_x, gain_parameters = _draw_parameter_samples(
            variational_mean, variational_log_std, count, min_variational_std, max_variational_std,
            bounded_parameter_handling, parameter_mins, parameter_maxes,
            transform_interior_margin=transform_interior_margin, transform_map=transform_map,
            variational_correlation_cholesky=variational_correlation_cholesky, sampling_method=sampling_method,
        )
        gain_joints = []
        for gain_model, concurrency, gain_dispatcher, prefix in (
                (model, fom_evaluation_concurrency, dispatcher, 'fom'),
                (rom_model_candidate, rom_evaluation_concurrency, rom_dispatcher, 'rom')):
            results = run_vi_iteration(
                gain_model, observations, f'{iteration_directory}/run_{prefix}_gain_independent_',
                parameter_names, gain_parameters, concurrency, gain_dispatcher,
            )
            likelihoods, _ = _compute_log_likelihoods(
                results['errors'], observations_covariance, covariance_regularization,
                precision_operator=log_likelihood_precision_operator,
            )
            _, _, joint = _compute_log_prior_and_joint_terms(
                likelihoods, gain_parameters, gain_x, prior_mean, prior_precision_operator,
                prior_covariance_log_det, bounded_parameter_handling, parameter_mins, parameter_maxes,
                transform_interior_margin, transform_map,
            )
            gain_joints.append(joint)
        target_std, _ = _compute_variational_std(variational_log_std, min_variational_std, max_variational_std)
        gain_independent_data = dict(
            optimizer_samples=gain_x, parameter_samples=gain_parameters,
            high_log_joint=gain_joints[0], low_log_joint=gain_joints[1],
            mean=variational_mean.copy(), std=target_std.copy(),
            correlation_cholesky=(None if variational_correlation_cholesky is None
                                  else variational_correlation_cholesky.copy()),
            cholesky=(np.diag(target_std) if variational_correlation_cholesky is None
                      else target_std[:, None]*variational_correlation_cholesky),
        )

    (
        gradient_mean,
        gradient_log_std,
        baseline_mean,
        baseline_log_std,
        alpha_mean,
        alpha_log_std,
        gradient_signal_to_noise_ratio,
        gradient_standard_error,
        gradient_gain_samples,
    ) = (
        _compute_mfmc_reinforce_gradients(
            optimizer_samples_fom,
            optimizer_samples_rom_base,
            optimizer_samples_rom_extra,
            variational_mean,
            variational_std,
            fom_log_joint_terms,
            rom_log_joint_terms_base,
            rom_log_joint_terms_extra,
            baseline_method,
            use_mfmc_control_variate,
            mfmc_control_variate_mode,
            variational_correlation_cholesky,
            elbo_scaling_factor,
            score_function_entropy_strategy,
            gradient_gain_estimation_strategy=gradient_gain_estimation_strategy,
            gain_num_folds=gain_num_folds,
            force_unit_gain=bootstrap_rom,
            return_gain_samples=True,
            gain_history_data=gain_history_data,
            gain_independent_data=gain_independent_data,
            mfmc_fixed_gain=mfmc_fixed_gain,
        )
    )
    hessian_full, hessian_gain_samples = _compute_mfmc_reinforce_hessian_full(
        optimizer_samples_fom,
        optimizer_samples_rom_base,
        optimizer_samples_rom_extra,
        variational_mean,
        variational_std,
        fom_log_joint_terms,
        rom_log_joint_terms_base,
        rom_log_joint_terms_extra,
        baseline_method,
        use_mfmc_control_variate,
        mfmc_control_variate_mode,
        variational_correlation_cholesky,
        elbo_scaling_factor,
        hessian_gain_estimation_strategy=hessian_gain_estimation_strategy,
        force_unit_gain=bootstrap_rom,
        return_gain_samples=True,
        mfmc_fixed_gain=mfmc_fixed_gain,
    )
    dimensionality = variational_mean.size
    hessian_diagonal_mean = np.diag(hessian_full[:dimensionality, :dimensionality])
    hessian_diagonal_log_std = np.diag(hessian_full[dimensionality:, dimensionality:])
    update_direction_mean, update_direction_log_std, normalized_gradient_method = _compute_update_directions(
        gradient_mean,
        gradient_log_std,
        variational_std,
        gradient_method,
    )

    dimensionality = variational_mean.size
    entropy = np.sum(variational_log_std) + 0.5 * dimensionality * (1.0 + np.log(2.0 * np.pi))
    if variational_correlation_cholesky is not None:
        entropy += np.sum(np.log(np.diag(variational_correlation_cholesky)))
    entropy *= elbo_scaling_factor
    if rom_extra_sample_size > 0:
        low_fidelity_full_log_joint_terms = np.concatenate(
            [rom_log_joint_terms_base, rom_log_joint_terms_extra]
        )
        mfmc_mean_log_joint = (
            np.mean(fom_log_joint_terms)
            + np.mean(low_fidelity_full_log_joint_terms)
            - np.mean(rom_log_joint_terms_base)
        )
    else:
        mfmc_mean_log_joint = np.mean(fom_log_joint_terms)
    elbo = elbo_scaling_factor * mfmc_mean_log_joint + entropy

    optimizer_samples = np.vstack([
        optimizer_samples_fom,
        optimizer_samples_rom_base,
        optimizer_samples_rom_extra,
    ])
    parameter_samples = np.vstack([
        parameter_samples_fom,
        parameter_samples_rom_base,
        parameter_samples_rom_extra,
    ])
    state = {
        'optimizer_samples': optimizer_samples,
        'parameter_samples': parameter_samples,
        'parameter_samples_fom': parameter_samples_fom,
        'parameter_samples_rom_base': parameter_samples_rom_base,
        'parameter_samples_rom_only': parameter_samples_rom_extra,
        'qois_fom': fom_results['qois'],
        'mean_qoi_fom': fom_results['mean-qoi'],
        'errors_fom': fom_results['errors'],
        'qois_rom_base': rom_results_base['qois'],
        'qois_rom_coupled': rom_results_base['qois'],
        'qois_rom_only': rom_results_extra['qois'],
        'log_likelihoods_fom': fom_log_likelihoods,
        'log_priors_fom': fom_log_priors,
        'log_joint_terms_fom': fom_log_joint_terms,
        'log_transform_jacobian_fom': fom_log_transform_jacobian,
        'log_likelihoods_rom_base': rom_log_likelihoods_base,
        'log_priors_rom_base': rom_log_priors_base,
        'log_joint_terms_rom_base': rom_log_joint_terms_base,
        'log_transform_jacobian_rom_base': rom_log_transform_jacobian_base,
        'log_likelihoods_rom_coupled': rom_log_likelihoods_base,
        'log_likelihoods_rom_only': rom_log_likelihoods_extra,
        'log_priors_rom_only': rom_log_priors_extra,
        'log_joint_terms_rom_only': rom_log_joint_terms_extra,
        'log_transform_jacobian_rom_only': rom_log_transform_jacobian_extra,
        'mean_misfit': np.mean(fom_misfits),
        'elbo_scaling_factor': elbo_scaling_factor,
        'mean_relative_mse': np.mean(_compute_relative_mse(fom_results['errors'], observations)),
        'entropy': entropy,
        'elbo': elbo,
        'gradient_mean': gradient_mean,
        'gradient_log_std': gradient_log_std,
        'hessian_diagonal_mean': hessian_diagonal_mean,
        'hessian_diagonal_log_std': hessian_diagonal_log_std,
        'hessian_full': hessian_full,
        'update_direction_mean': update_direction_mean,
        'update_direction_log_std': update_direction_log_std,
        'gradient_method': normalized_gradient_method,
        'baseline_mean': baseline_mean,
        'baseline_log_std': baseline_log_std,
        'gradient_signal_to_noise_ratio': gradient_signal_to_noise_ratio,
        'gradient_standard_error': gradient_standard_error,
        'mfmc_alpha_mean': alpha_mean,
        'mfmc_alpha_log_std': alpha_log_std,
        'rom_error': rom_error,
        'rom_tolerance': rom_tolerance,
        'rom_rebuilt_this_iteration': rom_rebuilt_this_iteration,
        'rom_model': rom_model_candidate,
        'rom_retraining_strategy': rom_retraining_strategy,
        'gradient_gain_estimation_strategy': gradient_gain_estimation_strategy,
        'hessian_gain_estimation_strategy': hessian_gain_estimation_strategy,
        'gain_num_folds': gain_num_folds,
        'gain_fold_indices': gain_folds(len(parameter_samples_fom), gain_num_folds) if gradient_gain_estimation_strategy == 'k_fold' else None,
        'bootstrap_rom': bootstrap_rom,
        'gain_history_data': gain_history_data,
        'gain_independent_data': gain_independent_data,
        'gain_sample_size': gain_sample_size,
        'use_mfmc_control_variate': bool(use_mfmc_control_variate),
        'mfmc_fixed_gain': mfmc_fixed_gain,
        'gain_distribution_mean': variational_mean.copy(),
        'gain_distribution_std': variational_std.copy(),
        'gain_distribution_correlation_cholesky': (None if variational_correlation_cholesky is None
                                                  else variational_correlation_cholesky.copy()),
        'gain_iteration_directory': iteration_directory,
        'gradient_gain_samples': gradient_gain_samples,
        'hessian_gain_samples': hessian_gain_samples,
        'rom_adaptation_required': delayed_adaptation and (
            not bootstrap_rom and allow_rom_retraining and rom_error >= rom_tolerance
        ),
        'pending_rom_model': None,
        'pending_rom_training_dirs': [],
        'pending_rom_training_parameters': None,
        'pending_rom_training_qois': None,

        'training_dirs': candidate_training_dirs,
        'training_parameters': candidate_training_parameters,
        'training_qois': candidate_training_qois,
        'rom_training_dirs': candidate_rom_training_dirs,
        'rom_training_parameters': candidate_rom_training_parameters,
        'rom_training_qois': candidate_rom_training_qois,
    }
    if gradient_gain_estimation_strategy == 'history':
        batch = dict(
            parameter_samples=parameter_samples_fom.copy(), optimizer_samples=optimizer_samples_fom.copy(),
            high_log_joint=fom_log_joint_terms.copy(), log_priors=fom_log_priors.copy(),
            log_transform_jacobian=fom_log_transform_jacobian.copy(),
            mean=variational_mean.copy(), std=variational_std.copy(),
            correlation_cholesky=(None if variational_correlation_cholesky is None
                                  else variational_correlation_cholesky.copy()),
            source_directory=iteration_directory,
            sample_ids=sample_ids(iteration_directory, len(parameter_samples_fom)),
        )
        batches = [] if gain_history_state is None else gain_history_state['gain_training_batches']
        state['gain_training_batches'] = append_training_batch(batches, batch, max_rom_training_dirs)
        state['gain_history_training_limit'] = max_rom_training_dirs
    return state


def _validate_run_mf_vi_inputs(restart_file: str,
                               absolute_work_dir: str,
                               fom_sample_size: int,
                               rom_extra_sample_size: int,
                               max_step_size: float,
                               step_size_growth_factor: float,
                               step_size_decay_factor: float,
                               line_search_sample_growth_factor: float,
                               relaxation_parameter: float,
                               line_search_method: str,
                               line_search_nonmonotone_window: int,
                               line_search_armijo_coefficient: float,
                               line_search_uncertainty_sigma: float,
                               min_variational_std: float,
                               max_variational_std: float,
                               max_log_std_update: float,
                               max_mean_update_std: float,
                               newton_regularization: float,
                               newton_regularization_strategy: str,
                               newton_regularization_epsilon: float,
                               newton_additive_regularization: float,
                               newton_adaptive_regularization: bool,
                               newton_regularization_increase_factor: float,
                               newton_regularization_decrease_factor: float,
                               newton_regularization_max_multiplier: float,
                               newton_hessian_type: str,
                               covariance_regularization: float,
                               restart_files_to_keep: int,
                               gradient_gain_estimation_strategy: str,
                               observations_covariance: np.ndarray,
                               observations: np.ndarray,
                               elbo_scaling_factor: float,
                               elbo_relative_tolerance: float,
                               sampling_method: str,
                               max_rom_training_history: int,
                               prior_parameter_space,
                               initial_variational_parameter_space,
                               parameter_mins: np.ndarray,
                               parameter_maxes: np.ndarray,
                               transform_interior_margin: float,
                               transform_map: str,
                               min_physical_variational_std_fraction: float,
                               bounded_parameter_handling: str,
                               dispatcher: Optional[BaseDispatcher] = None,
                               gain_num_folds: int = 5,
                               hessian_gain_estimation_strategy: str = "same_sample") -> None:
    if restart_file is not None:
        assert os.path.isfile(restart_file), f"restart_file does not exist ({restart_file})"
    require_relative_or_absolute_path(resolve_dispatcher(dispatcher), absolute_work_dir)
    assert fom_sample_size > 1, "fom_sample_size must be greater than 1"
    assert rom_extra_sample_size >= 0, "rom_extra_sample_size must be non-negative"
    assert max_step_size > 0.0, "max_step_size must be positive"
    assert step_size_growth_factor >= 1.0, "step_size_growth_factor must be greater than 1.0"
    assert step_size_decay_factor >= 1.0, "step_size_decay_factor must be greater than 1.0"
    assert line_search_sample_growth_factor >= 1.0, (
        "line_search_sample_growth_factor must be greater than or equal to 1.0"
    )
    assert relaxation_parameter >= 1.0, "relaxation_parameter must be >= 1.0"
    if line_search_method == 'stochastic_nonmonotone':
        assert line_search_nonmonotone_window >= 1, "line_search_nonmonotone_window must be >= 1"
        assert 0.0 <= line_search_armijo_coefficient <= 1.0, (
            "line_search_armijo_coefficient must be in [0,1]"
        )
        assert line_search_uncertainty_sigma >= 0.0, "line_search_uncertainty_sigma must be non-negative"
    assert min_variational_std > 0.0, "min_variational_std must be positive"
    assert max_variational_std > min_variational_std, (
        "max_variational_std must be greater than min_variational_std"
    )
    assert min_physical_variational_std_fraction >= 0.0, (
        "min_physical_variational_std_fraction must be non-negative"
    )
    assert max_log_std_update > 0.0, "max_log_std_update must be positive"
    if max_mean_update_std is not None:
        assert max_mean_update_std > 0.0, "max_mean_update_std must be positive"
    assert np.isfinite(newton_regularization) and newton_regularization > 0.0, (
        "newton_regularization must be finite and positive"
    )
    _normalize_newton_regularization_strategy(newton_regularization_strategy)
    assert np.isfinite(newton_regularization_epsilon), (
        "newton_regularization_epsilon must be finite"
    )
    assert newton_regularization_epsilon > 0.0, (
        "newton_regularization_epsilon must be positive"
    )
    assert np.isfinite(newton_additive_regularization), (
        "newton_additive_regularization must be finite"
    )
    assert newton_additive_regularization >= 0.0, (
        "newton_additive_regularization must be non-negative"
    )
    assert isinstance(newton_adaptive_regularization, (bool, np.bool_)), (
        "newton_adaptive_regularization must be a bool"
    )
    if newton_adaptive_regularization and newton_additive_regularization <= 0.0:
        raise ValueError(
            "Adaptive Newton regularization requires a positive "
            "newton_additive_regularization."
        )
    assert (
        np.isfinite(newton_regularization_increase_factor)
        and newton_regularization_increase_factor > 1.0
    ), "newton_regularization_increase_factor must be finite and greater than 1"
    assert (
        np.isfinite(newton_regularization_decrease_factor)
        and newton_regularization_decrease_factor > 1.0
    ), "newton_regularization_decrease_factor must be finite and greater than 1"
    assert (
        np.isfinite(newton_regularization_max_multiplier)
        and newton_regularization_max_multiplier >= 1.0
    ), "newton_regularization_max_multiplier must be finite and at least 1"
    _normalize_newton_hessian_type(newton_hessian_type)
    assert covariance_regularization >= 0.0, "covariance_regularization must be non-negative"
    assert restart_files_to_keep >= 1, "restart_files_to_keep must be >= 1"
    _normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy)
    assert observations_covariance.shape[0] == observations_covariance.shape[1], (
        "observations_covariance must be square"
    )
    assert observations_covariance.shape[0] == observations.size, (
        "observations_covariance shape must match observations size"
    )
    assert elbo_scaling_factor is None or elbo_scaling_factor > 0.0, "elbo_scaling_factor must be positive"
    if elbo_relative_tolerance is not None:
        assert elbo_relative_tolerance >= 0.0, "elbo_relative_tolerance must be non-negative"
    _normalize_sampling_method(sampling_method)
    _normalize_transform_map(transform_map)
    assert max_rom_training_history >= 1, "max_rom_training_history must be >= 1"

    parameter_names, _, _, _, initial_variational_mean, initial_variational_covariance, _ = (
        _validate_gaussian_parameter_spaces(
            prior_parameter_space,
            initial_variational_parameter_space,
        )
    )
    parameter_dimensionality = np.asarray(initial_variational_mean).size
    assert len(parameter_names) > 0, "prior_parameter_space must define at least one parameter"
    covariance = np.asarray(initial_variational_covariance)
    assert covariance.ndim == 2, "initial variational covariance must be a 2D array"
    assert covariance.shape[0] == covariance.shape[1], (
        "initial variational covariance must be square"
    )
    assert covariance.shape[0] == parameter_dimensionality, (
        "initial variational covariance shape must match initial variational mean size"
    )
    if parameter_mins is not None:
        assert np.size(parameter_mins) == parameter_dimensionality, (
            f"parameter_mins of size {np.size(parameter_mins)} is inconsistent with "
            f"the variational dimensionality of size {parameter_dimensionality}"
        )
    if parameter_maxes is not None:
        assert np.size(parameter_maxes) == parameter_dimensionality, (
            f"parameter_maxes of size {np.size(parameter_maxes)} is inconsistent with "
            f"the variational dimensionality of size {parameter_dimensionality}"
        )
    if bounded_parameter_handling == 'transform':
        assert 0.0 <= transform_interior_margin < 0.5, (
            "transform_interior_margin must be in [0.0, 0.5)"
        )
        assert parameter_mins is not None, "parameter_mins must be provided for bounded_parameter_handling='transform'"
        assert parameter_maxes is not None, "parameter_maxes must be provided for bounded_parameter_handling='transform'"
        assert np.size(parameter_mins) == parameter_dimensionality, (
            f"parameter_mins of size {np.size(parameter_mins)} is inconsistent with "
            f"the variational dimensionality of size {parameter_dimensionality}"
        )
        assert np.size(parameter_maxes) == parameter_dimensionality, (
            f"parameter_maxes of size {np.size(parameter_maxes)} is inconsistent with "
            f"the variational dimensionality of size {parameter_dimensionality}"
        )
        assert np.all(parameter_maxes > parameter_mins), (
            "All parameter_maxes entries must be greater than parameter_mins entries "
            "for bounded_parameter_handling='transform'"
        )


[docs] def run_mf_vi(model: QoiModel, rom_model_builder: QoiModelBuilderWithTrainingData, prior_parameter_space, observations: np.ndarray, observations_covariance: np.ndarray, parameter_mins: np.ndarray = None, parameter_maxes: np.ndarray = None, initial_variational_parameter_space=None, restart_file: str = None, optimizer_method: str = 'gradient', optimizer_config=None, line_search_method: str = 'stochastic_nonmonotone', line_search_config=None, absolute_work_dir: str = None, fom_sample_size: int = 10, rom_extra_sample_size: int = 30, rom_tolerance: float = 0.005, max_rom_training_history: int = 1, random_seed: int = 1, sampling_method: str = 'mc', fom_evaluation_concurrency=10, rom_evaluation_concurrency=1, covariance_regularization: float = 1e-7, restart_files_to_keep: int = 10, rom_retraining_strategy: str = 'delayed', gradient_gain_estimation_strategy: str = 'same_sample', elbo_scaling_factor='diag_mean', elbo_relative_tolerance: float = None, baseline_method: str = None, use_mfmc_control_variate: bool = True, mfmc_control_variate_mode: str = 'componentwise', bounded_parameter_handling: str = 'transform', transform_interior_margin: float = 1e-8, transform_map: str = 'sigmoid', min_physical_variational_std_fraction: float = 1e-8, dispatcher: Optional[BaseDispatcher] = None, *, absolute_vi_directory: str = None, score_function_entropy_strategy: str = 'analytic', rom_substep_start_iteration: int = 0, rom_substep_end_iteration: Optional[int] = None, num_rom_substeps: int = 0, gain_num_folds: int = 5, hessian_gain_estimation_strategy: str = "same_sample", gain_sample_size=None, mfmc_fixed_gain: float = 1.0, _reuse_controller=None): """ Run multi-fidelity VI with MFMC variance-reduced score-function gradients. Args: prior_parameter_space: Either GaussianParameterSpace (diagonal VI) or MultivariateGaussianParameterSpace (multivariate VI). Defines the Bayesian prior in physical parameter space. parameter_mins: Optional lower bounds on parameters. parameter_maxes: Optional upper bounds on parameters. initial_variational_parameter_space: Required Gaussian initializer for the variational state in physical parameter space. restart_file: Optional restart file path. Restart files written by this routine store `variational_mean` in physical coordinates. optimizer_method: Optimizer used for variational updates. Supported options are 'gradient', 'adam', and 'newton'. optimizer_config: Method-specific optimizer config. Expected types are `VIGradientOptimizerConfig` for optimizer_method='gradient', `VIAdamOptimizerConfig` for optimizer_method='adam', and `VINewtonOptimizerConfig` for optimizer_method='newton'. line_search_method: Line-search acceptance strategy. Supported options are 'none' (fixed-step Newton), 'legacy', and 'stochastic_nonmonotone'. Defaults to 'stochastic_nonmonotone'. line_search_config: Method-specific line-search config. Expected types are `VILegacyLineSearchConfig` for line_search_method='legacy' and `VIStochasticNonmonotoneLineSearchConfig` for line_search_method='stochastic_nonmonotone'. For Newton without line search, use ``line_search_method='none'`` and optionally ``line_search_config=VINoLineSearchConfig(step_size=0.5)``. sampling_method: Sampling method for variational draws. Supported options are 'mc' and 'rqmc'. mfmc_control_variate_mode: Control-variate coefficient strategy. 'componentwise' computes one scalar coefficient per component. 'scalar' computes one shared scalar coefficient (A = alpha I). 'matrix' computes a joint linear map across components. rom_retraining_strategy: 'same_sample' adapts immediately using the current HF batch and history; 'delayed' trains after acceptance and activates replacements in the next outer iteration. gain_num_folds: Number of balanced outer folds for gradient 'k_fold' gain estimation (default 5, capped at the paired sample count). hessian_gain_estimation_strategy: Hessian gain fitting; only 'same_sample' is supported, independently of the gradient setting. mfmc_fixed_gain: Finite scalar coefficient used for gradient and Hessian corrections when use_mfmc_control_variate=False (default 1.0). Componentwise gains use this value uniformly; matrix gains use it times the identity. Ignored when fitting gains is enabled. gain_sample_size: Independent gradient gain batch size. None matches the current trial HF sample count; a positive integer fixes the count. gradient_gain_estimation_strategy: Gradient gain fitting. 'same_sample' fits one gain on all pairs; 'loo' excludes each held-out pair from its gain and baseline fits; 'k_fold' excludes each held-out fold and shares one gain per fold; 'independent' fits a gain on fresh, separate paired HF/LF samples; 'history' importance-weights the accepted HF training window toward the current variational distribution, using the current ROM. The bootstrap trains immediately and uses a fixed unit gain. transform_interior_margin: Margin used by bounded_parameter_handling='transform' to keep mapped samples away from exact bounds. transform_map: Transform used by bounded_parameter_handling='transform'. Supported options are 'sigmoid' and 'arctan'. min_physical_variational_std_fraction: Minimum physical-space variational standard deviation as a fraction of each parameter range when bounded_parameter_handling='transform'. score_function_entropy_strategy: Entropy treatment in the score-function gradient. ``'analytic'`` retains the analytic Gaussian entropy gradient; ``'joint'`` estimates the full ``log_joint - log_q`` integrand. The joint strategy is not a pathwise estimator. dispatcher: Optional (defaults to None, which instantiates a LocalDispatcher). Pass a RemoteDispatcher to send FOM evaluations to the configured remote host (e.g. an HPC cluster). ROM evaluations always run locally, so a RemoteDispatcher requires a relative `absolute_work_dir` and `fom_evaluation_concurrency=1`. Returns: Tuple of (variational_mean, variational_std, fom_parameter_samples, fom_qois). """ evaluate_state = _evaluate_mf_vi_state if _reuse_controller is None else _reuse_controller.evaluate_state if absolute_vi_directory is not None: warnings.warn( "'absolute_vi_directory' is deprecated; use 'absolute_work_dir' instead.", DeprecationWarning, stacklevel=2, ) if absolute_work_dir is not None: raise TypeError("Specify only 'absolute_work_dir', not both directory arguments.") absolute_work_dir = absolute_vi_directory if absolute_work_dir is None: absolute_work_dir = os.getcwd() + "/work/" validate_rom_substeps( rom_substep_start_iteration, rom_substep_end_iteration, num_rom_substeps, ) dispatcher = resolve_dispatcher(dispatcher) require_supported_concurrency(model, dispatcher, fom_evaluation_concurrency) start_time = time.time() start_cpu_time = time.process_time() parameter_mins, parameter_maxes = _resolve_parameter_bounds( parameter_mins, parameter_maxes, ) restart_file = _resolve_restart_file(restart_file) optimization_method, resolved_optimizer_config = _resolve_optimizer_config( optimizer_method, optimizer_config, VIGradientOptimizerConfig(), VINewtonOptimizerConfig(newton_regularization=1e-8), VIAdamOptimizerConfig(), ) if optimization_method == 'adam' and line_search_config is not None: raise ValueError( "line_search_config is not supported with optimizer_method='adam'; " "Adam supplies the complete update step." ) if _normalize_line_search_method(line_search_method) == 'none' and optimization_method != 'newton': raise ValueError("line_search_method='none' requires optimizer_method='newton'") line_search_method, resolved_line_search_config = _resolve_line_search_config( line_search_method, line_search_config, VILegacyLineSearchConfig( step_size_growth_factor=1.05, relaxation_parameter=10.0, ), VIStochasticNonmonotoneLineSearchConfig( step_size_growth_factor=1.05, relaxation_parameter=10.0, ), ) if optimization_method == 'adam': line_search_method = 'legacy' resolved_line_search_config = VILegacyLineSearchConfig( initial_step_size=1.0, max_step_size=1.0, step_size_growth_factor=1.0, step_size_decay_factor=1.0, max_step_size_decrease_trys=0, relaxation_parameter=1.0, line_search_sample_growth_factor=1.0, log_std_learning_rate_factor=1.0, ) gradient_method = 'standard' if optimization_method in ('gradient', 'adam'): gradient_method = resolved_optimizer_config.gradient_method gradient_norm_tolerance = resolved_optimizer_config.gradient_norm_tolerance max_iterations = resolved_optimizer_config.max_iterations max_log_std_update = resolved_optimizer_config.max_log_std_update max_mean_update_std = None min_variational_std = resolved_optimizer_config.min_variational_std max_variational_std = resolved_optimizer_config.max_variational_std newton_defaults = VINewtonOptimizerConfig(newton_regularization=1e-8) newton_metric = _normalize_newton_metric(newton_defaults.newton_metric) newton_fallback_learning_rate = newton_defaults.newton_fallback_learning_rate newton_regularization = newton_defaults.newton_regularization newton_regularization_strategy = _normalize_newton_regularization_strategy( newton_defaults.newton_regularization_strategy ) newton_regularization_epsilon = newton_defaults.newton_regularization_epsilon newton_additive_regularization = newton_defaults.newton_additive_regularization newton_additive_regularization_growth_factor = ( newton_defaults.newton_additive_regularization_growth_factor ) newton_additive_regularization_max = newton_defaults.newton_additive_regularization_max newton_adaptive_regularization = newton_defaults.newton_adaptive_regularization newton_regularization_increase_factor = ( newton_defaults.newton_regularization_increase_factor ) newton_regularization_decrease_factor = ( newton_defaults.newton_regularization_decrease_factor ) newton_regularization_max_multiplier = ( newton_defaults.newton_regularization_max_multiplier ) newton_hessian_type = _normalize_newton_hessian_type(newton_defaults.newton_hessian_type) newton_curvature_strategy = _normalize_newton_curvature_strategy( newton_defaults.newton_curvature_strategy ) newton_hessian_num_samples = newton_defaults.newton_hessian_num_samples newton_hessian_averaging_factor = newton_defaults.newton_hessian_averaging_factor if optimization_method == 'newton': max_mean_update_std = resolved_optimizer_config.max_mean_update_std newton_metric = _normalize_newton_metric(resolved_optimizer_config.newton_metric) newton_fallback_learning_rate = float(resolved_optimizer_config.newton_fallback_learning_rate) if (not np.isfinite(newton_fallback_learning_rate) or newton_fallback_learning_rate <= 0.0 or not np.isfinite(1.0 / newton_fallback_learning_rate)): raise ValueError("newton_fallback_learning_rate and its reciprocal must be finite and positive.") newton_regularization = resolved_optimizer_config.newton_regularization newton_regularization_strategy = _normalize_newton_regularization_strategy( resolved_optimizer_config.newton_regularization_strategy ) newton_regularization_epsilon = ( resolved_optimizer_config.newton_regularization_epsilon ) newton_additive_regularization = ( resolved_optimizer_config.newton_additive_regularization ) newton_additive_regularization_growth_factor = ( resolved_optimizer_config.newton_additive_regularization_growth_factor ) newton_additive_regularization_max = ( resolved_optimizer_config.newton_additive_regularization_max ) _scheduled_newton_regularization( newton_additive_regularization, newton_additive_regularization_growth_factor, 0, maximum=newton_additive_regularization_max, ) newton_adaptive_regularization = ( resolved_optimizer_config.newton_adaptive_regularization ) newton_regularization_increase_factor = ( resolved_optimizer_config.newton_regularization_increase_factor ) newton_regularization_decrease_factor = ( resolved_optimizer_config.newton_regularization_decrease_factor ) newton_regularization_max_multiplier = ( resolved_optimizer_config.newton_regularization_max_multiplier ) newton_hessian_type = _normalize_newton_hessian_type( resolved_optimizer_config.newton_hessian_type ) newton_curvature_strategy = _normalize_newton_curvature_strategy( resolved_optimizer_config.newton_curvature_strategy ) newton_hessian_num_samples = resolved_optimizer_config.newton_hessian_num_samples newton_hessian_averaging_factor = resolved_optimizer_config.newton_hessian_averaging_factor if newton_hessian_num_samples is not None: assert isinstance(newton_hessian_num_samples, (int, np.integer)), ( "newton_hessian_num_samples must be an integer" ) assert newton_hessian_num_samples > 1, ( "newton_hessian_num_samples must be greater than 1" ) assert np.isfinite(newton_hessian_averaging_factor), ( "newton_hessian_averaging_factor must be finite" ) assert 0.0 <= newton_hessian_averaging_factor < 1.0, ( "newton_hessian_averaging_factor must be in [0, 1)" ) initial_step_size = resolved_line_search_config.initial_step_size max_step_size = resolved_line_search_config.max_step_size step_size_growth_factor = resolved_line_search_config.step_size_growth_factor step_size_decay_factor = resolved_line_search_config.step_size_decay_factor max_step_size_decrease_trys = resolved_line_search_config.max_step_size_decrease_trys relaxation_parameter = resolved_line_search_config.relaxation_parameter line_search_sample_growth_factor = resolved_line_search_config.line_search_sample_growth_factor line_search_nonmonotone_window = 1 line_search_armijo_coefficient = 0.0 line_search_uncertainty_sigma = 0.0 if line_search_method == 'stochastic_nonmonotone': line_search_nonmonotone_window = resolved_line_search_config.line_search_nonmonotone_window line_search_armijo_coefficient = resolved_line_search_config.line_search_armijo_coefficient line_search_uncertainty_sigma = resolved_line_search_config.line_search_uncertainty_sigma max_rom_training_dirs = int(max_rom_training_history * fom_sample_size) elbo_scaling_factor = _resolve_elbo_scaling_factor( elbo_scaling_factor, observations_covariance, ) bounded_parameter_handling = _normalize_bounded_parameter_handling(bounded_parameter_handling) transform_map = _normalize_transform_map(transform_map) ( parameter_names, prior_mean, prior_covariance, _, initial_variational_mean, initial_variational_covariance, variational_distribution, ) = _validate_gaussian_parameter_spaces( prior_parameter_space, initial_variational_parameter_space, ) if ( optimization_method == 'adam' and gradient_method == 'natural' and variational_distribution == 'multivariate' ): raise NotImplementedError( "Natural-gradient Adam is not supported for correlated multivariate " "Gaussian MF-VI. Use VIAdamOptimizerConfig(gradient_method='standard') instead." ) sampling_method = _normalize_sampling_method(sampling_method) rom_retraining_strategy = _normalize_rom_retraining_strategy(rom_retraining_strategy) if baseline_method is None: baseline_method = 'loo' baseline_method = _normalize_baseline_method(baseline_method) score_function_entropy_strategy = _normalize_score_function_entropy_strategy( score_function_entropy_strategy ) mfmc_control_variate_mode = _normalize_mfmc_control_variate_mode( mfmc_control_variate_mode ) hessian_gain_estimation_strategy = _normalize_hessian_gain_estimation_strategy(hessian_gain_estimation_strategy) mfmc_fixed_gain = _normalize_mfmc_fixed_gain(mfmc_fixed_gain) gain_sample_size = _validate_gain_sample_size(gain_sample_size) gradient_gain_estimation_strategy = _normalize_gradient_gain_estimation_strategy(gradient_gain_estimation_strategy) if gradient_gain_estimation_strategy == 'k_fold': validate_gain_num_folds(gain_num_folds) validate_gain_sampling(gradient_gain_estimation_strategy, _normalize_sampling_method(sampling_method)) _validate_run_mf_vi_inputs( restart_file=restart_file, absolute_work_dir=absolute_work_dir, fom_sample_size=fom_sample_size, rom_extra_sample_size=rom_extra_sample_size, max_step_size=max_step_size, step_size_growth_factor=step_size_growth_factor, step_size_decay_factor=step_size_decay_factor, line_search_sample_growth_factor=line_search_sample_growth_factor, relaxation_parameter=relaxation_parameter, line_search_method=line_search_method, line_search_nonmonotone_window=line_search_nonmonotone_window, line_search_armijo_coefficient=line_search_armijo_coefficient, line_search_uncertainty_sigma=line_search_uncertainty_sigma, min_variational_std=min_variational_std, max_variational_std=max_variational_std, max_log_std_update=max_log_std_update, max_mean_update_std=max_mean_update_std, newton_regularization=newton_regularization, newton_regularization_strategy=newton_regularization_strategy, newton_regularization_epsilon=newton_regularization_epsilon, newton_additive_regularization=newton_additive_regularization, newton_adaptive_regularization=newton_adaptive_regularization, newton_regularization_increase_factor=newton_regularization_increase_factor, newton_regularization_decrease_factor=newton_regularization_decrease_factor, newton_regularization_max_multiplier=newton_regularization_max_multiplier, newton_hessian_type=newton_hessian_type, covariance_regularization=covariance_regularization, restart_files_to_keep=restart_files_to_keep, gradient_gain_estimation_strategy=gradient_gain_estimation_strategy, hessian_gain_estimation_strategy=hessian_gain_estimation_strategy, gain_num_folds=gain_num_folds, observations_covariance=observations_covariance, observations=observations, elbo_scaling_factor=elbo_scaling_factor, elbo_relative_tolerance=elbo_relative_tolerance, sampling_method=sampling_method, max_rom_training_history=max_rom_training_history, prior_parameter_space=prior_parameter_space, initial_variational_parameter_space=initial_variational_parameter_space, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, transform_map=transform_map, min_physical_variational_std_fraction=min_physical_variational_std_fraction, bounded_parameter_handling=bounded_parameter_handling, dispatcher=dispatcher, ) log_likelihood_precision_operator = _compute_log_likelihood_precision_operator( observations_covariance, covariance_regularization, ) prior_precision_operator, prior_covariance_log_det = _compute_gaussian_log_density_data( prior_covariance, ) iteration = 0 step_size = min(initial_step_size, max_step_size) variational_correlation_cholesky = None vi_history = _initialize_vi_history() if restart_file is None: np.random.seed(random_seed) initial_optimizer_mean, initial_optimizer_covariance = ( _convert_physical_moments_to_optimizer_moments( initial_variational_mean, initial_variational_covariance, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, transform_map, ) ) ( variational_mean, variational_log_std, variational_correlation_cholesky, ) = _initialize_variational_from_mean_cov( initial_optimizer_mean, initial_optimizer_covariance, variational_distribution, min_variational_std, max_variational_std, ) variational_log_std = _enforce_variational_log_std_bounds( variational_mean, variational_log_std, min_variational_std, max_variational_std, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, min_physical_variational_std_fraction, transform_map, ) state = evaluate_state( gain_sample_size=gain_sample_size, model=model, rom_model=None, rom_model_builder=rom_model_builder, observations=observations, observations_covariance=observations_covariance, iteration_directory=f'{absolute_work_dir}/iteration_{iteration}', parameter_names=parameter_names, variational_mean=variational_mean, variational_log_std=variational_log_std, prior_mean=prior_mean, prior_precision_operator=prior_precision_operator, prior_covariance_log_det=prior_covariance_log_det, fom_sample_size=fom_sample_size, rom_extra_sample_size=rom_extra_sample_size, fom_evaluation_concurrency=fom_evaluation_concurrency, rom_evaluation_concurrency=rom_evaluation_concurrency, covariance_regularization=covariance_regularization, baseline_method=baseline_method, use_mfmc_control_variate=use_mfmc_control_variate, mfmc_control_variate_mode=mfmc_control_variate_mode, variational_correlation_cholesky=variational_correlation_cholesky, elbo_scaling_factor=elbo_scaling_factor, gradient_method=gradient_method, bounded_parameter_handling=bounded_parameter_handling, min_variational_std=min_variational_std, max_variational_std=max_variational_std, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, transform_map=transform_map, rom_tolerance=rom_tolerance, max_rom_training_dirs=max_rom_training_dirs, rom_retraining_strategy=rom_retraining_strategy, gradient_gain_estimation_strategy=gradient_gain_estimation_strategy, hessian_gain_estimation_strategy=hessian_gain_estimation_strategy, gain_num_folds=gain_num_folds, training_dirs=[], training_parameters=None, training_qois=None, rom_training_dirs=[], rom_training_parameters=None, rom_training_qois=None, log_likelihood_precision_operator=log_likelihood_precision_operator, sampling_method=sampling_method, dispatcher=dispatcher, score_function_entropy_strategy=score_function_entropy_strategy, mfmc_fixed_gain=mfmc_fixed_gain, ) if elbo_scaling_factor is None: elbo_scaling_factor = state['elbo_scaling_factor'] initial_elbo_reference = float(state['elbo']) else: restart_data = np.load(restart_file, allow_pickle=True) if 'line_search_method' in restart_data: saved_method = restart_data['line_search_method'].item() if saved_method is not None and saved_method != line_search_method: raise ValueError("Restart file line_search_method does not match current run.") elbo_scaling_factor = _restore_initial_expected_misfit_scale( elbo_scaling_factor, restart_data ) ( rom_substep_start_iteration, rom_substep_end_iteration, num_rom_substeps, ) = restore_rom_substeps( restart_data, rom_substep_start_iteration, rom_substep_end_iteration, num_rom_substeps, ) vi_history = _load_vi_history_from_restart(restart_data) if 'rng_state' in restart_data: np.random.set_state(tuple(restart_data['rng_state'].tolist())) else: np.random.seed(random_seed) iteration = int(restart_data['iteration']) step_size = min(initial_step_size, max_step_size) variational_mean = _restore_variational_mean_from_restart( restart_data, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, transform_map, ) variational_log_std = _clip_variational_log_std( restart_data['variational_log_std'], min_variational_std, max_variational_std, ) variational_log_std = _enforce_variational_log_std_bounds( variational_mean, variational_log_std, min_variational_std, max_variational_std, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, min_physical_variational_std_fraction, transform_map, ) if 'bounded_parameter_handling' in restart_data: restart_bounded_parameter_handling = str( restart_data['bounded_parameter_handling'].item() ) if restart_bounded_parameter_handling != bounded_parameter_handling: raise ValueError( "restart_file bounded_parameter_handling does not match current run." ) if 'transform_map' in restart_data: restart_transform_map = _normalize_transform_map( str(restart_data['transform_map'].item()) ) if restart_transform_map != transform_map: raise ValueError("restart_file transform_map does not match current run.") if 'variational_distribution' in restart_data: restart_variational_distribution = str(restart_data['variational_distribution'].item()) if restart_variational_distribution != variational_distribution: raise ValueError( "restart_file variational_distribution does not match current run." ) if 'optimization_method' in restart_data: restart_optimization_method = str(restart_data['optimization_method'].item()).strip().lower() if restart_optimization_method != optimization_method: raise ValueError("restart_file optimization_method does not match current run.") if 'max_mean_update_std' in restart_data: restart_limit = float(restart_data['max_mean_update_std']) restart_limit = None if np.isnan(restart_limit) else restart_limit if restart_limit != max_mean_update_std: raise ValueError("restart_file max_mean_update_std does not match current run.") if 'mfmc_control_variate_mode' in restart_data: restart_control_variate_mode = _normalize_mfmc_control_variate_mode( str(restart_data['mfmc_control_variate_mode'].item()) ) if restart_control_variate_mode != mfmc_control_variate_mode: raise ValueError("restart_file mfmc_control_variate_mode does not match current run.") restart_entropy_strategy = ( str(restart_data['score_function_entropy_strategy'].item()) if 'score_function_entropy_strategy' in restart_data else 'analytic' ) if restart_entropy_strategy != score_function_entropy_strategy: raise ValueError( "restart_file score_function_entropy_strategy does not match current run." ) if 'sampling_method' in restart_data: restart_sampling_method = _normalize_sampling_method( str(restart_data['sampling_method'].item()) ) if restart_sampling_method != sampling_method: raise ValueError("restart_file sampling_method does not match current run.") if 'prior_mean' in restart_data and not np.allclose(restart_data['prior_mean'], prior_mean): raise ValueError("restart_file prior_mean does not match current run.") if 'prior_covariance' in restart_data and not np.allclose( restart_data['prior_covariance'], prior_covariance, ): raise ValueError("restart_file prior_covariance does not match current run.") if 'elbo_scaling_factor' in restart_data: restart_elbo_scaling_factor = float(restart_data['elbo_scaling_factor']) if not np.isclose(restart_elbo_scaling_factor, elbo_scaling_factor): raise ValueError("restart_file elbo_scaling_factor does not match current run.") if 'elbo_relative_tolerance' in restart_data: restart_elbo_relative_tolerance = float(restart_data['elbo_relative_tolerance']) restart_tolerance_is_none = np.isnan(restart_elbo_relative_tolerance) current_tolerance_is_none = elbo_relative_tolerance is None if restart_tolerance_is_none != current_tolerance_is_none: raise ValueError("restart_file elbo_relative_tolerance does not match current run.") if ( not current_tolerance_is_none and not np.isclose(restart_elbo_relative_tolerance, elbo_relative_tolerance) ): raise ValueError("restart_file elbo_relative_tolerance does not match current run.") if variational_distribution == 'multivariate': if 'variational_correlation_cholesky' in restart_data: variational_correlation_cholesky = restart_data['variational_correlation_cholesky'] elif 'optimizer_samples' in restart_data: variational_correlation_cholesky = _compute_correlation_cholesky_from_samples( restart_data['optimizer_samples'] ) else: raise ValueError( "restart_file is missing variational_correlation_cholesky for multivariate VI." ) training_directory_key = ( 'training_directories' if 'training_directories' in restart_data else 'training_dirs' ) rom_training_directory_key = ( 'rom_training_directories' if 'rom_training_directories' in restart_data else 'rom_training_dirs' ) if training_directory_key not in restart_data or rom_training_directory_key not in restart_data: raise ValueError( "restart_file missing training_directories/rom_training_directories." ) if ( 'training_parameters' not in restart_data or 'training_qois' not in restart_data or 'rom_training_parameters' not in restart_data or 'rom_training_qois' not in restart_data ): raise ValueError( "restart_file missing training parameters or qois arrays." ) training_dirs = restart_data[training_directory_key].tolist() rom_training_dirs = restart_data[rom_training_directory_key].tolist() training_parameters = restart_data['training_parameters'] training_qois = restart_data['training_qois'] rom_training_parameters = restart_data['rom_training_parameters'] rom_training_qois = restart_data['rom_training_qois'] validate_mf_vi_restart(restart_data, rom_retraining_strategy, gradient_gain_estimation_strategy, max_rom_training_dirs, gain_num_folds, hessian_gain_strategy=hessian_gain_estimation_strategy, gain_sample_size=gain_sample_size, use_mfmc_control_variate=use_mfmc_control_variate, mfmc_fixed_gain=mfmc_fixed_gain) state = restore_mf_vi_state( restart_data, rom_model_builder, f'{absolute_work_dir}/iteration_{iteration}', dispatcher, ) if 'initial_elbo_reference' in restart_data: initial_elbo_reference = float(restart_data['initial_elbo_reference']) else: initial_elbo_reference = float(state['elbo']) if restart_file is None: state = stage_delayed_rom( state, rom_model_builder, f'{absolute_work_dir}/iteration_{iteration}', max_rom_training_dirs, dispatcher, ) running_hessian = None if optimization_method == 'newton': if restart_file is not None and 'newton_curvature_strategy' in restart_data: restart_strategy = _normalize_newton_curvature_strategy( str(restart_data['newton_curvature_strategy'].item()) ) if restart_strategy != newton_curvature_strategy: raise ValueError( "restart_file newton_curvature_strategy does not match current run." ) elif restart_file is not None and newton_curvature_strategy != 'same_sample': raise ValueError( "restart_file is missing state required by the selected Newton curvature strategy." ) if restart_file is not None and 'newton_hessian_num_samples' in restart_data: restart_count = int(restart_data['newton_hessian_num_samples']) restart_count = None if restart_count < 0 else restart_count if restart_count != newton_hessian_num_samples: raise ValueError( "restart_file newton_hessian_num_samples does not match current run." ) if restart_file is not None and 'newton_hessian_averaging_factor' in restart_data: if not np.isclose( float(restart_data['newton_hessian_averaging_factor']), newton_hessian_averaging_factor, ): raise ValueError( "restart_file newton_hessian_averaging_factor does not match current run." ) if newton_curvature_strategy == 'lagged': if restart_file is None: running_hessian = _get_state_hessian(state, newton_hessian_type) elif 'running_hessian' in restart_data: running_hessian = np.asarray(restart_data['running_hessian']).copy() else: raise ValueError("restart_file is missing the lagged running Hessian.") accepted_elbo_history = ( restart_data['accepted_elbo_history'].tolist() if restart_file is not None and 'accepted_elbo_history' in restart_data else [float(state['elbo'])] ) accepted_elbo_history, accepted_elbo_standard_error_history = _restore_mf_elbo_uncertainty_history( restart_data if restart_file is not None else {}, accepted_elbo_history, state, elbo_scaling_factor, require_history=(restart_file is not None and optimization_method != 'adam' and line_search_method == 'stochastic_nonmonotone'), ) current_newton_additive_regularization = _restore_adaptive_newton_regularization( restart_data if restart_file is not None else {}, restart_file is not None and optimization_method == 'newton', newton_additive_regularization, newton_adaptive_regularization, newton_regularization_increase_factor, newton_regularization_decrease_factor, newton_regularization_max_multiplier, growth_factor=newton_additive_regularization_growth_factor, completed_steps=iteration, maximum=newton_additive_regularization_max, ) scheduled_newton_base = _scheduled_newton_regularization( newton_additive_regularization, newton_additive_regularization_growth_factor, iteration, maximum=newton_additive_regularization_max, ) steepest_descent_solver = ( AdamSolver.from_config(resolved_optimizer_config) if optimization_method == 'adam' else SteepestDescentSolver() ) if optimization_method == 'adam' and restart_file is not None: if 'adam_gradient_method' not in restart_data: raise ValueError("restart_file is missing Adam gradient-method state.") restart_adam_gradient_method = str(restart_data['adam_gradient_method'].item()) if restart_adam_gradient_method != gradient_method: raise ValueError( "restart_file adam_gradient_method does not match current Adam config." ) steepest_descent_solver.load_restart_state_dict(restart_data) _save_mf_vi_restart( f'{absolute_work_dir}/iteration_{iteration}/restart.npz', state, variational_mean, variational_log_std, variational_distribution, prior_mean, prior_covariance, variational_correlation_cholesky, elbo_scaling_factor, elbo_relative_tolerance, initial_elbo_reference, iteration, step_size, bounded_parameter_handling, transform_map, optimization_method, mfmc_control_variate_mode, score_function_entropy_strategy, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, vi_history=vi_history, sampling_method=sampling_method, max_mean_update_std=max_mean_update_std, newton_curvature_strategy=newton_curvature_strategy, newton_hessian_num_samples=newton_hessian_num_samples, newton_hessian_averaging_factor=newton_hessian_averaging_factor, current_newton_additive_regularization=( current_newton_additive_regularization ), newton_additive_regularization_max=newton_additive_regularization_max, newton_additive_regularization_growth_factor=( newton_additive_regularization_growth_factor ), initial_newton_additive_regularization=( newton_additive_regularization ), newton_adaptive_regularization=newton_adaptive_regularization, newton_regularization_increase_factor=( newton_regularization_increase_factor ), newton_regularization_decrease_factor=( newton_regularization_decrease_factor ), newton_regularization_max_multiplier=( newton_regularization_max_multiplier ), running_hessian=running_hessian, accepted_elbo_history=accepted_elbo_history, accepted_elbo_standard_error_history=accepted_elbo_standard_error_history, adam_restart_data=( steepest_descent_solver.restart_state_dict() if optimization_method == 'adam' else None ), adam_gradient_method=(gradient_method if optimization_method == 'adam' else None), rom_substep_start_iteration=rom_substep_start_iteration, rom_substep_end_iteration=rom_substep_end_iteration, num_rom_substeps=num_rom_substeps, dispatcher=dispatcher, line_search_method=line_search_method, ) _prune_old_restart_files(absolute_work_dir, restart_files_to_keep, dispatcher) if optimization_method == 'adam': adam_learning_rate, gradient_norm = _compute_adam_diagnostics( steepest_descent_solver, state, variational_log_std, min_variational_std, max_variational_std, gradient_method, ) else: adam_learning_rate = None gradient_norm = _compute_gradient_norm(state, optimization_method) wall_time = time.time() - start_time cpu_time = time.process_time() - start_cpu_time if len(vi_history['cpu_time_seconds']) <= iteration: _append_vi_history( vi_history, variational_mean, variational_log_std, min_variational_std, max_variational_std, variational_correlation_cholesky, state['mean_relative_mse'], state['log_likelihoods_fom'], cpu_time, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, transform_map, newton_additive_regularization=( current_newton_additive_regularization if optimization_method == 'newton' else np.nan ), gradient_mean=state['gradient_mean'], gradient_log_std=state['gradient_log_std'], gradient_standard_error=state['gradient_standard_error'], mfmc_alpha_mean=state['mfmc_alpha_mean'], mfmc_alpha_log_std=state['mfmc_alpha_log_std'], ) alpha_mean_scalar = float(np.mean(state['mfmc_alpha_mean'])) alpha_log_scalar = float(np.mean(state['mfmc_alpha_log_std'])) optimizer_status = ( f'Adam learning rate: {adam_learning_rate:.5e}, ' f'Adam input gradient norm: {gradient_norm:.5f}' if optimization_method == 'adam' else f'Step size: {step_size:.5f}, Gradient norm: {gradient_norm:.5f}' ) print( f'Iteration: {iteration}, Relative MSE: {state["mean_relative_mse"]:.5f}, ' f'ELBO: {state["elbo"]:.5f}, ROM err: {state["rom_error"]:.5f}, ' f'alpha_mean: {alpha_mean_scalar:.5f}, alpha_logstd: {alpha_log_scalar:.5f}, ' f'{optimizer_status}, Wall time: {wall_time:.5f}' ) _print_gradient_signal_to_noise_ratio(state) _print_vi_parameters( variational_mean, variational_log_std, min_variational_std, max_variational_std, optimizer_samples=state['optimizer_samples'], parameter_samples=state['parameter_samples'], ) _write_iteration_stats_file( f'{absolute_work_dir}/iteration_{iteration}', variational_mean, variational_log_std, min_variational_std, max_variational_std, variational_correlation_cholesky, state['elbo'], state['log_likelihoods_fom'], state['log_priors_fom'], state['mean_relative_mse'], wall_time, cpu_time, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, transform_map, dispatcher=dispatcher, ) iteration += 1 step_failed_counter = 0 elbo_converged = False independent_hessian_cache = None while iteration < max_iterations and gradient_norm > gradient_norm_tolerance: iteration_rom_state = activate_delayed_rom(state) current_fom_sample_size = int(np.ceil( fom_sample_size * (line_search_sample_growth_factor ** step_failed_counter) )) current_fom_sample_size = max(current_fom_sample_size, 2) if rom_extra_sample_size > 0: current_rom_extra_sample_size = int(np.ceil( rom_extra_sample_size * (line_search_sample_growth_factor ** step_failed_counter) )) current_rom_extra_sample_size = max(current_rom_extra_sample_size, 1) else: current_rom_extra_sample_size = 0 newton_metric_scale = None curvature_hessian = None pending_running_hessian = running_hessian if optimization_method == 'newton': variational_std_for_metric, _ = _compute_variational_std( variational_log_std, min_variational_std, max_variational_std, ) newton_metric_scale = _compute_newton_metric_scale( newton_metric, variational_std_for_metric, ) if newton_curvature_strategy == 'independent': if independent_hessian_cache is None: hessian_fom_sample_size = ( fom_sample_size if newton_hessian_num_samples is None else newton_hessian_num_samples ) hessian_rom_extra_sample_size = int(round( rom_extra_sample_size * hessian_fom_sample_size / fom_sample_size )) if rom_extra_sample_size > 0: hessian_rom_extra_sample_size = max( hessian_rom_extra_sample_size, 1 ) hessian_state = evaluate_state( gain_sample_size=gain_sample_size, model=model, allow_rom_retraining=False, rom_model=iteration_rom_state['rom_model'], rom_model_builder=rom_model_builder, observations=observations, observations_covariance=observations_covariance, iteration_directory=( f'{absolute_work_dir}/iteration_{iteration}/hessian' ), parameter_names=parameter_names, variational_mean=variational_mean, variational_log_std=variational_log_std, prior_mean=prior_mean, prior_precision_operator=prior_precision_operator, prior_covariance_log_det=prior_covariance_log_det, fom_sample_size=hessian_fom_sample_size, rom_extra_sample_size=hessian_rom_extra_sample_size, fom_evaluation_concurrency=fom_evaluation_concurrency, rom_evaluation_concurrency=rom_evaluation_concurrency, covariance_regularization=covariance_regularization, baseline_method=baseline_method, use_mfmc_control_variate=use_mfmc_control_variate, mfmc_control_variate_mode=mfmc_control_variate_mode, variational_correlation_cholesky=variational_correlation_cholesky, elbo_scaling_factor=elbo_scaling_factor, gradient_method=gradient_method, bounded_parameter_handling=bounded_parameter_handling, min_variational_std=min_variational_std, max_variational_std=max_variational_std, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, transform_map=transform_map, rom_tolerance=rom_tolerance, max_rom_training_dirs=max_rom_training_dirs, rom_retraining_strategy=rom_retraining_strategy, gradient_gain_estimation_strategy=('same_sample' if gradient_gain_estimation_strategy == 'independent' else gradient_gain_estimation_strategy), hessian_gain_estimation_strategy=hessian_gain_estimation_strategy, gain_num_folds=gain_num_folds, gain_history_state=state, training_dirs=[], training_parameters=None, training_qois=None, rom_training_dirs=iteration_rom_state['rom_training_dirs'], rom_training_parameters=iteration_rom_state['rom_training_parameters'], rom_training_qois=iteration_rom_state['rom_training_qois'], log_likelihood_precision_operator=log_likelihood_precision_operator, sampling_method=sampling_method, dispatcher=dispatcher, score_function_entropy_strategy=score_function_entropy_strategy, mfmc_fixed_gain=mfmc_fixed_gain, ) independent_hessian_cache = _get_state_hessian( hessian_state, newton_hessian_type ) curvature_hessian = independent_hessian_cache elif newton_curvature_strategy == 'lagged': curvature_hessian = running_hessian pending_running_hessian = _average_hessians( running_hessian, _get_state_hessian(state, newton_hessian_type), newton_hessian_averaging_factor, ) line_search_predicted_slope = 0.0 if optimization_method in ('gradient', 'adam'): if optimization_method == 'adam': gradient = np.concatenate([state['gradient_mean'], state['gradient_log_std']]) fisher_diagonal = _compute_adam_fisher_diagonal( variational_log_std, min_variational_std, max_variational_std, gradient_method, ) step = steepest_descent_solver.step( gradient, fisher_diagonal=fisher_diagonal ) else: gradient = np.concatenate([ state['update_direction_mean'], state['update_direction_log_std'] ]) step = steepest_descent_solver.step(gradient) dimensionality = state['update_direction_mean'].size direction_mean = step[:dimensionality] direction_log_std = step[dimensionality:] line_search_predicted_slope = float( np.dot(state['gradient_mean'], direction_mean) + np.dot(state['gradient_log_std'], direction_log_std) ) test_variational_mean = variational_mean + step_size * direction_mean log_std_update = np.clip( step_size * direction_log_std, -max_log_std_update, max_log_std_update, ) test_variational_log_std = variational_log_std + log_std_update test_variational_log_std = _clip_variational_log_std( test_variational_log_std, min_variational_std, max_variational_std, ) test_variational_log_std = _enforce_variational_log_std_bounds( test_variational_mean, test_variational_log_std, min_variational_std, max_variational_std, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, min_physical_variational_std_fraction, transform_map, ) else: direction_mean, direction_log_std = _compute_newton_step( state, newton_regularization, newton_regularization_strategy=newton_regularization_strategy, newton_regularization_epsilon=newton_regularization_epsilon, newton_fallback_learning_rate=newton_fallback_learning_rate, newton_additive_regularization=( current_newton_additive_regularization ), newton_hessian_type=newton_hessian_type, metric_scale=newton_metric_scale, hessian=curvature_hessian, ) if line_search_method == 'none': direction_log_std = ( resolved_line_search_config.log_std_learning_rate_factor * direction_log_std ) mean_update = _limit_mean_update( direction_mean, step_size, variational_std_for_metric, max_mean_update_std, ) test_variational_mean = variational_mean + mean_update log_std_update = np.clip( step_size * direction_log_std, -max_log_std_update, max_log_std_update, ) test_variational_log_std = variational_log_std + log_std_update test_variational_log_std = _clip_variational_log_std( test_variational_log_std, min_variational_std, max_variational_std, ) test_variational_log_std = _enforce_variational_log_std_bounds( test_variational_mean, test_variational_log_std, min_variational_std, max_variational_std, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, min_physical_variational_std_fraction, transform_map, ) if max_mean_update_std is not None: line_search_predicted_slope = float( ( np.dot(state['gradient_mean'], mean_update) + np.dot( state['gradient_log_std'], test_variational_log_std - variational_log_std, ) ) / step_size ) else: line_search_predicted_slope = float( np.dot(state['gradient_mean'], direction_mean) + np.dot(state['gradient_log_std'], direction_log_std) ) if rom_substeps_enabled( iteration - 1, rom_substep_start_iteration, rom_substep_end_iteration, num_rom_substeps, ): test_variational_mean, test_variational_log_std = ( apply_diagonal_rom_substeps( rom_model=iteration_rom_state['rom_model'], candidate_mean=test_variational_mean, candidate_log_std=test_variational_log_std, outer_iteration=iteration - 1, num_rom_substeps=num_rom_substeps, step_size=step_size, outer_method=optimization_method, optimizer_config=resolved_optimizer_config, max_mean_update_std=max_mean_update_std, max_log_std_update=max_log_std_update, min_variational_std=min_variational_std, max_variational_std=max_variational_std, observations=observations, observations_covariance=observations_covariance, parameter_names=parameter_names, prior_mean=prior_mean, prior_precision_operator=prior_precision_operator, prior_covariance_log_det=prior_covariance_log_det, sample_size=max(current_fom_sample_size, current_rom_extra_sample_size), evaluation_concurrency=rom_evaluation_concurrency, covariance_regularization=covariance_regularization, baseline_method=baseline_method, bounded_parameter_handling=bounded_parameter_handling, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, transform_map=transform_map, min_physical_variational_std_fraction=min_physical_variational_std_fraction, variational_correlation_cholesky=variational_correlation_cholesky, elbo_scaling_factor=elbo_scaling_factor, log_likelihood_precision_operator=log_likelihood_precision_operator, sampling_method=sampling_method, score_function_entropy_strategy=score_function_entropy_strategy, directory=f'{absolute_work_dir}/iteration_{iteration}', dispatcher=resolve_local_dispatcher(dispatcher), ) ) # The line search must assess the entire proposed outer + ROM step. line_search_predicted_slope = float( np.dot(state['gradient_mean'], (test_variational_mean - variational_mean) / step_size) + np.dot(state['gradient_log_std'], (test_variational_log_std - variational_log_std) / step_size) ) test_state = evaluate_state( gain_sample_size=gain_sample_size, model=model, rom_model=iteration_rom_state['rom_model'], rom_model_builder=rom_model_builder, observations=observations, observations_covariance=observations_covariance, iteration_directory=f'{absolute_work_dir}/iteration_{iteration}', parameter_names=parameter_names, variational_mean=test_variational_mean, variational_log_std=test_variational_log_std, prior_mean=prior_mean, prior_precision_operator=prior_precision_operator, prior_covariance_log_det=prior_covariance_log_det, fom_sample_size=current_fom_sample_size, rom_extra_sample_size=current_rom_extra_sample_size, fom_evaluation_concurrency=fom_evaluation_concurrency, rom_evaluation_concurrency=rom_evaluation_concurrency, covariance_regularization=covariance_regularization, baseline_method=baseline_method, use_mfmc_control_variate=use_mfmc_control_variate, mfmc_control_variate_mode=mfmc_control_variate_mode, variational_correlation_cholesky=variational_correlation_cholesky, elbo_scaling_factor=elbo_scaling_factor, gradient_method=gradient_method, bounded_parameter_handling=bounded_parameter_handling, min_variational_std=min_variational_std, max_variational_std=max_variational_std, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, transform_map=transform_map, rom_tolerance=rom_tolerance, max_rom_training_dirs=max_rom_training_dirs, rom_retraining_strategy=rom_retraining_strategy, gradient_gain_estimation_strategy=gradient_gain_estimation_strategy, hessian_gain_estimation_strategy=hessian_gain_estimation_strategy, gain_num_folds=gain_num_folds, gain_history_state=state, training_dirs=state['training_dirs'], training_parameters=state['training_parameters'], training_qois=state['training_qois'], rom_training_dirs=iteration_rom_state['rom_training_dirs'], rom_training_parameters=iteration_rom_state['rom_training_parameters'], rom_training_qois=iteration_rom_state['rom_training_qois'], log_likelihood_precision_operator=log_likelihood_precision_operator, sampling_method=sampling_method, dispatcher=dispatcher, score_function_entropy_strategy=score_function_entropy_strategy, mfmc_fixed_gain=mfmc_fixed_gain, ) if optimization_method == 'adam' or line_search_method == 'none': accept_step = True elif line_search_method == 'legacy': allowable_elbo_drop = (relaxation_parameter - 1.0) * abs(state['elbo']) accept_step = test_state['elbo'] >= state['elbo'] - allowable_elbo_drop else: reference_elbo, reference_standard_error = _select_mf_elbo_reference( accepted_elbo_history, accepted_elbo_standard_error_history, line_search_nonmonotone_window, ) nonnegative_predicted_slope = max(line_search_predicted_slope, 0.0) armijo_target = ( reference_elbo + line_search_armijo_coefficient * step_size * nonnegative_predicted_slope ) test_standard_error = _compute_state_elbo_standard_error(test_state, elbo_scaling_factor) delta_standard_error = np.sqrt( reference_standard_error ** 2 + test_standard_error ** 2 ) armijo_target -= line_search_uncertainty_sigma * delta_standard_error accept_step = test_state['elbo'] >= armijo_target trial_newton_additive_regularization = ( current_newton_additive_regularization if optimization_method == 'newton' else np.nan ) if accept_step: step_failed_counter = 0 variational_mean = test_variational_mean*1.0 variational_log_std = test_variational_log_std*1.0 state = stage_delayed_rom( test_state, rom_model_builder, f'{absolute_work_dir}/iteration_{iteration}', max_rom_training_dirs, dispatcher, ) if newton_curvature_strategy == 'lagged': running_hessian = pending_running_hessian independent_hessian_cache = None accepted_elbo_history.append(state['elbo']) accepted_elbo_standard_error_history.append( _compute_state_elbo_standard_error(state, elbo_scaling_factor) ) relative_elbo_improvement = ( float(state['elbo']) / (initial_elbo_reference + 1e-16) ) if ( elbo_relative_tolerance is not None and relative_elbo_improvement <= elbo_relative_tolerance ): elbo_converged = True accepted_step_size = step_size step_size = min(initial_step_size, max_step_size) scheduled_newton_base = _scheduled_newton_regularization( newton_additive_regularization, newton_additive_regularization_growth_factor, iteration, maximum=newton_additive_regularization_max, ) current_newton_additive_regularization = scheduled_newton_base if optimization_method == 'adam': adam_learning_rate, gradient_norm = _compute_adam_diagnostics( steepest_descent_solver, state, variational_log_std, min_variational_std, max_variational_std, gradient_method, ) else: gradient_norm = _compute_gradient_norm(state, optimization_method) wall_time = time.time() - start_time cpu_time = time.process_time() - start_cpu_time _append_vi_history( vi_history, variational_mean, variational_log_std, min_variational_std, max_variational_std, variational_correlation_cholesky, state['mean_relative_mse'], state['log_likelihoods_fom'], cpu_time, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, transform_map, accepted_step_size=accepted_step_size, newton_additive_regularization=( trial_newton_additive_regularization ), gradient_mean=state['gradient_mean'], gradient_log_std=state['gradient_log_std'], gradient_standard_error=state['gradient_standard_error'], mfmc_alpha_mean=state['mfmc_alpha_mean'], mfmc_alpha_log_std=state['mfmc_alpha_log_std'], ) alpha_mean_scalar = float(np.mean(state['mfmc_alpha_mean'])) alpha_log_scalar = float(np.mean(state['mfmc_alpha_log_std'])) optimizer_status = ( f'Adam learning rate: {adam_learning_rate:.5e}, ' f'Adam input gradient norm: {gradient_norm:.5f}' if optimization_method == 'adam' else f'Step size: {accepted_step_size:.5e}, Gradient norm: {gradient_norm:.5f}' ) print( f'Iteration: {iteration}, Relative MSE: {state["mean_relative_mse"]:.5f}, ELBO: {state["elbo"]:.5f}, ' f'Relative ELBO (initial ref): {relative_elbo_improvement:.5e}, ' f'ROM err: {state["rom_error"]:.5f}, alpha_mean: {alpha_mean_scalar:.5f}, ' f'alpha_logstd: {alpha_log_scalar:.5f}, {optimizer_status}, ' f'Newton additive regularization: ' f'{trial_newton_additive_regularization:.5e}, ' f'Wall time: {wall_time:.5f}' ) _print_gradient_signal_to_noise_ratio(state) _print_vi_parameters( variational_mean, variational_log_std, min_variational_std, max_variational_std, optimizer_samples=state['optimizer_samples'], parameter_samples=state['parameter_samples'], ) _write_iteration_stats_file( f'{absolute_work_dir}/iteration_{iteration}', variational_mean, variational_log_std, min_variational_std, max_variational_std, variational_correlation_cholesky, state['elbo'], state['log_likelihoods_fom'], state['log_priors_fom'], state['mean_relative_mse'], wall_time, cpu_time, bounded_parameter_handling, parameter_mins, parameter_maxes, transform_interior_margin, transform_map, dispatcher=dispatcher, ) _save_mf_vi_restart( f'{absolute_work_dir}/iteration_{iteration}/restart.npz', state, variational_mean, variational_log_std, variational_distribution, prior_mean, prior_covariance, variational_correlation_cholesky, elbo_scaling_factor, elbo_relative_tolerance, initial_elbo_reference, iteration, step_size, bounded_parameter_handling, transform_map, optimization_method, mfmc_control_variate_mode, score_function_entropy_strategy, parameter_mins=parameter_mins, parameter_maxes=parameter_maxes, transform_interior_margin=transform_interior_margin, vi_history=vi_history, sampling_method=sampling_method, max_mean_update_std=max_mean_update_std, newton_curvature_strategy=newton_curvature_strategy, newton_hessian_num_samples=newton_hessian_num_samples, newton_hessian_averaging_factor=newton_hessian_averaging_factor, current_newton_additive_regularization=( current_newton_additive_regularization ), newton_additive_regularization_max=newton_additive_regularization_max, newton_additive_regularization_growth_factor=( newton_additive_regularization_growth_factor ), initial_newton_additive_regularization=( newton_additive_regularization ), newton_adaptive_regularization=newton_adaptive_regularization, newton_regularization_increase_factor=( newton_regularization_increase_factor ), newton_regularization_decrease_factor=( newton_regularization_decrease_factor ), newton_regularization_max_multiplier=( newton_regularization_max_multiplier ), running_hessian=running_hessian, accepted_elbo_history=accepted_elbo_history, accepted_elbo_standard_error_history=accepted_elbo_standard_error_history, adam_restart_data=( steepest_descent_solver.restart_state_dict() if optimization_method == 'adam' else None ), adam_gradient_method=( gradient_method if optimization_method == 'adam' else None ), rom_substep_start_iteration=rom_substep_start_iteration, rom_substep_end_iteration=rom_substep_end_iteration, num_rom_substeps=num_rom_substeps, dispatcher=dispatcher, line_search_method=line_search_method, ) _prune_old_restart_files(absolute_work_dir, restart_files_to_keep, dispatcher) iteration += 1 if elbo_converged: print( "ELBO relative-improvement tolerance reached " f"({relative_elbo_improvement:.5e} <= {elbo_relative_tolerance:.5e}), terminating" ) break else: step_failed_counter += 1 if optimization_method == 'newton' and newton_adaptive_regularization: step_size, current_newton_additive_regularization = ( _backtrack_adaptive_newton_controls( step_size, current_newton_additive_regularization, scheduled_newton_base, step_size_decay_factor, newton_regularization_increase_factor, newton_regularization_max_multiplier, maximum=newton_additive_regularization_max, ) ) else: step_size /= step_size_decay_factor print( f' Warning, rejecting step, Iteration: {iteration}, ' f'Relative MSE: {state["mean_relative_mse"]:.5f}, ' f'ELBO: {state["elbo"]:.5f}, Step size: {step_size:.5e}, ' f'Newton additive regularization: ' f'{current_newton_additive_regularization:.5e}, ' f'Gradient norm: {gradient_norm:.5f}' ) _print_vi_parameters( variational_mean, variational_log_std, min_variational_std, max_variational_std, optimizer_samples=state['optimizer_samples'], parameter_samples=state['parameter_samples'], ) if step_failed_counter > max_step_size_decrease_trys: print(f' Failed to advance after {max_step_size_decrease_trys}, exiting') break if iteration >= max_iterations: print('Max iterations reached, terminating') elif elbo_converged: print('ELBO relative-improvement tolerance reached!') elif gradient_norm <= gradient_norm_tolerance: print('Gradient norm dropped below tolerance!') variational_std, _ = _compute_variational_std( variational_log_std, min_variational_std, max_variational_std, ) _save_vi_history(absolute_work_dir, vi_history, dispatcher) return variational_mean, variational_std, state['parameter_samples_fom'], state['qois_fom']