romtools.workflows.inverse.vi.drivers#
Variational inference drivers for Gaussian posterior approximations.
This module provides derivative-free variational inference (VI) routines for black-box forward models. An approximate posterior is represented by a Gaussian variational family, and the optimizer updates the variational parameters to maximize the evidence lower bound (ELBO).
Theory
run_vi solves a Gaussian variational inference problem by maximizing
where \(q(\theta;\zeta)\) is the variational search distribution and \(\zeta\) denotes its parameters. In this implementation, the variational family is Gaussian in either diagonal form or fixed-correlation multivariate form, with the optimizer state stored as the variational mean and log standard deviation.
For black-box forward models, the code uses the score-function (REINFORCE/log-likelihood-trick) estimator instead of reparameterization gradients through the PDE model:
with
The expectation is approximated with Monte Carlo or randomized quasi-Monte Carlo samples from the current variational distribution. Because only \(\nabla_{\zeta}\log q\) is needed, the forward model itself is treated as derivative-free.
When optimizer_method="adam", the selected score gradient is passed to a
stateful Adam ascent update. By default, the raw score gradient is
preconditioned with the damped mean-field Gaussian Fisher matrix before Adam,
matching the ABRIS setup; the default initial learning rate is \(0.1/d\),
where \(d\) is the parameter dimension.
When optimizer_method="newton", the routine also forms a second-order
score-function estimator for curvature:
This is the curvature model used by the Newton update path. The implementation
supports a metric rescaling via newton_metric and either diagonal or full
projected Hessian solves via newton_hessian_type. The
newton_regularization_strategy option selects a fixed eigenvalue tolerance, a
tolerance proportional to the Hessian spectral norm, or "per_parameter"
direction-wise damping. All strategies form curvature from \(-H\) and replace eigenvalues strictly
below the tolerance with the reciprocal of newton_fallback_learning_rate
(default 0.01). Eigenvalues at or above the tolerance are retained.
newton_regularization controls that tolerance. Before damping and line-search
scaling, replaced directions take gradient steps with this learning rate. The separate
newton_additive_regularization adds \(\lambda I\) for the "absolute"
and "hessian_norm" strategies, and adds
\(\lambda\,\mathrm{diag}(|H_{ii}|+\epsilon)\) for "per_parameter", where
\(\epsilon\) is newton_regularization_epsilon. For the natural metric,
regularization is evaluated after metric rescaling. The
newton_curvature_strategy option controls stochastic coupling: the default
"same_sample" reuses the gradient samples, "independent" evaluates a
separate batch (whose size is set by newton_hessian_num_samples), and
"lagged" preconditions with the previous exponentially averaged Hessian.
The lagged averaging weight is set by newton_hessian_averaging_factor.
When newton_adaptive_regularization is enabled, a rejected step decreases
the next step size and increases additive regularization by
newton_regularization_increase_factor within that iteration. After any
accepted step, the next outer iteration starts at the configured initial step
size and scheduled base additive regularization, including after an accepted ELBO drop.
The base grows by newton_additive_regularization_growth_factor (default 1.0)
after each acceptance, starting at newton_additive_regularization for the
first step. Growth is supported for mean-field VI/MF-VI with or without adaptive
retry regularization. Rejections do not advance the schedule. Retry damping is
bounded by the scheduled base and newton_regularization_max_multiplier
times that base.
Variance Reduction
score_function_entropy_strategy="analytic" (the default) estimates the
log-joint score contribution and adds the Gaussian entropy gradient exactly.
The "joint" strategy instead keeps \(-\log q\) inside the sampled ELBO
integrand. The analytic strategy can have lower variance far from the optimum;
with a suitable baseline, the joint strategy has zero per-sample contribution
when the posterior belongs to the variational family. Both choices are
score-function estimators, not pathwise estimators.
The gradient estimator optionally supports a baseline through
baseline_method. In particular, the leave-one-out option subtracts a
sample mean baseline that is independent of the current score term,
preserving unbiasedness while reducing Monte Carlo variance:
where \(b^{(-i)}\) is the mean ELBO over all samples except \(\theta^{(i)}\).
Gaussian Structure
For Gaussian priors and Gaussian variational families, the ELBO integrand decomposes into
so the forward-model dependence enters through the log-likelihood term, while the prior and variational-density terms are handled analytically. This is why the routine can remain derivative-free with respect to the forward model while still using gradient- and Hessian-based updates in the variational parameters.
Functions
|
Run Gaussian variational inference with score-function gradients. |
- romtools.workflows.inverse.vi.drivers.run_vi(model, prior_parameter_space, observations, observations_covariance, parameter_mins=None, parameter_maxes=None, initial_variational_parameter_space=None, restart_file=None, optimizer_method='gradient', optimizer_config=None, line_search_method='stochastic_nonmonotone', line_search_config=None, absolute_work_dir=None, sample_size=30, random_seed=1, sampling_method='mc', evaluation_concurrency=1, covariance_regularization=1e-08, restart_files_to_keep=10, elbo_scaling_factor='diag_mean', elbo_relative_tolerance=None, baseline_method=None, bounded_parameter_handling='transform', transform_interior_margin=1e-06, transform_map='sigmoid', min_physical_variational_std_fraction=1e-06, dispatcher=None, *, absolute_vi_directory=None, score_function_entropy_strategy='analytic', _reuse_controller=None)[source]#
Run Gaussian variational inference with score-function gradients.
This routine approximates the posterior with a Gaussian variational family (diagonal or fixed-correlation multivariate) and updates its mean and log-standard deviation using REINFORCE. An optional baseline can be enabled to reduce gradient estimator variance.
- Parameters:
model (QoiModel) – QoiModel to evaluate at sampled parameters.
prior_parameter_space – Either GaussianParameterSpace (diagonal VI) or MultivariateGaussianParameterSpace (multivariate VI). Defines the Bayesian prior in physical parameter space.
observations (ndarray) – Observed QoI vector.
observations_covariance (ndarray) – Observation covariance matrix.
parameter_mins (ndarray) – Optional lower bounds on parameters.
parameter_maxes (ndarray) – Optional upper bounds on parameters.
initial_variational_parameter_space – Required Gaussian initializer for the variational state in physical parameter space.
restart_file (str) – Optional restart file path. Restart files written by this routine store variational_mean in physical coordinates.
optimizer_method (str) – 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 (str) – 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 optionallyline_search_config=VINoLineSearchConfig(step_size=0.5).absolute_work_dir (str) – Absolute path to the working directory for runs.
sample_size (int) – Number of MC samples per iteration.
random_seed (int) – RNG seed for reproducibility.
sampling_method (str) – Sampling method for variational draws. Supported options are ‘mc’ and ‘rqmc’.
evaluation_concurrency – Concurrent model evaluations per iteration.
covariance_regularization (float) – Diagonal regularization for covariance inversion.
restart_files_to_keep (int) – Number of most-recent restart files to retain under absolute_work_dir. Older restart files are removed.
elbo_scaling_factor – Positive scalar that multiplies the ELBO objective, or a string mode. Supported string modes are: ‘initial_expected_misfit’: reciprocal of max(1, initial HF mean noise-weighted half squared residual), fixed thereafter and on restart. The initial HF batch is reused; no extra model evaluations are needed. ‘diag_mean’ (or ‘auto’): mean(diag(observations_covariance)), ‘diag_trace’: sum(diag(observations_covariance)).
elbo_relative_tolerance (float) – Optional non-negative relative tolerance for ELBO improvement relative to the initial ELBO at the initial variational guess. When set, VI stops when elbo_current / (elbo_initial + 1e-16) is less than or equal to this tolerance.
baseline_method (str) – Baseline used in REINFORCE gradient estimation. Supported options are ‘none’, ‘loo’, and ‘optimal’.
score_function_entropy_strategy (str) – Entropy treatment in the score-function gradient.
'analytic'retains the analytic Gaussian entropy gradient;'joint'estimates the fulllog_joint - log_qintegrand. The joint strategy is not a pathwise estimator.bounded_parameter_handling (str) – Parameter bounds handling. Supported options are ‘clip’ and ‘transform’.
transform_interior_margin (float) – Margin used by bounded_parameter_handling=’transform’ to keep mapped samples away from exact bounds.
transform_map (str) – Transform used by bounded_parameter_handling=’transform’. Supported options are ‘sigmoid’ and ‘arctan’.
min_physical_variational_std_fraction (float) – Minimum physical-space variational standard deviation as a fraction of each parameter range when bounded_parameter_handling=’transform’.
dispatcher (BaseDispatcher | None) – Optional (defaults to None, which instantiates a LocalDispatcher). Pass a RemoteDispatcher to send model evaluations to the configured remote host (e.g. an HPC cluster).
absolute_vi_directory (str)
- Returns:
Tuple of (variational_mean, variational_std, parameter_samples, qois).