Results

PartitionResult dataclass

PartitionResult(labels: ndarray, training_scores: ndarray, cell_weights: ndarray, cell_score_sums: ndarray, cell_score_means: ndarray, information_full: ndarray, information_partitioned: ndarray, objective: float, transform: FisherTransform, transformed_centers: ndarray | None, metric: ndarray | None, criterion: DOptimality | ProfiledDOptimality, config: PartitionConfig, execution: ExecutionConfig, train_report: InformationReport, provenance: ScoreProvenance, accepted_moves: int, scans: int, exchange_stable: bool, best_remaining_gain: float, objective_history: ndarray, positive_weight_mask: ndarray, lloyd_iterations: int = 0, accepted_lloyd_steps: int = 0, geometry: GeometryReport | None = None, profiled_report: ProfiledInformationReport | None = None, profiled_geometry: ProfiledGeometryReport | None = None, schema: ScoreSchema | None = None)

Represent optimized labels of one fixed weighted score table.

The solver counters are reported separately and never merged: scans and accepted_moves describe exchange work, while lloyd_iterations and accepted_lloyd_steps describe guarded batch relabelings. Both stay zero for a solver that performs neither. objective_history records every accepted step of every phase in order and is strictly increasing.

Geometry diagnostics are criterion-specific and never shared: a DOptimality result carries geometry and no profiled_geometry, a ProfiledDOptimality result carries profiled_geometry and no geometry. The two measure different objects — a strict Mahalanobis Voronoi rule that exchange stability guarantees, and an efficient semimetric whose Voronoi rule a stable profiled partition may violate — so one name for both would claim an implication that does not hold.

exchange_stable and geometry are verdicts at config.gain_tolerance, which GeometryReport records, and never claims at tolerance zero. A finite solver stops at that threshold, so verifying its output against a stricter one would reject partitions it legitimately converged on.

n_bins property

n_bins: int

Return the number of nonempty requested cells.

rank property

rank: int

Return the numerically informative score-space rank.

information_kind property

information_kind: str

Describe whether supplied-score matrices justify exact Fisher language.

"supplied_score_surrogate" means the reported matrices measure Var(E[s_hat | q]) for the supplied vectors s_hat, which is the model's Fisher information only when s_hat equals the model score.

report

report() -> InformationReport

Return supplied-score information for the fixed partition.

compile_quantizer

compile_quantizer(*, execution: ExecutionConfig | None = None) -> Quantizer

Compile an exchange-stable D partition into its canonical rule.

Theorem 3 makes a one-point-exchange-stable, nonsingular D partition a self-consistent \(I^{-1}\)-Mahalanobis Voronoi partition of the observed rows, so the compiled rule \(\hat q(s)=\arg\min_b (s-\mu_b)^\top I^{-1}(s-\mu_b)\) is bookkeeping rather than a new fit. The theorem is exact; the partition behind it is not. A finite solver stops at config.gain_tolerance, so the guarantee this method can offer is self-consistency at that tolerance: the rule reproduces every training label except on rows whose relocation is worth no more than gain_tolerance, which the geometry certificate has already measured and stamped with the same tolerance. Requiring exact reproduction instead verifies at tolerance zero and refuses partitions the solver converged on, which is what a boundary row in a million becomes.

Boundary ties are never resolved here. predict_scores keeps the ordinary argmin rule, which is deterministic and breaks a tie toward the lowest cell index; the tolerance governs verification, not assignment.

Returns:

• Quantizer –

  The deployable rule itself -- the partition's centers, metric and transform. It is a rule, not a new fit, so it carries no labels, reports or history; those already belong to this partition.

Raises:

• ValueError –

  When the criterion is not DOptimality, when the partition is not exchange-stable, when the compilation geometry is missing, or when the rule relabels a training row by more than gain_tolerance.

to_dict

to_dict() -> dict[str, JsonValue]

Return the fixed-sample result as JSON-ready data.

QuantizerResult dataclass

QuantizerResult(quantizer: Quantizer, criterion: Criterion, config: QuantizerConfig, execution: ExecutionConfig, trace: OptimizationTrace, labels: ndarray, train_report: InformationReport, validation_report: InformationReport | None, provenance: ScoreProvenance, hardening_gap: float | None = None, source_kind: str = 'score_sample', train_profiled_report: ProfiledInformationReport | None = None, validation_profiled_report: ProfiledInformationReport | None = None)

Represent a reusable hard rule on raw score vectors.

centers property

centers: ndarray

Return the frozen cell centers in transformed coordinates.

metric property

metric: ndarray | None

Return the frozen common Mahalanobis metric, if the rule carries one.

transform property

