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 for v0.7. 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
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='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 observations.
solver='auto' keeps the dense analytic quadratic default and selects
ADMM only when the model requires it. solver='sparse' explicitly uses
optional SciPy sparse-direct solving for unconstrained squared loss with
optional L2 regularization.
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] | 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
|
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.
:::