Inverse fitting
pyvoro2.inverse is the canonical high-level namespace for fixed-observation
separator fitting. Its deliberately small public surface contains the resolved
observation container, resolver, fit result, solver entry point, and neutral
weight/radius transforms.
The six high-level names exported here are stable in v0.8. Advanced separator inspection and solver-control objects are provisional unless marked experimental in the API inventory.
Advanced objective models, problem objects, realization diagnostics, reports, and experimental active-set refinement are documented under separator-specific inverse fitting.
The high-level SeparatorFitResult keeps its flat compatibility fields and
provides .state, .identification, .observation_view(...), .objective,
.algebraic, and .solver_termination access. The concrete provisional view
types live only in pyvoro2.inverse.separator, so this package's __all__
remains deliberately small.
pyvoro2.inverse
High-level inverse fitting for weighted tessellations.
The package root intentionally exposes only the fixed-observation separator
workflow and neutral weight/radius transforms. Advanced separator models,
realization diagnostics, reports, and experimental active-set refinement live
in :mod:pyvoro2.inverse.separator.
SeparatorFitResult
dataclass
Bases: _ObservationBoundResult
Result of fitting power weights from separator observations.
algebraic
property
Return difference-space and connectivity diagnostics.
identification
property
Return data-identification and component-alignment metadata.
objective
property
Return the existing objective-contribution breakdown, if available.
solver_termination
property
Return termination metadata for the fixed-observation solver.
state
property
Return fitted weights and their backend-radius representation.
observation_view(observations)
Return diagnostics for the observations that produced this result.
Solver and problem-builder results retain a private reference to their resolved source observations. The supplied object may be that source or an independently resolved, fully equivalent observation set. The returned view shares arrays and does not copy them.
SeparatorObservations
dataclass
Bases: _ObservationIdentityStorage
Resolved pairwise separator observations.
This object is the public 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.
fit_weights_from_separators(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='direct', linear_backend='dense', admm_max_iter=2000, admm_rho=1.0, admm_abs_tol=1e-06, admm_rel_tol=1e-05, connectivity_check='warn')
Fit power weights from resolved pairwise separator observations.
solver='direct' solves a purely quadratic model directly.
solver='admm' executes ADMM whenever a component solve is required and
is required for Huber mismatch, active scalar penalties, or hard
restrictions. A no-work fit reports solver='none' and
linear_backend=None. linear_backend selects dense NumPy or
explicitly requested sparse SciPy linear algebra without size-based
switching. Zero-strength penalties are absent and do not force ADMM.
Supported numerical failure of the optional direct ADMM warm start falls
back to the reference or zero initialization.
radii_to_weights(radii)
Convert radii to finite power weights (w = r^2).
Raises ValueError when the input or its squared result is non-finite.
resolve_separator_observations(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 observations.
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 | integer] | ndarray | None
|
Unique non-negative integer external IDs aligned with |
None
|
index_mode
|
Literal['index', 'id']
|
Interpret the first two tuple entries as internal indices or external IDs. Endpoint values must be integers in either mode; floats, numeric strings, and booleans are rejected. |
'index'
|
image
|
Literal['nearest', 'given_only']
|
Shift resolution policy for tuples that do not specify a shift. |
'nearest'
|
image_search
|
int
|
Bounded incumbent-seeding hint for certified periodic nearest-image inference. It cannot change a successful result. |
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
|
weights_to_radii(weights, *, r_min=0.0, weight_shift=None)
Convert power weights to finite radii using one global shift.
Raises ValueError when an input, intermediate value, or result is
non-finite.
:::