transform: FisherTransform

Return the informative-subspace projection the rule was fitted in.

schema property

schema: ScoreSchema | None

Return the names of the raw score coordinates, when they were declared.

n_bins property

n_bins: int

Return the number of hard output labels.

rank property

rank: int

Return the numerically informative score-space rank.

information_kind property

information_kind: str

Describe whether supplied-score matrices justify exact Fisher language.

"supplied_score_surrogate" means the reported matrices measure Var(E[s_hat | q]) for the supplied vectors s_hat, which is the model's Fisher information only when s_hat equals the model score.

predict_scores

predict_scores(scores: ArrayLike, *, execution: ExecutionConfig | None = None) -> ndarray

Assign raw score rows with the frozen score-space rule.

Rows are assigned in memory-bounded chunks so that predicting on a large sample never materializes the full [n_rows, n_bins, rank] distance tensor at once; each row's distance and nearest-center argmin are independent of every other row, so chunking is bit-identical to the unchunked computation.

evaluate_scores

evaluate_scores(scores: ArrayLike, weights: ArrayLike | None = None, *, execution: ExecutionConfig | None = None) -> InformationReport

Evaluate the frozen rule on a new weighted score sample.

report

report() -> InformationReport

Return final hard training-sample diagnostics.

to_dict

to_dict() -> dict[str, JsonValue]

Return JSON-ready in-memory state, not a versioned artifact format.

plot_summary

plot_summary(scores: ArrayLike, weights: ArrayLike | None = None) -> Figure

Create the optional score-space summary figure.

Quantizer dataclass

Quantizer(transform: FisherTransform, centers: ndarray, metric: ndarray | None, schema: ScoreSchema | None, provenance: ScoreProvenance, criterion: Criterion, execution: ExecutionConfig)

A frozen hard rule on score space.

This is what a fit is for: the object that turns a future score vector into a bin. It holds no training labels, no reports and no history -- those stay on :class:~scorequant.QuantizerResult, which exposes the rule as result.quantizer.

Attributes:

• transform (FisherTransform) –

  Projection onto the informative score subspace the rule was fitted in.

• centers (ndarray) –

  Cell centers in transformed coordinates, shape [K, R].

• metric (ndarray | None) –

  Optional common Mahalanobis metric, shape [R, R]. None means the ordinary Euclidean nearest-center rule in transformed coordinates.

• schema (ScoreSchema | None) –

  Optional names of the raw score coordinates the rule expects.

• provenance (ScoreProvenance) –

  How the scores the rule was fitted on were obtained.

• criterion (Criterion) –

  The objective the rule was optimized for, recorded so a loaded artifact can still say what it was built to preserve.

• execution (ExecutionConfig) –

  The backend the rule was fitted under, reused for prediction unless overridden.

n_bins property

n_bins: int

Return the number of hard output labels.

rank property

rank: int

Return the numerically informative score-space rank.

input_dim property

input_dim: int

Return the raw score dimension the rule accepts.

information_kind property

information_kind: str

Describe whether supplied-score matrices justify exact Fisher language.

predict_scores

predict_scores(scores: ArrayLike, *, execution: ExecutionConfig | None = None) -> ndarray

Assign raw score rows with the frozen rule.

Rows are assigned in memory-bounded chunks, so predicting on a large sample never materializes the full [n_rows, n_bins, rank] distance tensor at once. Each row's nearest-center argmin is independent of every other row, so chunking is bit-identical to the unchunked computation.

evaluate_scores

evaluate_scores(scores: ArrayLike, weights: ArrayLike | None = None, *, rank_rtol: float | None = None, execution: ExecutionConfig | None = None) -> InformationReport

Measure the information this rule retains on a new weighted sample.

This is a property of the rule rather than of the fit that produced it, so a loaded artifact can be scored against fresh data without the training result being present.

Parameters:

• rank_rtol (float | None, default: None ) –

  Relative rank threshold for the report. Defaults to the one the rule's own transform was built with.

to_dict

to_dict() -> dict[str, JsonValue]

Return JSON-ready rule state.

Unlike the diagnostic to_dict on the result types, this one is the readable face of a versioned format: :meth:save writes exactly these fields, with the arrays moved out to .npy members.

save

save(path: str | Path) -> Path

Write the rule to a versioned, non-pickle artifact.

The file is a zip archive holding one manifest.json and one .npy member per array. Nothing is pickled, so loading it executes no code from the file, and reading it back needs neither JAX nor the solver that produced it.

Parameters:

• path (str | Path) –

  Destination path. .sqz is appended when the path has no suffix.

Returns:

• Path –

  The path actually written.

load classmethod

load(path: str | Path) -> Quantizer

