API reference · Axiom

Constructor

This page covers the Basic and Multilevel Matcher API. For thread-safe durable integration and its current qualification status, see Service, durability and qualification. Compact native Packed storage is not a separate matcher.

Matcher(n: int, mode: "basic" | "multilevel")

Argument	Meaning
`n`	Number of vertices. Vertices are integers in `[0, n)`.
`mode`	Exactly `basic` or `multilevel`.

Updates

Method	Behavior
`insert(u, v)`	Adds an existing or new graph edge and repairs the matching.
`delete(u, v)`	Removes an existing graph edge and repairs any affected matching state.

Update semantics

insert(u, v) ignores a duplicate edge after validating its endpoints.
delete(u, v) records a missing-edge deletion without changing the graph.
Self-loops are outside the graph model and do not become matching edges.
A failed update is atomic: callers do not receive a partially applied state.

Inspection

matcher.matching()  # matching edge snapshot
matcher.size()      # number of matching edges
matcher.maximal()   # invariant check
matcher.stats()     # update and rebuild ledger

Inspection methods are read-only from the caller’s perspective. Treat returned collections as snapshots and continue to mutate the graph through insert and delete.

Method	Returns	Use	Cost
`partner(v)`	`int \| None`	Return the matched neighbor or `None`.	O(1)
`partners()`	`dict[int, int]`	Return a copy of the full partner map.	O(\|M*\|)
`matching()`	`set[Edge]`	Return a copy of the current matching.	O(\|M*\|)
`size()`	`int`	Return the number of matching edges.	O(1)
`maximal()`	`bool`	Check the matching against the current graph.	O(n + m)
`stats()`	`dict[str, int]`	Return counters and active schedule values.	O(1)

`stats()` schema

Key	Meaning
`n`, `m`	Vertex and live-edge counts at the time of the snapshot.
`matching_size`	Number of edges in the maintained maximal matching.
`updates_since_rebuild`	Updates applied since the active phase rebuild.
`phase_length`, `subphase_length`	Configured rebuild and seed-maintenance boundaries.
`subphase_count`	Number of subphase maintenance events completed.
`z`	Active saturation threshold for the current mode.
`total_updates`, `total_insertions`, `total_deletions`	Cumulative accepted update counters.
`phase_rebuilds`, `subphase_rebuilds`	Cumulative phase and subphase maintenance counts.
`rematch_*_scans`, `stale_cleanups`	Empirical work counters for rematching and removed matching edges.

Validation and failure

Invalid vertices, malformed edges, and unsupported modes are rejected explicitly. Duplicate insertions and missing deletions follow the documented no-op semantics. A failed update must not expose a partially applied graph or matching state.

Condition	Result
Invalid `n`, vertex, mode, graph, or colorer	`ValueError` before state changes.
Duplicate insertion, missing deletion, or self-loop update	Validated no-op; the graph and matching remain unchanged.
Internal repair or invariant failure	`RuntimeError` after atomic rollback; inspect the diagnostic and preserve the input trace.

For reproducible experiments, record the mode, vertex count, update sequence, and stats() ledger alongside your result.

Custom implementations and concurrency

The optional graph and basic-mode colorer parameters are extension points for compatible implementations. A custom graph must preserve the graph protocol and edge-set semantics; a multilevel matcher always uses its canonical paper-oriented colorer.

Thread safety: a matcher is stateful and is not designed for concurrent mutation. Serialize updates per instance. Use independent matcher instances for parallel experiments.

NextRun examples