Names you can build on.
This is a practical map of the public surface. For exact signatures and edge cases, jump from a symbol to its module in the repository.
Graph data structures
| Symbol | Use it for | Notes |
|---|---|---|
Graph[NodeT] | Undirected graph storage. | Adjacency and edge lookups are constant time. Nodes must be hashable and orderable for stable sorting. |
ThreadSafeGraph[NodeT] | Shared graph access. | Uses an RLock. Live views are not compound snapshots. |
Graph.from_edges | Build a graph from edge pairs. | Implicitly creates endpoint nodes. |
subgraph / edge_subgraph | Create derived graph values. | Returns a new graph; verify ownership when attaching attributes. |
Domain model
| Symbol | Role | Typical use |
|---|---|---|
Action | One candidate mutation. | ActionType.ADD_EDGE, remove node, or a domain-specific action. |
DeltaResult | Incremental score result. | Set reward change, penalty change, and feasibility. |
DefaultState | Small state implementation. | Use it when your problem needs no extra fields. |
UndoEntry | Rollback record. | Usually managed by the problem implementation. |
SubgraphExtractionProblem | Polymorphic domain boundary. | Subclass it for custom reward, penalty, actions, and constraints. |
Built-in problems
MaximumPlanarSubgraphProblem
Maximize retained edges with an Euler-bound feasibility heuristic. Validate planarity externally when you need a complete guarantee.
MinimumConnectedDominatingSetProblem
Find a small connected set that dominates every vertex.
MaximumWeightedIndependentSetProblem
Choose a high-weight set of mutually non-adjacent vertices.
PrizeCollectingVertexCoverProblem
Trade vertex costs against uncovered-edge penalties.
UncapacitatedFacilityLocationProblem
Choose facilities and assignments at low total cost.
MinimumWeightedSteinerTreeProblem
Connect terminals through optional nodes and edges.
Solver strategies
| Solver | Good first question |
|---|---|
GreedySolver | What does the local objective do? |
MultiStartSolver | How sensitive is the result to the initial state? |
BeamSearchSolver | Does keeping the top-k states improve quality? |
AnytimeSolver | What is the best answer under a time budget? |
AdaptiveBeamSolver | Can diversity reduce search collapse? |
LearnedGuidanceSolver | Can optional model signals guide action choice? |
MultiObjectiveSolver | Do I need a Pareto frontier? |
StreamingSolver | Can the graph change while the solver runs? |
Budgets and observability
EarlyTerminationCondition accepts max_iterations, max_evaluations, max_time_ms, objective_target, and stall_iterations. Give at least one positive limit when constructing it.
stop = EarlyTerminationCondition(
max_iterations=500,
max_time_ms=5_000,
stall_iterations=40,
)
result = GreedySolver(problem, early_stop=stop).solve(
observer=MetricsObserver(),
)Optional integrations
NetworkX conversion lives in delta_search.interop. Visualization helpers require matplotlib. Learned guidance requires scikit-learn. Install these only when you need them with pip install -e ".[all]"; core imports should remain usable without them.