Skip to content

Healing (predictive primitives)

The shared decision primitive Mitigation and Vector Healing both call into -- see Concepts for which of those two you actually want.

Given one step of a noisy telemetry sequence (a VQE energy, an MD trajectory value), is this a genuine change worth keeping, or a spike worth smoothing away? This module's primitives answer that question one number at a time -- the "Phi-Trigger" -- and are what ia_utils.vector_healing.enhanced_dense_healing_hybrid calls internally on a whole sequence. Reach for this page directly when you want that same decision on raw values of your own, without going through the full sequence-healing wrapper.

Step 1. The trigger: real change or noise?

import jax.numpy as jnp
import dense_evolution.healing as h

dq_dt = jnp.array([0.001, 0.002, 0.5, 0.001])
h.evaluate_phi_trigger(dq_dt)

(Array([0., 0., 1., 0.], dtype=float32, weak_type=True),
 Array([0.15, 0.15, 0.05, 0.15], dtype=float32, weak_type=True),
 Array([0.11, 0.11, 0.01, 0.11], dtype=float32, weak_type=True))

dq_dt is one rate-of-change value per step -- how much a quantity moved since the previous step. evaluate_phi_trigger returns three arrays: the trigger itself (1.0 where a step's rate crosses the "this is real dynamics" threshold, 0.0 otherwise -- only the third step here, 0.5, is large enough), and two damping coefficients that drop when the trigger fires (0.15 -> 0.05 and 0.11 -> 0.01) -- a genuine change gets less aggressive smoothing applied around it than a static step would.

Step 2. Where dq_dt comes from: comparing two real states

ipg_vector = jnp.array([1.0, 0.0])
phi_ab = h.calculate_phi_ab(jnp.array([1.0, 0.0]), jnp.array([1.0, 0.0]), ipg_vector)

v_stable = h.calculate_vettore_dinamico(jnp.array(1.0), jnp.array(1.001), phi_ab)
v_jump = h.calculate_vettore_dinamico(jnp.array(1.0), jnp.array(1.5), phi_ab)

h.evaluate_phi_trigger(jnp.array([v_stable, v_jump]))[0]

Array([0., 1.], dtype=float32, weak_type=True)

Step 1's dq_dt isn't usually handed to you directly -- it's built from two states E_A/E_B (a scalar energy or observable at consecutive steps) plus Phi_AB, an alignment/coherence factor between them (calculate_phi_ab, here computed once for two identical direction vectors and reused for both comparisons). calculate_vettore_dinamico(E_A, E_B, Phi_AB) is log(E_B/E_A) scaled by that alignment -- a log-likelihood-ratio-flavored measure of how much E_A moved to become E_B. 1.0 -> 1.001 (v_stable = 0.0035) doesn't trigger; 1.0 -> 1.5 (v_jump = 1.42) does -- exactly the same 0/1 split Step 1 showed directly, now built from two real states instead of a rate-of-change handed in already computed.

Details

What's principled vs. empirical here: calculate_vettore_dinamico's core term is a genuine log-likelihood ratio (the same elementary quantity Kullback-Leibler divergence is built from -- see kl_divergence for the distinction between this one un-weighted scalar ratio and a full KL divergence over a probability distribution). calculate_phi_ab is a geometric construction instead, built empirically rather than derived from an information-theoretic quantity -- worth knowing before leaning on either reading too heavily.

Applied layer: ia_utils.vector_healing.enhanced_dense_healing_hybrid is what actually calls these primitives on a real (n_steps, dim) sequence -- see Vector Healing for that page's own worked examples. This shipped with the pre-rebuild dashboard_core's Streamlit "AI healing shield" middleware (VQE/MD telemetry routed through it before any panel was built from it), and was left behind -- not removed -- when dashboard_core was rebuilt around the Composer kernel.

Reintegrated end to end: dashboard_core.run_vector_healing (a thin wrapper, mirroring mitigation.py's shape) -> the kernel's POST /api/vector_healing -> the MCP tool dense_evolution_vector_healing (see mcp_server/README.md). All three call the same real primitives on this page -- no separate reimplementation.

The other branch, not wired up: dense_evolution.mitigation's zero_noise_extrapolation has a healing-adapted branch (triggered by passing sigma_at_base_noise) that calls calculate_delta_preemp from this module. Unlike run_vector_healing above, this branch is not currently reachable from the kernel or MCP: dashboard_core.run_zne_mitigation never passes sigma_at_base_noise, and the kernel's MitigateRequest has no field for it. This was originally left as a known follow-up pending calculate_advanced_sigma's undefined input provenance -- that question has since been closed, not completed: Dense-Evolution-Discovery Experiment 35 (scripts/zne_healing_sigma_provenance.py) fed the branch a real, oracle-free sigma_at_base_noise (the empirical std of the noisy trial ensemble) and found, via a permutation-test negative control, that the branch's coefficient perturbation doesn't discriminate real sigma from randomly shuffled sigma at all -- a confound, not a usable signal. Wiring this branch up would not have helped even with fully-designed inputs. calculate_advanced_sigma is now deprecated (DeprecationWarning, kept for backward compatibility only) rather than completed -- excluded from the guide above for that reason.

healing

Backward-compatibility shim -- the real implementation moved to dense_evolution.mitigation.healing as part of the Phase 2 subpackage split (see prog.txt). Kept so from dense_evolution.healing import calculate_phi_ab (used by external consumers, e.g. tools/ia_utils and Dense-Evolution-Discovery) keeps working unchanged. Import from dense_evolution.mitigation.healing directly in new code.

calculate_advanced_sigma 

calculate_advanced_sigma(
    kappa: ndarray,
    H: ndarray,
    Psi: ndarray,
    Omega_sync: ndarray,
    tau_K: ndarray,
) -> jnp.ndarray

Deprecated: kappaHPsiOmega_synctau_K, intended as the source of zero_noise_extrapolation's sigma_at_base_noise (see this module's own docs/api/healing.md), but its 5 inputs never had a defined provenance in a ZNE context -- and Dense-Evolution-Discovery Experiment 35 (scripts/zne_healing_sigma_provenance.py) has since shown that even a fully-designed input wouldn't matter: a permutation-test negative control (real sigma vs. randomly shuffled sigma) performed statistically identically, meaning the healing-adapted branch's coefficient perturbation doesn't discriminate real signal from noise at all. Kept for backward compatibility only (no known external callers found in Dense-Evolution, Dense-Evolution-Discovery, or Dense-Armor); will be removed in a future major version. This wrapper is intentionally NOT @jax.jit-decorated (unlike the private core it delegates to) so the warning fires on every call, not just once per traced input shape.

Source code in dense_evolution/mitigation/healing.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def calculate_advanced_sigma(kappa: jnp.ndarray, H: jnp.ndarray, Psi: jnp.ndarray, Omega_sync: jnp.ndarray, tau_K: jnp.ndarray) -> jnp.ndarray:
    """Deprecated: kappa*H*Psi*Omega_sync*tau_K, intended as the source of
    zero_noise_extrapolation's sigma_at_base_noise (see this module's own
    docs/api/healing.md), but its 5 inputs never had a defined provenance
    in a ZNE context -- and Dense-Evolution-Discovery Experiment 35
    (scripts/zne_healing_sigma_provenance.py) has since shown that even a
    fully-designed input wouldn't matter: a permutation-test negative
    control (real sigma vs. randomly shuffled sigma) performed
    statistically identically, meaning the healing-adapted branch's
    coefficient perturbation doesn't discriminate real signal from noise
    at all. Kept for backward compatibility only (no known external
    callers found in Dense-Evolution, Dense-Evolution-Discovery, or
    Dense-Armor); will be removed in a future major version. This wrapper
    is intentionally NOT @jax.jit-decorated (unlike the private core it
    delegates to) so the warning fires on every call, not just once per
    traced input shape."""
    warnings.warn(
        "calculate_advanced_sigma is deprecated: its output was never wired into "
        "any real pipeline, and Dense-Evolution-Discovery Experiment 35 found the "
        "one place it could have been used (zero_noise_extrapolation's healing "
        "branch) does not discriminate real sigma from random noise anyway. "
        "Will be removed in a future release.",
        DeprecationWarning, stacklevel=2,
    )
    return _calculate_advanced_sigma_core(kappa, H, Psi, Omega_sync, tau_K)

calculate_phi_ab 

calculate_phi_ab(
    state_A: ndarray, state_B: ndarray, ipg_vector: ndarray
) -> jnp.ndarray

Computes the Phi_AB spatial alignment and coherence factor.

Source code in dense_evolution/mitigation/healing.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
@jax.jit
def calculate_phi_ab(state_A: jnp.ndarray, state_B: jnp.ndarray, ipg_vector: jnp.ndarray) -> jnp.ndarray:
    """Computes the Phi_AB spatial alignment and coherence factor."""
    semantic_change = state_B - state_A
    norm_change = jnp.linalg.norm(semantic_change)
    norm_ipg = jnp.linalg.norm(ipg_vector)

    alignment = jnp.where(
        (norm_change > 1e-12) & (norm_ipg > 1e-12),
        # jnp.dot on complex arrays is the bilinear (non-conjugated) product
        # and stays complex, which used to blow up jnp.clip below with
        # "ValueError: Clip received a complex value". jnp.real(jnp.vdot(..))
        # is the correct Hermitian-inner-product real part -- for real
        # inputs it reduces exactly to jnp.dot (no behavior change for
        # existing real-valued callers), and for complex inputs (e.g. a
        # genuine statevector) it gives the real alignment value this
        # function needs. Re(vdot(a,b)) == Re(vdot(b,a)) always, even
        # though vdot(a,b) != vdot(b,a) in general (they're conjugates) --
        # argument order doesn't matter here only because we take the real part.
        jnp.real(jnp.vdot(semantic_change, ipg_vector)) / (norm_change * norm_ipg),
        0.0
    )
    semantic_alignment = (alignment + 1.0) / 2.0

    distance_A_B = jnp.linalg.norm(state_A - state_B)
    coherence_component = 1.0 - (distance_A_B / GLOBAL_CONSTANTS['MAX_SEMANTIC_DISTANCE'])

    phi_ab = (semantic_alignment * GLOBAL_CONSTANTS['WEIGHT_SEMANTIC']) + (coherence_component * GLOBAL_CONSTANTS['WEIGHT_COHERENCE'])
    return jnp.clip(phi_ab, 0.0, 1.0)

calculate_vettore_dinamico 

calculate_vettore_dinamico(
    E_A: ndarray, E_B: ndarray, Phi_AB: ndarray
) -> jnp.ndarray

Computes the Dynamic Vector (V_dinamic) as a differential logarithmic energy variation.

log(E_B / E_A) is a log-likelihood ratio -- the same elementary quantity Kullback-Leibler divergence is built from (see this module's docstring for the precise distinction: this is one un-weighted log-ratio between two scalars, not a full KL divergence over a probability distribution). Equivalently, the difference in surprisal (-log E) between the two states.

Source code in dense_evolution/mitigation/healing.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
@jax.jit
def calculate_vettore_dinamico(E_A: jnp.ndarray, E_B: jnp.ndarray, Phi_AB: jnp.ndarray) -> jnp.ndarray:
    """Computes the Dynamic Vector (V_dinamic) as a differential logarithmic energy variation.

    log(E_B / E_A) is a log-likelihood ratio -- the same elementary
    quantity Kullback-Leibler divergence is built from (see this
    module's docstring for the precise distinction: this is one
    un-weighted log-ratio between two scalars, not a full KL divergence
    over a probability distribution). Equivalently, the difference in
    surprisal (-log E) between the two states."""
    valid_inputs = (E_A > 1e-12) & (E_B > 1e-12)
    ratio = jnp.where(valid_inputs, E_B / E_A, 1.0)
    log_ratio_clamped = jnp.clip(jnp.log(ratio), -5.0, 5.0)
    v_vita = GLOBAL_CONSTANTS['V_DINAMIC_K_COEFF'] * log_ratio_clamped * Phi_AB
    return jnp.where(valid_inputs, v_vita, 0.0)

calculate_vettore_statico 

calculate_vettore_statico(
    v_dinamic_value: ndarray,
) -> jnp.ndarray

Computes the Static Vector tensorial-stasis indicator.

Source code in dense_evolution/mitigation/healing.py 
137
138
139
140
141
@jax.jit
def calculate_vettore_statico(v_dinamic_value: jnp.ndarray) -> jnp.ndarray:
    """Computes the Static Vector tensorial-stasis indicator."""
    is_growing = v_dinamic_value > GLOBAL_CONSTANTS['V_DINAMIC_MIN_EFFECTIVE_VALUE']
    return GLOBAL_CONSTANTS['V_STATIC_K_PRIME_COEFF'] * (1.0 - jnp.where(is_growing, 1.0, 0.0))

calculate_delta_preemp 

calculate_delta_preemp(
    current_sigma: ndarray, target_sigma_ideal: float = 10.0
) -> jnp.ndarray

Computes the predictive deviation Delta_Pre_emp normalized against the ideal eigenstate.

Source code in dense_evolution/mitigation/healing.py 
143
144
145
146
147
@jax.jit
def calculate_delta_preemp(current_sigma: jnp.ndarray, target_sigma_ideal: float = 10.0) -> jnp.ndarray:
    """Computes the predictive deviation Delta_Pre_emp normalized against the ideal eigenstate."""
    safe_target = jnp.where(target_sigma_ideal <= 0.0, 1.0, target_sigma_ideal)
    return jnp.abs(current_sigma - target_sigma_ideal) / safe_target

evaluate_phi_trigger 

evaluate_phi_trigger(
    deterministic_dq_dt_a: ndarray,
) -> Tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]

Evaluates the Phi-Trigger state by computing the conditional damping coefficients.

Source code in dense_evolution/mitigation/healing.py 
149
150
151
152
153
154
155
156
157
158
159
@jax.jit
def evaluate_phi_trigger(deterministic_dq_dt_a: jnp.ndarray) -> Tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]:
    """Evaluates the Phi-Trigger state by computing the conditional damping coefficients."""
    magnitude_change_a = jnp.abs(deterministic_dq_dt_a)
    trigger_active = magnitude_change_a > GLOBAL_CONSTANTS['NON_STATIC_THRESHOLD_A']

    lambda_step = jnp.where(trigger_active, 0.05, 0.05 + GLOBAL_CONSTANTS['DAMPING_BOOST_ON_STASIS'])
    epsilon_dissip = jnp.where(trigger_active, GLOBAL_CONSTANTS['EPSILON_DISSIPATION_BASE'],
                                GLOBAL_CONSTANTS['EPSILON_DISSIPATION_BASE'] + GLOBAL_CONSTANTS['DAMPING_BOOST_ON_STASIS'])

    return jnp.where(trigger_active, 1.0, 0.0), lambda_step, epsilon_dissip

calculate_jax_reflection 

calculate_jax_reflection(
    coherence_values: ndarray, noise_levels: ndarray
) -> Tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]

Performs spectral statistical aggregation (Zero-Drift) on the XLA runtime.

Source code in dense_evolution/mitigation/healing.py 
161
162
163
164
165
166
167
168
169
170
171
@jax.jit
def calculate_jax_reflection(coherence_values: jnp.ndarray, noise_levels: jnp.ndarray) -> Tuple[jnp.ndarray, jnp.ndarray, jnp.ndarray]:
    """Performs spectral statistical aggregation (Zero-Drift) on the XLA runtime."""
    n_coh = coherence_values.shape[0]
    avg_coherence = jnp.where(n_coh > 0, jnp.mean(coherence_values), 0.0)
    var_coherence = jnp.where(n_coh > 0, jnp.var(coherence_values), 0.0)

    n_noise = noise_levels.shape[0]
    avg_noise = jnp.where(n_noise > 0, jnp.mean(noise_levels), 0.0)

    return avg_coherence, var_coherence, avg_noise