Skip to content

Choosing an API

pyvoro2 has one normal forward path and one normal separator-inverse path. The advanced separator namespace serves narrower research workflows; the v0.7 compatibility namespaces are no longer part of the package.

Forward computation

Choose the namespace by dimension:

import pyvoro2 as pv          # 3D
import pyvoro2.planar as pv2  # 2D

Use compute(...) and keep its default structured result:

result3d = pv.compute(points3d, domain=domain3d)
result2d = pv2.compute(points2d, domain=domain2d)

Both calls return the same stable TessellationResult class. Use its aligned arrays and capability checks for normal downstream work. Application code should receive this result from compute(...); direct construction remains provisional and is not a backend-record normalization or geometric-verification API.

Select output='cells' only when a low-level workflow intentionally wants the raw backend-shaped cell dictionaries:

cells = pv.compute(points3d, domain=domain3d, output='cells')

This is an explicit supported output mode, not the recommended general result container.

For power diagrams, prefer mathematical weights:

result = pv.compute(
    points3d,
    domain=domain3d,
    mode='power',
    weights=weights,
)

Use radii= only when backend-compatible radii are already the data you have. Weights are the mathematical power parameters; radii are a non-unique shifted representation used by Voro++.

Separator inverse fitting

Normal high-level path

Use pyvoro2.inverse for fixed-observation separator fitting:

import pyvoro2.inverse as inverse

observations = inverse.resolve_separator_observations(
    points,
    rows,
    domain=domain,
)
fit = inverse.fit_weights_from_separators(
    points,
    observations,
)

This stable surface intentionally contains only:

  • SeparatorObservations;
  • resolve_separator_observations;
  • SeparatorFitResult;
  • fit_weights_from_separators;
  • weights_to_radii and radii_to_weights.

It is the preferred path for applications and downstream packages.

Advanced separator research path

Use pyvoro2.inverse.separator when you need explicit model pieces, exported problem/operator views, realization matching, reports, or the experimental active-set outer loop:

import pyvoro2.inverse.separator as separator

model = separator.FitModel(
    mismatch=separator.HuberLoss(delta=0.02),
)
fit = separator.fit_weights_from_separators(
    points,
    observations,
    model=model,
    solver='admm',
)

Most of this larger surface is provisional. The active-set workflow is experimental and has no universal convergence guarantee.

Removed v0.7 compatibility path

pyvoro2.powerfit, broad top-level separator exports, and historical separator names were compatibility-only routes in v0.7 and are absent in v0.8. Use pyvoro2.inverse or pyvoro2.inverse.separator.

See the v0.6.3–v0.8 migration guide for exact replacements.

Feature and lifecycle status

Capability v0.8 lifecycle Recommended use
2D/3D domains and compute, locate, ghost_cells Stable Normal public API
weights= and radii= power input semantics Stable Prefer weights= for mathematical workflows
TessellationResult core fields and output='cells' Stable Default structured result; raw output when intentionally needed
Diagnostics, validation, normalization, duplicate checks, face/edge annotations Stable Normal scientific workflow
Visualization helpers Provisional Optional inspection convenience
pyvoro2.inverse high-level separator workflow Stable Normal inverse API
Advanced objective, problem, operator, realization, and report objects in pyvoro2.inverse.separator Provisional Research and specialized downstream use
Explicit SciPy sparse quadratic separator backend Provisional Large static sparse quadratic observation graphs
Realization-aware active-set refinement Experimental Opt-in diagnostic outer algorithm
v0.7-only inverse and planar compatibility routes Removed in v0.8 Follow the migration guide
v0.8 cleanup and compatibility removal Implemented maintenance scope No new numerical features
v0.9 functional/API stabilization Planned before 1.0 Refines existing forward, periodic, and separator workflows
Prescribed cell areas/volumes Planned for v1.1 Not implemented
Mixed separator and cell-measure fitting Planned for v1.2 Not implemented

The complete name-by-name contract is in the v0.8 API inventory. The capabilities and limitations page separates supported behavior from removable wrapper restrictions and backend limitations.

Static scalability contract

The current API supports large static sparse separator-observation graphs through the explicit SciPy-backed quadratic path when its model restrictions are satisfied. The supported scalable regime is a locality graph with observation count that remains sparse relative to all possible site pairs.

The following are not implied:

  • scalable dense or arbitrary all-pairs observation graphs;
  • automatic sparse-backend selection;
  • sparse execution for Huber, hard-constrained, positive-strength penalty, or active-set branches;
  • prepared solvers or warm starts across changing frames;
  • molecular-dynamics trajectory throughput;
  • parallel forward tessellation, multiprocessing ownership semantics, GPU, or distributed execution.

Trajectory-scale and parallel workflow design is explicitly deferred until post-1.0 evidence identifies where that responsibility belongs.

Result-layer map

A separator workflow can produce several related but distinct kinds of data:

resolved observations
        |
        v
fixed-observation fit
        +--> fitted state and backend representation
        +--> observation predictions and objective values
        +--> identification, graph, incidence, and operator diagnostics
        +--> fixed-solver termination
        |
        v  optional forward realization
realized geometry
        +--> requested-image / other-image / unrealized matching
        +--> cells, boundaries, measures, and empty-cell diagnostics
        |
        v  optional experimental outer loop
active-set path and outer termination

A small algebraic residual does not prove that the requested pair is a realized face. The realized geometry is not part of the exact fixed-observation solve, and active-set refinement is a separate experimental outer algorithm.

The separator-fitting guide explains the layers in detail. The glossary defines the recurring terms.