ldtc.lmeas

Lmeas: Estimators for loop and exchange influence (L).

Lightweight predictive-dependence estimators used to compute loop influence L_loop and exchange influence L_ex over a C/Ex partition. Includes linear (Granger-like) and mutual information methods, with optional TE/DI proxies. Confidence intervals are computed via circular block bootstrap per window.

See Also

paper/main.tex — Criterion; Methods: Measurement & Attestation.

LResult dataclass

Result container for loop/exchange influence and CI bounds.

Attributes:

Name	Type	Description
L_loop	float	Point estimate of loop influence.
L_ex	float	Point estimate of exchange influence.
ci_loop	Tuple[float, float]	Tuple of (lo, hi) CI bounds for L_loop.
ci_ex	Tuple[float, float]	Tuple of (lo, hi) CI bounds for L_ex.

estimate_L(X, C, Ex, method='linear', p=3, lag_mi=1, n_boot=64, mi_k=5)

Estimate loop and exchange influence.

Computes L_loop over partition C and L_ex from Ex -> C using the selected predictive dependence metric.

Parameters:

Name	Type	Description	Default
X	ndarray	Time-by-signal matrix of shape (T, N).	required
C	Sequence[int]	Indices of the loop partition.	required
Ex	Sequence[int]	Indices of the exchange partition.	required
method	str	One of {"linear", "mi", "mi_kraskov", "transfer_entropy", "directed_information"}.	'linear'
p	int	VAR order for linear estimator.	3
lag_mi	int	Lag between sources and targets for MI/TE/DI methods.	1
n_boot	int	Number of bootstrap draws for CI estimation.	64
mi_k	int	k-NN parameter for Kraskov MI.	5

Returns:

Type	Description
LResult	LResult with point estimates and (lo, hi) CI bounds for each metric.

Raises:

Type	Description
ValueError	If method is not supported.

Lmeas: Metrics and thresholds.

Helper metrics for loop-dominance M(dB) and SC1 evaluation used by the verification harness and figures.

See Also

paper/main.tex — Criterion; SC1; Methods: Threshold Calibration.

SC1Stats dataclass

Summary statistics used for SC1 evaluation.

Attributes:

Name	Type	Description
delta	float	Fractional drop in L_loop during the perturbation window.
tau_rec	float	Estimated recovery time in seconds.
M_post	float	Decibel margin measured after recovery gate.

m_db(L_loop, L_ex, eps=1e-12)

Compute loop-dominance in decibels.

Computes M = 10 * log10(L_loop / L_ex) with small positive floors to avoid division by zero.

Parameters:

Name	Type	Description	Default
L_loop	float	Loop influence value.	required
L_ex	float	Exchange influence value.	required
eps	float	Numerical floor applied to both numerator and denominator.	1e-12

Returns:

Type	Description
float	Decibel ratio of loop to exchange influence.

sc1_evaluate(L_loop_baseline, L_loop_trough, L_loop_recovered, M_post, epsilon, tau_rec_measured, Mmin, tau_max)

Evaluate SC1 pass/fail and return stats.

Checks that the fractional loop drop delta and recovery time tau_rec are within preset limits and that the post-recovery margin exceeds Mmin.

Parameters:

Name	Type	Description	Default
L_loop_baseline	float	Baseline loop influence before Ω.	required
L_loop_trough	float	Minimum loop influence measured during Ω.	required
L_loop_recovered	float	Loop influence after recovery (unused in decision here).	required
M_post	float	Post-recovery decibel margin M.	required
epsilon	float	Maximum allowed fractional drop.	required
tau_rec_measured	float	Measured recovery time (seconds).	required
Mmin	float	Minimum acceptable decibel margin after recovery.	required
tau_max	float	Maximum allowed recovery time.	required

Returns:

Type	Description
bool	Tuple (passed, stats) where passed is the SC1 decision and
SC1Stats	stats contains delta, tau_rec, and M_post.

Lmeas: Partition management and greedy regrowth.

Deterministic C/Ex partition representation with hysteresis and a greedy suggestor to increase loop influence under sparsity penalties.

See Also

paper/main.tex — Criterion; Methods: Partitioning algorithm.

Partition dataclass

C/Ex partition state with freeze flag and flip counter.

Attributes:

Name	Type	Description
C	List[int]	Indices belonging to the loop (closed) set.
Ex	List[int]	Indices belonging to the exchange set.
frozen	bool	If True, updates are suppressed (e.g., during Ω windows).
flips	int	Number of accepted partition flips since creation.

