qbiocode.apps.quvine.api.targets module#

Quantum-target construction for quantum-calibrated registry methods.

build_walk_targets is the real, walk-based target generator used by quvine.embed(): for each calibration seed it samples a local subgraph and runs the requested walk (CTQW/DTQW via hiperwalk, or classical RWR) to produce the probability distribution pQ that the heat/poly filter is calibrated to. This is the same construction the HPC engine (comprehensive_embedding_analysis._generate_quantum_targets) uses, so the ctqw/dtqw/rwr variants produce genuinely different calibrations.

select_calibration_seeds infers dispersed, traversal-useful calibration centers (farthest-point / k-center landmarks) when the caller passes none.

build_quantum_targets is the legacy index-distance stub, kept only for backward compatibility; embed() no longer uses it.

Summary#

Functions:

build_quantum_targets

DEPRECATED — use build_walk_targets().

build_walk_targets

Build real walk-based calibration targets.

select_calibration_seeds

Select dispersed, traversal-useful calibration seeds via farthest-point (k-center) landmark selection.

Reference#

select_calibration_seeds(G, k=None, seed=0)[source]#

Select dispersed, traversal-useful calibration seeds via farthest-point (k-center) landmark selection.

A naive “top-k degree” choice tends to pick mutually-adjacent hub nodes in one dense core, giving overlapping calibration subgraphs. Instead: anchor on the highest-degree node, then greedily add the node that is farthest (in shortest-path hops) from the already-selected set, maintaining a running nearest-landmark-distance array. This guarantees the landmarks are pairwise non-adjacent (>=2 hops) and spread across the graph.

Cost is K BFS sweeps total (O(K*(V+E))) using scipy CSR BFS; runs per-connected-component so disconnected graphs still get coverage.

Parameters:

  • G (Graph) – graph.

  • k (Optional[int]) – number of landmarks; defaults to max(3, min(10, n // 20)).

  • seed (int) – reserved for reproducibility (selection is deterministic).

Return type:

List

Returns:

List of node ids (the graph’s own labels).

build_walk_targets(G, seeds, walk_type='ctqw', num_subgraphs=5, subgraph_size=20, steps=20, seed=42)[source]#

Build real walk-based calibration targets.

For up to num_subgraphs seeds, expand a <=2-hop subgraph (capped at subgraph_size, restricted to the component containing the center), run the requested walk from the center, and record the node-probability distribution as pQ. The returned {"nodes","center","pQ"} dicts satisfy the contract validated by gat.calibrate_heat_kernel / calibrate_polynomial_filter.

Parameters:

  • G (Graph) – graph.

  • seeds (Sequence) – calibration center node ids (only those present are used).

  • walk_type (str) – "ctqw" | "dtqw" (need hiperwalk) | "rwr" (classical).

  • num_subgraphs (int) – sampling controls.

  • subgraph_size (int) – sampling controls.

  • steps (int) – sampling controls.

  • seed (int) – RNG seed for subgraph sampling (deterministic).

Return type:

Optional[List[Dict]]

Returns:

List of target dicts, or None if no valid seed is present.

Raises:

  • QuvineMethodError – if walk_type is ctqw/dtqw but hiperwalk is missing.

  • ValueError – on unknown walk_type.

build_quantum_targets(graph, seeds, max_support=64)[source]#

DEPRECATED — use build_walk_targets(). This builds a walk-AGNOSTIC placeholder (pQ from node-index distance), so it cannot distinguish ctqw/dtqw/rwr. Kept only for backward compatibility; embed() no longer calls it.

Build per-seed quantum targets used to calibrate quantum filters.

For each valid seed, collect its <=2-hop neighborhood (capped at max_support nodes) and assign a normalized inverse-distance target distribution pQ over that support.

Parameters:

  • graph (Graph) – NetworkX graph.

  • seeds (Sequence) – Seed node ids (only those present in the graph are used).

  • max_support (int) – Maximum number of support nodes per seed.

Return type:

Optional[List[dict]]

Returns:

A list of {"nodes", "center", "pQ"} dicts, or None if no seed is present in the graph.