Read a rule written by :meth:save.

Raises:

• ValueError –

  When the file is not a ScoreQuant artifact, or declares a format_version this build does not know. An unknown version is refused by name rather than partially interpreted.

InformationReport dataclass

InformationReport(fisher_unbinned: ndarray, fisher_binned: ndarray, retained_matrix: ndarray, retained_eigenvalues: ndarray, arithmetic_mean_retention: float, geometric_mean_retention: float, logdet_retention: float, bin_weights: ndarray, bin_counts: ndarray, bin_effective_sample_sizes: ndarray, effective_rank: int, rank_threshold: float, psd_residual_min_eigenvalue: float)

Report supplied-score retention and per-bin diagnostics for one sample.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation.

__str__

__str__() -> str

Format headline supplied-score diagnostics.

ProfiledInformationReport dataclass

ProfiledInformationReport(interest: tuple[int, ...], nuisance: tuple[int, ...], schur_unbinned: ndarray, schur_binned: ndarray, nuisance_unbinned: ndarray, nuisance_binned: ndarray, objective: float, logdet_retention: float, geometric_mean_retention: float, interest_rank: int, nuisance_rank: int, schema: ScoreSchema | None = None)

Report same-label profiled information for interest and nuisance blocks.

interest_names property

interest_names: tuple[str, ...] | None

Return the names of the parameters of interest, when they were declared.

nuisance_names property

nuisance_names: tuple[str, ...] | None

Return the names of the profiled nuisance parameters, when declared.

describe

describe() -> str

Summarize the profiling split in one line, by name when one is available.

interest: HSPCs says what was optimized; interest: (4,) requires the reader to remember the column order.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible profiled-information representation.

GeometryReport dataclass

GeometryReport(maximum_voronoi_violation: float, guaranteed_violation_gain: float, maximum_violation_gain: float, maximum_separation_residual: float, violating_moves: int, evaluated_moves: int, voronoi_consistent: bool, separation_certified: bool, gain_tolerance: float)

Certify the self-consistent Voronoi geometry of a finite D partition.

At a one-point-exchange-stable, positive-definite D partition every admissible move that violates the Mahalanobis-Voronoi rule of the terminal metric \(I^{-1}\) would raise the log determinant by at least \(\log(1+\alpha\beta q_\delta^2/4)>0\), where \(q_\delta=(\mu_a-\mu_b)^\top I^{-1}(\mu_a-\mu_b)\) separates the two cell means. Exchange stability therefore forces strict Voronoi geometry, which is what makes PartitionResult.compile_quantizer well posed. This report measures both sides of that statement on the terminal state instead of assuming them.

A finite solver stops at a tolerance, so this certificate states one too. The theorem is exact, but the guaranteed gain of a violation shrinks with the cell separation, and on a large sample \(q_\delta\) shrinks with the sample size: once \(\log(1+\alpha\beta q_\delta^2/4)\) falls below the solver's gain_tolerance, exchange stability at that tolerance no longer forbids a row from sitting a hair past a cell boundary. Verifying such a state at tolerance zero rejects a partition the solver never claimed to have refined further, so every field below is judged against gain_tolerance instead.

All quadratic forms use the same metric and cell means the solver ended with, evaluated over the distinct positive-weight score atoms.

Attributes:

• maximum_voronoi_violation (float) –

  Largest value over rows of the own-cell distance minus the smallest other-cell distance. A nonpositive value means every row already sits in its nearest cell under the terminal metric. It is -inf for a single-cell partition, which has no alternative destination. This is a Mahalanobis distance gap, not a criterion gain, so it is a diagnostic and never the verdict.

• guaranteed_violation_gain (float) –

  Largest Theorem-3 lower bound \(\log(1+\alpha\beta q_\delta^2/4)\) over admissible Voronoi-violating moves, and exactly 0.0 when no such move exists.

• maximum_violation_gain (float) –

  Largest exact log-determinant gain over the same admissible Voronoi-violating moves, and exactly 0.0 when none exists. Theorem 3 bounds this from below, so guaranteed_violation_gain <= maximum_violation_gain always holds. This is the quantity the solver drives below its tolerance, so it is the one the verdict uses.

• maximum_separation_residual (float) –

  Largest value over unordered cell pairs of \(q_\delta-(1/W_a+1/W_b)\). The leverage lemma makes this nonpositive for every labeling, so a positive value indicates numerical trouble rather than a better partition. It is -inf for a single-cell partition.

• violating_moves, evaluated_moves –

  Number of admissible Voronoi-violating moves and of admissible moves. A move is admissible when its source cell keeps positive weight and its destination differs from its source.

