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

"""Cross-fitted ACV gains from cached score/weight moments."""

from .common import (
    _compute_variational_log_densities, _normalize_mfmc_control_variate_mode,
    _normalize_baseline_method,
)

import numpy as np
from scipy.special import logsumexp


def normalize_strategy(value, name, choices):
    value = value.strip().lower()
    if value not in choices:
        raise ValueError(f"Unsupported {name} '{value}'. Supported options are {choices}.")
    return value


def validate_gain_sampling(gain_strategy, sampling_method):
    if gain_strategy in ('loo', 'k_fold', 'history', 'independent') and sampling_method != 'mc':
        raise ValueError(f"{gain_strategy.upper()} gain estimation requires sampling_method='mc' with independent paired samples.")


[docs] def regularized_matrix_gain(variance, cross, epsilon=1e-12, max_rank=None, noise_floor=0.0): """Solve the ridge fit on the covariance range, excluding numerical nulls.""" variance = 0.5*(variance + variance.T) values, vectors = np.linalg.eigh(variance) if values[-1] <= epsilon: return np.zeros_like(cross) cutoff = max(noise_floor, np.finfo(float).eps*variance.shape[0]*max(float(values[-1]), 0.0)) keep = values > cutoff if max_rank is not None and max_rank < variance.shape[0]: keep[:variance.shape[0]-max_rank] = False if not np.any(keep): return np.zeros_like(cross) basis = vectors[:, keep] return basis @ ((basis.T @ cross)/(values[keep, None] + epsilon))
class _FoldMoments: """Stable prefix/suffix scatter merges, without subtracting the held-out row.""" def __init__(self, dimension, matrix): self.count = 0 self.means = {key: np.zeros(dimension) for key in ('h', 'l', 'd', 's')} self.pairs = ('ll', 'ld', 'ls', 'ds', 'ss', 'hh', 'hs') self.matrix_pairs = set(self.pairs[:5]) if matrix else set() self.scatter = {pair: np.zeros((dimension, dimension) if pair in self.matrix_pairs else dimension) for pair in self.pairs} def copy(self): result = _FoldMoments(self.means['s'].size, bool(self.matrix_pairs)) result.count = self.count result.means = {key: value.copy() for key, value in self.means.items()} result.scatter = {key: value.copy() for key, value in self.scatter.items()} return result def add(self, values): count = self.count + 1 delta = {key: values[key] - self.means[key] for key in self.means} for pair in self.pairs: left, right = (delta[key] for key in pair) product = np.outer(left, right) if pair in self.matrix_pairs else left*right self.scatter[pair] += (self.count/count)*product for key in self.means: self.means[key] += delta[key]/count self.count = count def covariance_with(self, other): count = self.count + other.count factor = self.count*other.count/count delta = {key: other.means[key] - self.means[key] for key in self.means} result = {} for pair in self.pairs: left, right = (delta[key] for key in pair) product = np.outer(left, right) if pair in self.matrix_pairs else left*right result[pair] = (self.scatter[pair] + other.scatter[pair] + factor*product)/count return result def _exclusive_sums(values): """Sum rows strictly before/after each row, avoiding total-minus-row cancellation.""" zero = np.zeros_like(values[:1]) before = np.concatenate((zero, np.cumsum(values[:-1], axis=0)), axis=0) after = np.concatenate((np.cumsum(values[:0:-1], axis=0)[::-1], zero), axis=0) return before + after def validate_gain_num_folds(value): if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)) or value < 2: raise ValueError('gain_num_folds must be an integer greater than or equal to two.') return int(value)
[docs] def gain_folds(n, num_folds=None): """Balanced, value-independent folds; None selects singleton LOO folds.""" count = n if num_folds is None else min(validate_gain_num_folds(num_folds), n) return np.array_split(np.arange(n), count)
[docs] def k_fold_acv_estimator(*args, gain_num_folds=5, **kwargs): """Fit gains on complementary paired folds, with inner LOO baselines.""" return loo_acv_estimator(*args, num_folds=validate_gain_num_folds(gain_num_folds), **kwargs)
[docs] def loo_acv_estimator(high_weights, low_weights, extra_weights, scores, extra_scores, baseline_method, mode, *, force_unit_gain=False, high_reference_terms=None, epsilon=1e-12, gain_regularization=1.0, return_baselines=False, fixed_gain=None, num_folds=None): """Cross-fit stable ACV gains with a fold-only extreme-coefficient guard. ``num_folds=None`` uses singleton LOO folds; otherwise use balanced contiguous k-fold partitions. Prefix/suffix covariance merges exclude the held-out fold without unstable scatter downdates. Weight offsets are removed before multiplication by scores. The fold containing the reference row is computed separately with a reference from its own fitting set. Moment work remains O(n*p**2); matrix solves are performed once per fold. Ordinary gains are not shrunk toward a preset coefficient. To guard against tiny fitting variances, positive ``gain_regularization`` limits scalar/componentwise magnitudes and matrix spectral norms to ``1 + sqrt(training_count/gain_regularization)/2``. The limit grows with sample count; zero disables it. All coefficient decisions exclude the held-out fold and LF-only samples. Matrix coefficients use delta_L @ A. """ mode = normalize_strategy(mode, 'mfmc_control_variate_mode', ('scalar', 'componentwise', 'matrix')) baseline_method = normalize_strategy(baseline_method, 'baseline_method', ('none', 'loo', 'optimal')) if not np.isfinite(gain_regularization) or gain_regularization < 0: raise ValueError('gain_regularization must be finite and non-negative.') high_weights = np.asarray(high_weights, dtype=float) low_weights = np.asarray(low_weights, dtype=float) extra_weights = np.asarray(extra_weights, dtype=float) scores = np.asarray(scores, dtype=float) n, m = high_weights.size, extra_weights.size if n < 1 or high_weights.ndim != 1 or low_weights.shape != high_weights.shape: raise ValueError('Cross-fitting requires a nonempty paired HF/LF sample set.') shape = scores.shape[1:] p = int(np.prod(shape)) s = scores.reshape(n, p) matrix = mode == 'matrix' folds = gain_folds(n, num_folds) ratio = m/(n+m) gain_shape = () if mode == 'scalar' else ((p, p) if matrix else shape) gains = np.zeros((n,) + gain_shape) corrected = np.empty((n, p)) if return_baselines: outer_high_baselines = np.zeros((n, p)) outer_low_baselines = np.zeros((n, p)) def prepare(reference): # These references belong to every fitting set that uses this cache. rh = high_weights[reference] if baseline_method != 'none' and n > 1 else 0.0 rl = low_weights[reference] if baseline_method != 'none' and n > 1 else 0.0 wh, wl = high_weights-rh, low_weights-rl wd = wh-wl if baseline_method != 'none' else high_weights-low_weights basis = {'h': wh[:, None]*s, 'l': wl[:, None]*s, 'd': wd[:, None]*s, 's': s} return rh, rl, wh, wl, basis rh, rl, wh, wl, basis = prepare(0) needs_fit = bool(m and fixed_gain is None and not force_unit_gain and any(n-len(fold) >= 2 for fold in folds)) if needs_fit: prefixes = [] accumulator = _FoldMoments(p, matrix) for indices in folds: prefixes.append(accumulator.copy()) for j in indices: accumulator.add({key: value[j] for key, value in basis.items()}) suffix = _FoldMoments(p, matrix) def exclude_folds(values): return _exclusive_sums(np.asarray([values[indices].sum(axis=0) for indices in folds])) def baseline_sums(wh, wl): if baseline_method == 'loo': return exclude_folds(wh), exclude_folds(wl) if baseline_method == 'optimal': return (exclude_folds(wh[:, None]*s**2), exclude_folds(wl[:, None]*s**2), exclude_folds(s**2)) return None sums = baseline_sums(wh, wl) ref_squares = (None if high_reference_terms is None else np.asarray(high_reference_terms).reshape(n, p)**2) reference_sums = None if ref_squares is None else exclude_folds(ref_squares) if m: extra_s = np.asarray(extra_scores).reshape(m, p) # Extra-sample reference affects the correction only, never the gain. extra_reference = extra_weights[0] extra_centered_mean = ((extra_weights-extra_reference)[:, None]*extra_s).mean(axis=0) extra_score_mean = extra_s.mean(axis=0) for i in range(len(folds)-1, -1, -1): indices = folds[i] k = n-len(indices) gain_limit = (1 + np.sqrt(k/gain_regularization)/2 if gain_regularization > 0 else np.inf) fold_rh, fold_rl, fold_wh, fold_wl = rh, rl, wh, wl fold_sums = sums covariance = prefixes[i].covariance_with(suffix) if needs_fit else None if i == 0 and k and baseline_method != 'none': # Reference row 0 is held out: neither it nor its large offset may # influence this fold's arithmetic or coefficient decisions. fold_rh, fold_rl, fold_wh, fold_wl, fold_basis = prepare(int(folds[0][-1])+1) if needs_fit: fold = _FoldMoments(p, matrix) for j in range(int(folds[0][-1])+1, n): fold.add({key: value[j] for key, value in fold_basis.items()}) covariance = {key: value/k for key, value in fold.scatter.items()} fold_sums = baseline_sums(fold_wh, fold_wl) held_h = held_l = np.zeros(p) a = 1.0 if k and baseline_method == 'loo': held_h = np.full(p, fold_sums[0][i]/k) held_l = np.full(p, fold_sums[1][i]/k) if k > 1: # Within the fitting fold, leave-j-out terms satisfy # (w_j - mean_{T minus j})*s_j = k/(k-1)*(w_j-mean_T)*s_j. # Exclude the entire outer fold, then the inner row. a = k/(k-1) elif k and baseline_method == 'optimal': numerator_h, numerator_l, denominator = (value[i] for value in fold_sums) held_h = np.divide(numerator_h, denominator, out=np.full(p, -fold_rh), where=denominator > epsilon) held_l = np.divide(numerator_l, denominator, out=np.full(p, -fold_rl), where=denominator > epsilon) fit_h, fit_l = a*held_h, a*held_l fit_d = fit_h-fit_l if return_baselines: outer_high_baselines[indices] = fold_rh+held_h outer_low_baselines[indices] = fold_rl+held_l if m and force_unit_gain: gain = np.eye(p) if matrix else np.ones(gain_shape) elif m and fixed_gain is not None: gain = np.asarray(fixed_gain).reshape(gain_shape) elif m and k >= 2: ll, ld, ls, ds, ss = (covariance[key] for key in ('ll', 'ld', 'ls', 'ds', 'ss')) ls_diag = np.diag(ls) if matrix else ls ds_diag = np.diag(ds) if matrix else ds ss_diag = np.diag(ss) if matrix else ss high_variance = np.maximum(a*a*covariance['hh'] - 2*a*fit_h*covariance['hs'] + fit_h**2*ss_diag, 0.0) if matrix: variance = (a*a*ll - a*(ls*fit_l[None, :] + ls.T*fit_l[:, None]) + ss*fit_l[:, None]*fit_l[None, :]) cross = (a*a*ld - a*(ls*fit_d[None, :] + ds.T*fit_l[:, None]) + ss*fit_l[:, None]*fit_d[None, :]) variance = 0.5*(variance + variance.T) scale = max(np.max(np.abs(a*a*ll)), np.max(np.abs(a*ls*fit_l[None, :])), np.max(np.abs(ss*fit_l[:, None]*fit_l[None, :]))) noise_floor = 64*np.finfo(float).eps*max(k, p)*scale if np.trace(variance) <= epsilon: gain = np.zeros((p, p)) else: # A fitted scalar prior preserves H = alpha*L even when # the fold cannot identify a full matrix's null directions. prior = 1 + np.trace(cross)/np.trace(variance) gain = prior*np.eye(p) + regularized_matrix_gain( variance, cross+(1-prior)*variance, epsilon, max_rank=k-1, noise_floor=noise_floor, ) else: variance = np.maximum(a*a*ll - 2*a*fit_l*ls_diag + fit_l**2*ss_diag, 0.0) cross = a*a*ld - a*(fit_d*ls_diag + fit_l*ds_diag) + fit_l*fit_d*ss_diag if mode == 'scalar': total = variance.sum() gain = np.array(1 + cross.sum()/total if total > epsilon else 0.0) else: gain = np.zeros(p) keep = variance > epsilon gain[keep] = 1 + cross[keep]/variance[keep] gain = gain.reshape(shape) if np.isfinite(gain_limit): if matrix: u, singular, vt = np.linalg.svd(gain, full_matrices=False) if singular[0] > gain_limit: gain = (u*np.minimum(singular, gain_limit)) @ vt else: gain = np.clip(gain, -gain_limit, gain_limit) negligible = high_variance == 0.0 if ref_squares is not None: reference = np.sqrt(reference_sums[i]/k) negligible |= np.sqrt(high_variance) <= 64*np.finfo(float).eps*np.maximum(reference, np.finfo(float).tiny) if matrix: gain[:, negligible] = 0.0 elif mode == 'scalar': if np.all(negligible): gain = np.array(0.0) else: gain.reshape(-1)[negligible] = 0.0 else: gain = np.zeros(gain_shape) gains[indices] = gain high_term = (fold_wh[indices, None]-held_h)*s[indices] if m: low_term = (fold_wl[indices, None]-held_l)*s[indices] # The paired LF term and LF-only mean use exactly the same # outer-fold LF baseline. No baseline is fitted on extra samples. extra_mean = extra_centered_mean + ((extra_reference-fold_rl)-held_l)*extra_score_mean delta = extra_mean-low_term projection = delta @ gain if matrix else delta*gain.reshape(-1) corrected[indices] = high_term + ratio*projection else: corrected[indices] = high_term if needs_fit: for j in indices: suffix.add({key: value[j] for key, value in basis.items()}) result = (corrected.mean(axis=0).reshape(shape), np.asarray(gains.mean(axis=0)), gains) if return_baselines: return result + (dict(high=outer_high_baselines.reshape((n,)+shape), low=outer_low_baselines.reshape((n,)+shape)),) return result
def history_weights(data, scale, entropy_strategy='analytic'): if data is None: raise ValueError('History gain estimation requires the accepted HF training window.') high = scale*np.asarray(data['high_log_joint']) low = scale*np.asarray(data['low_log_joint']) if entropy_strategy == 'joint': from romtools.workflows.inverse.vi.drivers import _compute_variational_log_densities logq = _compute_variational_log_densities( data['optimizer_samples'], data['mean'], data['std'], data['correlation_cholesky'], ) high = high-scale*logq low = low-scale*logq return high, low def sample_ids(directory, count): return [f'{directory}::{i}' for i in range(count)]
[docs] def append_training_batch(batches, batch, limit): """Trim accepted samples to the same count limit used for ROM training.""" if limit < 1: raise ValueError('The history training-window limit must be positive.') result = list(batches)+[batch] excess = sum(len(item['parameter_samples']) for item in result)-limit row_fields = ('parameter_samples', 'optimizer_samples', 'high_log_joint', 'log_priors', 'log_transform_jacobian', 'sample_ids') while excess > 0: first = result[0] count = len(first['parameter_samples']) if count <= excess: result.pop(0) excess -= count else: trimmed = dict(first) for key in row_fields: values = first[key][excess:] trimmed[key] = list(values) if key == 'sample_ids' else values.copy() result[0] = trimmed excess = 0 return result
[docs] def importance_weights(samples, target_mean, target_std, target_correlation, batches): """Balance-mixture MIS weights; normalize in log space without clipping.""" counts = np.array([len(batch['parameter_samples']) for batch in batches], dtype=float) component_logs = [ np.log(count/counts.sum())+_compute_variational_log_densities( samples, batch['mean'], batch['std'], batch['correlation_cholesky'], ) for count, batch in zip(counts, batches) ] mixture = logsumexp(np.stack(component_logs), axis=0) target = _compute_variational_log_densities(samples, target_mean, target_std, target_correlation) log_weights = target-mixture if not np.any(np.isfinite(log_weights)): return np.zeros(len(samples)), log_weights, 0.0 if np.any(np.isnan(log_weights)) or np.any(np.isposinf(log_weights)): raise ValueError('History importance densities must produce valid finite weight ratios.') weights = np.exp(log_weights-logsumexp(log_weights)) return weights, log_weights, float(1/np.sum(weights**2))
[docs] def fit_history_gain(high_weights, low_weights, scores, baseline_method, mode, sample_weights=None): """Weighted covariance fit; probabilities enter moments once, not twice.""" mode = _normalize_mfmc_control_variate_mode(mode) baseline_method = _normalize_baseline_method(baseline_method) n = len(high_weights) shape = scores.shape[1:] p = int(np.prod(shape)) gain_shape = () if mode == 'scalar' else ((p, p) if mode == 'matrix' else shape) weights = np.ones(n)/n if sample_weights is None else np.asarray(sample_weights, dtype=float) if weights.shape != (n,) or not np.all(np.isfinite(weights)) or np.any(weights < 0): raise ValueError('History sample weights must be finite nonnegative weights, one per sample.') mass = weights.sum() if not np.isfinite(mass): raise ValueError('History sample weights must have finite total mass.') if n < 2 or mass == 0: return np.zeros(gain_shape) weights = weights/mass if 1/np.sum(weights**2) < 2-1e-12: return np.zeros(gain_shape) flat = np.asarray(scores).reshape(n, p) high, low = np.asarray(high_weights), np.asarray(low_weights) if baseline_method == 'none': h, l = high[:, None]*flat, low[:, None]*flat else: rh, rl = high[0], low[0] high, low = high-rh, low-rl if baseline_method == 'loo': denominator = _exclusive_sums(weights)[:, None] hb = np.divide(_exclusive_sums(weights*high)[:, None], denominator, out=np.full((n, 1), -rh), where=denominator > 1e-12) lb = np.divide(_exclusive_sums(weights*low)[:, None], denominator, out=np.full((n, 1), -rl), where=denominator > 1e-12) else: denominator = np.sum(weights[:, None]*flat**2, axis=0) hb = np.divide(np.sum(weights[:, None]*high[:, None]*flat**2, axis=0), denominator, out=np.full(p, -rh), where=denominator > 1e-12) lb = np.divide(np.sum(weights[:, None]*low[:, None]*flat**2, axis=0), denominator, out=np.full(p, -rl), where=denominator > 1e-12) h, l = (high[:, None]-hb)*flat, (low[:, None]-lb)*flat x = l-np.sum(weights[:, None]*l, axis=0) y = h-np.sum(weights[:, None]*h, axis=0) variance = np.sum(weights[:, None]*x**2, axis=0) if mode == 'matrix': root = np.sqrt(weights)[:, None] u, singular, vt = np.linalg.svd(root*x, full_matrices=False) if singular[0]**2 <= 1e-12: return np.zeros((p, p)) keep = singular**2 > np.finfo(float).eps*p*singular[0]**2 keep[min(n-1, np.count_nonzero(weights)-1):] = False return vt[keep].T @ ((singular[keep]/(singular[keep]**2+1e-12))[:, None] * (u[:, keep].T @ (root*y))) cross = np.sum(weights[:, None]*x*y, axis=0) if mode == 'scalar': total = variance.sum() return np.array(cross.sum()/total if total > 1e-12 else 0.0) return np.divide(cross, variance, out=np.zeros(p), where=variance > 1e-12).reshape(shape)
[docs] def gaussian_history_kernels(data): """Mean/log-std gradient and Hessian kernels at the current target distribution.""" x, mean, std = data['optimizer_samples'], data['mean'], data['std'] z = (x-mean)/std chol = data['correlation_cholesky'] if chol is None: inverse = np.eye(len(mean)) inverse_z = z else: inverse = np.linalg.solve(chol.T, np.linalg.solve(chol, np.eye(len(mean)))) inverse_z = z @ inverse.T sm = inverse_z/std sl = z*inverse_z-1 n, d = x.shape second_mean = np.broadcast_to(-inverse/(std[:, None]*std[None, :]), (n, d, d)).copy() second_log = -(z[:, :, None]*z[:, None, :]*inverse[None, :, :]) indices = np.arange(d) second_log[:, indices, indices] -= z*inverse_z second_cross = -z[:, None, :]*inverse[None, :, :]/std[None, :, None] second_cross[:, indices, indices] -= sm return (sm, sl), ( sm[:, :, None]*sm[:, None, :]+second_mean, sl[:, :, None]*sl[:, None, :]+second_log, sm[:, :, None]*sl[:, None, :]+second_cross, )