In the library
The library raises two different kinds of error. A contract error means the call was malformed: mismatched shapes, a negative weight, a criterion paired with a configuration that cannot serve it. A refusal is not that. The arguments are well formed and the computation would run; the library declines because what the call asks it to assert is false in general, and it names the exact counterexample that makes it false.
Each refusal below therefore comes with a fixture: a small table of exact rational scores on which the asserted property demonstrably fails. A reader who doubts a refusal can read the fixture instead of taking the refusal on trust.
The refusals
| Refusal | Raised on | Rests on | Instead |
|---|---|---|---|
CE-DS-GLOBAL-GEOMETRY-001a global profiled optimum can violate its own first-order rule, so profiled labels have no canonical extension |
| Fit a reusable rule directly with | |
CE-D-VORONOI-CONVERSE-001looking geometric is strictly weaker than being exchange-stable |
| Inspect | |
CE-D-UNMERGED-DUPLICATES-001split duplicate atoms can be vacuously stable while defeating label reproduction | The terminal rule would relabel a training row by more than the gain tolerance | Merge or consistently label coincident score rows; inspect | |
CE-DS-MARGINS-RANK-VACUITY-001The cardinality boundary of | A profiled fit or partition whose cell count cannot generate nonsingular binned information | Raise |
What each object rests on
Every public object below is listed with the results that justify it. Where the list is empty the object is bookkeeping: it reports or carries what another object established, and adds no claim of its own.
Criteria
DOptimality(opens in a new tab)The log determinant of the binned information. Chosen partly because it is invariant under invertible reparameterization
ProfiledDOptimality(opens in a new tab)The log determinant of the Schur complement for the declared parameters of interest. The
interestargument is the parameter block; at least one nuisance column must remainNormalizedTrace(opens in a new tab)Retained normalized trace, which after Fisher whitening is exactly weighted k-means
Solver configurations
DExchangeConfig(opens in a new tab)Exact positive-gain one-point exchange: the closed-form relocation gain on the rank-two update, accepted only on strictly positive exact gains so the search terminates
MahalanobisLloydConfig(opens in a new tab)Batch reassignment as a proposal, accepted on the exact objective. The guard exists because the unguarded step is not monotone;
guard="exchange"hands the labels to the exact engine so the reported state stays compilableKMeansConfig(opens in a new tab)Weighted k-means on whitened scores, which is the trace criterion exactly
SoftVoronoiConfig(opens in a new tab)Optimization of a randomized quantizer's exact information, which exists because the hard empirical objective is piecewise constant and has no usable gradient. Its guarantees are those of smooth nonconvex optimization and no more
ScalarDPConfig(opens in a new tab)Exact interval dynamic programming on one score coordinate — the optimal cells are intervals, so the program returns a global optimum rather than a local one
Results and certificates
PartitionResult(opens in a new tab)A labelling of one fixed sample — the first of the three questions. It deliberately has no
predictmethod, because a finite labelling does not determine its own extensionNo result of its own.
PartitionResult.compile_quantizer()(opens in a new tab)The one exception: an exchange-stable, nonsingular
DOptimalityresult compiles into a Mahalanobis rule. It is bookkeeping, not a second fitGeometryReport(opens in a new tab)Measures both sides of the exchange-implies-Voronoi theorem on the terminal state instead of assuming them.
guaranteed_violation_gainis the theorem's lower bound;maximum_violation_gainis the exact gain the theorem bounds;maximum_separation_residualchecks the leverage inequality, so a positive value indicates numerical trouble rather than a better partitionStabilityReport(opens in a new tab)One complete exact scan certifying that no single relocation improves a supplied labelling, at a stated
gain_tolerance. A labelling certified at one tolerance is not certified at a smaller oneNo result of its own.
PartitionCertificate(opens in a new tab)The outcome of a bounded global search using the singleton-completion ceiling.
statusis either "optimal" or "budget_exhausted"; the second proves nothing about the incumbent, andincumbent_was_optimalisFalsewhenever it occursEfficientScoreBound(opens in a new tab)The full-data efficient-score ceiling on profiled information, attained for one parameter of interest by the exact interval program. Its
labelsalso serve as a strong initializerProfiledGeometryReport(opens in a new tab)Diagnoses the finite efficient-semimetric gap — the quantity that the profiled case has instead of a geometry theorem
Information reports
InformationReport.retained_matrix, retained_eigenvalues(opens in a new tab)The normalized retention spectrum, every eigenvalue in the unit interval
InformationReport.geometric_mean_retention(opens in a new tab)Determinant efficiency against unbinned inference
InformationReport.arithmetic_mean_retention, and the eigenvalue list(opens in a new tab)Direction-resolved diagnostics. They are reported separately because optimizing the determinant does not equalize retention across directions — a caution, not a theorem
InformationReport.effective_rank(opens in a new tab)The rank the binned information actually reached, against the ceiling
min(d, K-1)ProfiledInformationReport.geometric_mean_retention(opens in a new tab)Profiled efficiency, undefined where the Schur complement is singular
Sources and score providers
ScoreSample(opens in a new tab)The scores are supplied directly; provenance is exact and every identity on these pages applies as written
No result of its own.
LinearComponentScore, scores_from_components(opens in a new tab)Component densities give the local score of a linear mixture
DensityRatioScore, CentralLogRatioScore(opens in a new tab)The local score is the gradient of a log density ratio, so normalized densities are unnecessary
ratios_from_posteriors(opens in a new tab)Calibrated classifier posterior odds recover component density ratios when the training priors are known
RatioProvenance, ScoreProvenance(opens in a new tab)The record of which of the above applies. Estimated ratios never claim exact Fisher semantics, because the retained information is governed by the true score under the estimated rule and no theorem yet bounds the difference
ratio_closure_report(opens in a new tab)A necessary check that model ratios integrate to one under the reference measure. It is necessary and not sufficient: a small residual never upgrades estimated provenance to exact
No result of its own.