• voronoi_consistent (bool) –

  Whether maximum_violation_gain is at most gain_tolerance: no Voronoi violation is worth more than the solver's own stopping threshold. It is True whenever no row is misplaced at all.

• separation_certified (bool) –

  Whether maximum_separation_residual respects the leverage lemma up to a small relative floating-point tolerance.

• gain_tolerance (float) –

  Log-determinant gain tolerance this certificate holds at, taken from the configuration that produced the labels. voronoi_consistent means self-consistent at this tolerance and claims nothing at tolerance zero.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible Voronoi-geometry representation.

ProfiledGeometryReport dataclass

ProfiledGeometryReport(metric: ndarray, maximum_positive_violation: float, maximum_theoretical_bound: float, maximum_bound_residual: float, violating_moves: int, evaluated_moves: int, bound_certified: bool)

Diagnose the finite efficient-semimetric gap of a profiled partition.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible geometry-gap representation.

EfficientScoreBound dataclass

EfficientScoreBound(upper_bound: float, labels: ndarray, efficient_scores: ndarray, n_bins: int, interest: tuple[int, ...])

Certify a ceiling on profiled information from the full-data efficient score.

Let \(\hat s=s_\psi-B^\ast s_\lambda\) be the efficient score built from the full-data information matrix, and let \(q\) be any hard rule with at most n_bins cells. Efficient-score domination states

\[ \mathrm{Schur}_\psi\!\left(I_q\right)\;\preceq\; \mathbb{E}\!\left[\hat s \mid q\right]\text{-between-cell information}, \]

so maximizing the right-hand side over all n_bins-cell rules of \(\hat s\) upper-bounds the profiled objective of every n_bins-cell rule of the full score space. For one parameter of interest the right-hand side is scalar, the maximizer has ordered interval cells, and the exact weighted interval dynamic program attains it. upper_bound is the logarithm of that maximum, in the same convention as PartitionResult.objective under ProfiledDOptimality: an uncentered between-cell second moment of raw score columns, never a mean-centered variance.

Attributes:

• upper_bound (float) –

  Log-scale certified ceiling on the profiled objective.

• labels (ndarray) –

  Interval labels of the efficient score, defined for every input row. Zero-weight rows carry the label of their nearest cell mean and never influence the bound. These labels are also a strong initializer: pass them as initial_labels to optimize_partition under ProfiledDOptimality.

• efficient_scores (ndarray) –

  Full-information efficient scores with shape [N, 1].

• n_bins, interest –

  Cell budget and interest columns the bound was certified for.

Notes

The bound is a property of one weighted score table. Comparing it to a partition of different scores or weights is meaningless, and gap_to cannot detect that mismatch; it only checks the criterion convention and the cell budget. Refinement monotonicity makes the bound valid for any partition with at most n_bins cells.

gap_to

gap_to(partition_result: PartitionResult) -> float

Return the certified slack between the bound and an achieved objective.

Parameters:

• partition_result (PartitionResult) –

  Profiled-\(D_s\) result on the same weighted score table, with the same interest columns and at most n_bins cells.

Returns:

• float –

  upper_bound minus the achieved profiled objective. The value is nonnegative up to floating-point error on valid inputs.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation of the certified bound.

OptimizationTrace dataclass

OptimizationTrace(steps: ndarray, centers: ndarray, objective: ndarray, bin_weights: ndarray, train_hard_retention: ndarray, objective_label: str, validation_hard_retention: ndarray | None = None, soft_retention: ndarray | None = None, temperatures: ndarray | None = None, gradient_norms: ndarray | None = None)

Store aggregate quantizer optimization history.

Attributes:

• objective_label (str) –

  Units of objective. Solvers do not share one objective convention: "whitened_sse" is a minimized weighted within-cell squared error in Fisher-whitened coordinates, "logdet_retained" is a maximized retained log determinant, and "profiled_logdet" is a maximized profiled log determinant. Never compare two traces across labels.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible representation.

ScoreProvenance dataclass

ScoreProvenance(kind: ScoreKind = 'unknown', description: str | None = None, reference_point: tuple[float, ...] | None = None, metadata: Mapping[str, JsonValue] = dict(), ratio: RatioProvenance | None = None)

Describe where supplied score coordinates came from.

exact_fisher is derived from kind rather than accepted as an independent flag, so estimated scores cannot accidentally claim exact Fisher semantics. Scores built from model density ratios additionally carry a ratio record describing how the ratios were obtained.

exact_fisher property

exact_fisher: bool

Return whether exact-Fisher language is permitted.

to_dict

to_dict() -> dict[str, JsonValue]

Return a JSON-compatible provenance mapping.