Power fitting package
pyvoro2.powerfit
Public API for inverse fitting of power weights from pairwise constraints.
ActiveSetPathSummary
dataclass
Compact summary of transient active-set path diagnostics.
AlgebraicEdgeDiagnostics
dataclass
Edge-space diagnostics matching the paper-side algebraic formulas.
ConnectivityDiagnostics
dataclass
Structured connectivity diagnostics for the inverse-fit graph.
ConnectivityDiagnosticsError
Bases: ValueError
Raised when connectivity_check='raise' detects a graph issue.
ConstraintGraphDiagnostics
dataclass
Connectivity summary for a graph induced by constraint rows.
ExponentialBoundaryPenalty
dataclass
Bases: ScalarPenalty
Repulsive penalty near the boundaries of an interval.
The penalty is based on exponentials measured from an inner interval
[lower + margin, upper - margin].
FitModel
dataclass
Complete objective definition for inverse power-weight fitting.
The objective consists of
- one required mismatch term,
- an optional hard feasibility set,
- zero or more extra penalties,
- optional L2 regularization on the weights.
FixedValue
dataclass
HardConstraintConflict
dataclass
Compact witness for inconsistent hard separator restrictions.
HardConstraintConflictTerm
dataclass
One bound relation participating in an infeasibility witness.
HuberLoss
dataclass
Bases: ScalarMismatch
Huber mismatch penalty in the chosen measurement space.
The penalty is quadratic near zero and linear for large residuals.
Interval
dataclass
L2Regularization
dataclass
Optional L2 regularization on the weight vector.
PairBisectorConstraints
dataclass
Resolved pairwise separator constraints.
This object is the stable boundary between downstream pair-selection logic
and pyvoro2's inverse solver. Each row refers to a specific ordered pair
(i, j, shift) where shift is the lattice image applied to site j.
pair_labels(*, use_ids=False)
Return the left/right pair labels as indices or external ids.
subset(mask)
Return a subset with row order preserved.
to_records(*, use_ids=False)
Return one plain-Python record per constraint row.
PairConstraintDiagnostics
dataclass
to_records(*, ids=None)
Return one plain-Python record per candidate pair.
PowerFitProblem
dataclass
Stable public export of the resolved inverse power-fit problem.
canonicalize_gauge(weights)
Apply the standalone component gauge convention to candidate weights.
PowerWeightFitResult
dataclass
Result of inverse fitting of power weights.
RealizedPairDiagnostics
dataclass
Diagnostics for matching candidate constraints to realized boundaries.
to_records(constraints, *, use_ids=False)
Return one plain-Python record per candidate pair.
to_report(constraints, *, use_ids=False)
Return a JSON-friendly report for realized-boundary matching.
unaccounted_records(*, ids=None)
Return one record per realized-but-unaccounted unordered pair.
ReciprocalBoundaryPenalty
dataclass
Bases: ScalarPenalty
Reciprocal repulsion near interval boundaries.
This penalty is intended to be used together with a hard interval or a
strong outside penalty. It penalizes separator positions that enter the
boundary layers [lower, lower + margin] and [upper - margin, upper].
SelfConsistentPowerFitResult
dataclass
to_records(*, use_ids=False)
Return one plain-Python record per candidate pair.
to_report(*, use_ids=False)
Return a JSON-friendly report for this active-set solve.
SoftIntervalPenalty
dataclass
Bases: ScalarPenalty
Quadratic penalty for leaving a preferred interval.
The penalty is zero within [lower, upper] and quadratic outside.
SquaredLoss
dataclass
UnaccountedRealizedPair
dataclass
One realized internal boundary whose unordered pair was not supplied.
to_record(*, ids=None)
Return a plain-Python record for the unaccounted pair.
UnaccountedRealizedPairError
Bases: ValueError
Raised when unaccounted_pair_check='raise' finds absent pairs.
build_active_set_report(result, *, use_ids=False)
Return a JSON-friendly report for a self-consistent active-set result.
build_fit_report(result, constraints, *, use_ids=False)
Return a JSON-friendly report for a low-level fit result.
build_power_fit_problem(constraints, *, model=None)
Build a stable public power-fit problem from resolved constraints.
build_power_fit_result(problem, weights, *, solver='external', status='optimal', status_detail=None, converged=True, n_iter=0, warnings=(), canonicalize_gauge=True, r_min=0.0, weight_shift=None)
Package candidate weights into a standard power-fit result object.
build_realized_report(diagnostics, constraints, *, use_ids=False)
Return a JSON-friendly report for realized-face matching.
dumps_report_json(report, *, indent=2, sort_keys=False)
Serialize a powerfit report into a JSON string.
fit_power_weights(points, constraints, *, measurement='fraction', domain=None, ids=None, index_mode='index', image='nearest', image_search=1, confidence=None, model=None, r_min=0.0, weight_shift=None, solver='auto', max_iter=2000, rho=1.0, tol_abs=1e-06, tol_rel=1e-05, connectivity_check='warn')
Fit power weights from resolved pairwise separator constraints.
match_realized_pairs(points, *, domain, radii, constraints, return_boundary_measure=False, return_cells=False, return_tessellation_diagnostics=False, tessellation_check='diagnose', unaccounted_pair_check='diagnose')
Determine which resolved pair constraints correspond to realized boundaries.
The matching is purely geometric: each requested ordered pair (i, j, shift)
is checked against the set of realized cell boundaries in the power
tessellation, including explicit periodic image shifts.
radii_to_weights(radii)
Convert radii to power weights (w = r^2).
resolve_pair_bisector_constraints(points, constraints, *, measurement='fraction', domain=None, ids=None, index_mode='index', image='nearest', image_search=1, confidence=None, allow_empty=False)
Parse and resolve pairwise separator constraints.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
ndarray
|
Site coordinates with shape |
required |
constraints
|
ConstraintInput
|
Raw constraint tuples |
required |
measurement
|
Literal['fraction', 'position']
|
Whether |
'fraction'
|
domain
|
DomainAny | None
|
Optional non-periodic or periodic domain. |
None
|
ids
|
Sequence[int] | None
|
External ids used when |
None
|
index_mode
|
Literal['index', 'id']
|
Interpret the first two tuple entries as internal indices or external ids. |
'index'
|
image
|
Literal['nearest', 'given_only']
|
Shift resolution policy for tuples that do not specify a shift. |
'nearest'
|
image_search
|
int
|
Search radius for nearest-image resolution in triclinic periodic 3D cells. It is ignored for the current planar backend. |
1
|
confidence
|
Sequence[float] | None
|
Optional non-negative per-constraint weights. |
None
|
allow_empty
|
bool
|
Allow zero constraints and return an empty resolved object. |
False
|
solve_self_consistent_power_weights(points, constraints, *, measurement='fraction', domain, ids=None, index_mode='index', image='nearest', image_search=1, confidence=None, model=None, active0=None, options=None, r_min=0.0, weight_shift=None, fit_solver='auto', fit_max_iter=2000, fit_rho=1.0, fit_tol_abs=1e-06, fit_tol_rel=1e-05, return_history=False, return_cells=False, return_boundary_measure=False, return_tessellation_diagnostics=False, tessellation_check='diagnose', connectivity_check='warn', unaccounted_pair_check='warn')
Iteratively refine an active pair set against realized power-diagram boundaries.
weights_to_radii(weights, *, r_min=0.0, weight_shift=None)
Convert power weights to radii using an explicit global shift.
write_report_json(report, path, *, indent=2, sort_keys=False)
Write a powerfit report to a JSON file.
:::