PartitionManager

Deterministic C/Ex partition with simple hysteresis.

Provides a minimal manager that can be frozen and updated only when a suggested partition yields a sufficient decibel gain ΔM for a required number of consecutive windows.

Parameters:

Name	Type	Description	Default
N_signals	int	Total number of signals N.	required
seed_C	Sequence[int]	Initial indices for the C set; remainder form Ex.	required

freeze(on)

Enable or disable freeze to suppress updates.

Parameters:

Name	Type	Description	Default
on	bool	True to freeze, False to unfreeze.	required

get()

Return the current partition state.

Returns:

Name	Type	Description
The	Partition	class:Partition dataclass instance.

maybe_regrow(suggested_C, delta_M_db, delta_M_min_db=0.5, consecutive_required=3)

Consider adopting suggested_C using hysteresis on the ΔM gain.

Updates are ignored when frozen. Accept only if the same suggestion persists for consecutive_required calls and the gain exceeds delta_M_min_db.

Parameters:

Name	Type	Description	Default
suggested_C	Sequence[int]	Candidate list of indices for C.	required
delta_M_db	float	Decibel gain relative to baseline.	required
delta_M_min_db	float	Minimum required ΔM to count toward acceptance.	0.5
consecutive_required	int	Number of consecutive ready windows required.	3

update_current_M(M_db)

Record the latest measured M for the current partition.

Parameters:

Name	Type	Description	Default
M_db	float	Decibel loop-dominance value.	required

greedy_suggest_C(X, C, Ex, *, estimator, method='linear', p=3, lag_mi=1, n_boot_candidates=8, mi_k=5, lam=0.0, theta=0.0, kappa=None)

Greedy regrowth of C using ΔL_loop gain with sparsity penalty.

Starting from the current C/Ex, iteratively add the candidate from Ex that maximizes the penalized gain in L_loop until the marginal gain falls below theta or a cap kappa is reached.

Parameters:

Name	Type	Description	Default
X	Any	Telemetry matrix (T, N) consumed by estimator.	required
C	List[int] | Sequence[int]	Current loop set indices.	required
Ex	List[int] | Sequence[int]	Current exchange set indices.	required
estimator	Callable[..., Any]	Callable compatible with :func:ldtc.lmeas.estimators.estimate_L.	required
method	str	Estimation method forwarded to estimator.	'linear'
p	int	VAR order for linear estimator.	3
lag_mi	int	Lag for MI-based estimators.	1
n_boot_candidates	int	Number of bootstrap draws used during candidate eval.	8
mi_k	int	k-NN parameter for Kraskov MI.	5
lam	float	Sparsity penalty per added node.	0.0
theta	float	Minimum penalized gain to accept a candidate.	0.0
kappa	int | None	Optional cap on |C|.	None

Returns:

Type	Description
List[int]	Tuple (suggested_C, delta_M_db, details) where details contains
float	provenance about added indices and intermediate gains.

Lmeas: Diagnostic helpers for measurement stability.

Wrappers for ADF/KPSS tests, stationarity summaries, and a VAR N/T ratio heuristic used to annotate audit records and guard measurement stability.

See Also

paper/main.tex — Methods: Measurement; Smell-tests & invalidation.

StationaritySummary dataclass

Summary of per-series stationarity flags.

Attributes:

Name	Type	Description
adf_nonstationary_frac	float	Fraction flagged non-stationary by ADF (fail to reject unit root at 5%).
kpss_nonstationary_frac	float	Fraction flagged non-stationary by KPSS (reject stationarity at 5%).
per_series	List[Tuple[bool, bool]]	List of tuples (adf_nonstat, kpss_nonstat) per column.

stationarity_checks(X)

Run ADF and KPSS per column and summarize.

Parameters:

Name	Type	Description	Default
X	ndarray	Array of shape (T, N) with time along axis 0.	required

Returns:

Type	Description
StationaritySummary	class:StationaritySummary with per-series flags and overall fractions.

Raises:

Type	Description
ValueError	If X is not a 2D array.

var_nt_ratio(T, N, p)

Rule-of-thumb samples-per-parameter ratio for VAR(p).

Computes (T - p) / (N * p) where T is time samples, N is the number of signals, and p is the lag order. Lower values indicate a more marginal regression setting.