qbiocode.apps.quvine.embedding.quantum_filters module

QuVINE Quantum Filters: Quantum-Calibrated Graph Diffusion

This module implements quantum-calibrated graph diffusion for QuVINE, which uses local quantum walk statistics from sampled subnetworks to calibrate parameters of global graph diffusion operators.

Key Innovation: - Run quantum walks on small subgraphs (scalable) - Fit global diffusion parameters to match quantum behavior - Apply calibrated classical operator to full graph (efficient)

Reference: - QuVINE notebook: notebooks/Q-Caliber_Quantum_Calibrated_Graph_Diffusion.ipynb - Hiperwalk: https://hiperwalk.org/

Author: QuVINE Team

Summary

Functions:

apply_heat_filter	Apply heat kernel filter: Z = exp(-t*L) @ X
apply_polynomial_filter	Apply polynomial filter: Z = sum_{k=0}^K a_k * L^k @ X
calibrate_heat_kernel	Calibrate heat kernel time parameter by matching quantum walk targets.
calibrate_polynomial_filter	Calibrate polynomial filter coefficients by least squares.
generate_baseline_filter_embedding	Generate baseline graph filter embeddings (without quantum calibration).
generate_baseline_heat_embedding	Baseline heat-kernel embedding on random features (no quantum calibration).
generate_baseline_poly_embedding	Baseline polynomial-filter embedding on random features (no quantum calibration).
generate_quvine_heat_embedding	Generate QuVINE heat kernel embeddings.
generate_quvine_poly_embedding	Generate QuVINE polynomial filter embeddings.
get_ego_net_nodes_quvine	Get ego-net nodes using QuVINE's expand_neighborhood function.
get_laplacian
importance_sample_centers	Sample m centers without replacement, stratified by degree bins.

Reference

get_laplacian(G, normalize=True, weight='weight')

get_ego_net_nodes_quvine(G, center, k=2, max_nodes=None)

Get ego-net nodes using QuVINE’s expand_neighborhood function.

Parameters:

• G – NetworkX graph

• center – Center node

• k – Hop radius

• max_nodes – Maximum number of nodes (optional truncation)

Returns:

List of nodes in the ego-net

importance_sample_centers(G, m, exclude={}, bins=6, seed=0)

Sample m centers without replacement, stratified by degree bins.

Parameters:

• G – NetworkX graph

• m – Number of centers to sample

• exclude – Set of nodes to exclude

• bins – Number of degree bins for stratification

• seed – Random seed

Returns:

List of sampled center nodes

calibrate_heat_kernel(L, q_targets, t_grid, node_to_idx, loss='l2')

Calibrate heat kernel time parameter by matching quantum walk targets.

Fits the parameter t in g_t(L) = exp(-t*L) by minimizing the loss between heat kernel diffusion and quantum walk probability distributions on subnetworks.

Parameters:

• L (Union[ndarray, spmatrix]) – Laplacian matrix of the full graph

• q_targets (List[Dict]) – List of quantum walk target distributions, each containing: - ‘nodes’: List of node IDs in subnetwork - ‘center’: Center node ID - ‘pQ’: Quantum walk probability distribution

• t_grid (ndarray) – Grid of time values to search over

• node_to_idx (Dict[int, int]) – Dictionary mapping node IDs to matrix indices

• loss (str) – Loss function (‘l2’ or ‘kl’)

Return type:

Tuple[float, float]

Returns:

Tuple of (best_loss, best_t)

Example

>>> L = nx.laplacian_matrix(G).astype(float)
>>> q_targets = [{'nodes': [0,1,2], 'center': 0, 'pQ': np.array([0.5, 0.3, 0.2])}]
>>> t_grid = np.linspace(0.1, 5.0, 20)
>>> node_to_idx = {i: i for i in range(G.number_of_nodes())}
>>> loss_val, t_star = calibrate_heat_kernel(L, q_targets, t_grid, node_to_idx)

calibrate_polynomial_filter(L, q_targets, node_to_idx, K=4, ridge=1e-06)

Calibrate polynomial filter coefficients by least squares.

Fits coefficients {a_k} in g(L) = sum_{k=0}^K a_k * L^k by minimizing the squared error between polynomial filter output and quantum walk targets.

Parameters:

• L (Union[ndarray, spmatrix]) – Laplacian matrix of the full graph

• q_targets (List[Dict]) – List of quantum walk target distributions (same format as calibrate_heat_kernel)

• node_to_idx (Dict[int, int]) – Dictionary mapping node IDs to matrix indices

• K (int) – Polynomial degree (number of terms - 1)

• ridge (float) – Ridge regularization parameter

Return type:

ndarray

Returns:

Array of polynomial coefficients [a_0, a_1, …, a_K]

Example

>>> coeffs = calibrate_polynomial_filter(L, q_targets, node_to_idx, K=4)
>>> print(f"Polynomial coefficients: {coeffs}")

apply_heat_filter(L, X, t)

Apply heat kernel filter: Z = exp(-t*L) @ X

Parameters:

• L (Union[ndarray, spmatrix]) – Laplacian matrix

• X (ndarray) – Node features [N, d]

• t (float) – Time parameter

Return type:

ndarray

Returns:

Filtered features [N, d]

apply_polynomial_filter(L, X, coeffs)

Apply polynomial filter: Z = sum_{k=0}^K a_k * L^k @ X

Uses Horner’s method for efficient computation.

Parameters:

• L (Union[ndarray, spmatrix]) – Laplacian matrix

• X (ndarray) – Node features [N, d]

• coeffs (ndarray) – Polynomial coefficients [a_0, a_1, …, a_K]

Return type:

ndarray

Returns:

Filtered features [N, d]

generate_quvine_heat_embedding(G, q_targets, t_grid=None, embedding_dim=128, use_features=False, features=None, normalize=True, random_state=42)

Generate QuVINE heat kernel embeddings.

Workflow: 1. Calibrate heat kernel time parameter using quantum walk targets 2. Apply calibrated heat kernel to node features 3. Return filtered features as embeddings

Parameters:

• G (Graph) – NetworkX graph

• q_targets (List[Dict]) – List of quantum walk target distributions

• t_grid (Optional[ndarray]) – Grid of time values to search (default: np.linspace(0.1, 5.0, 20))

• embedding_dim (int) – Embedding dimension (used if generating random features)

• use_features (bool) – Whether to use provided features or generate random ones

• features (Optional[ndarray]) – Node features [N, d] (optional)

• normalize (bool) – Whether to normalize Laplacian

• random_state (int) – Random seed

Return type:

ndarray

Returns:

Node embeddings [N, embedding_dim]

generate_quvine_poly_embedding(G, q_targets, K=4, ridge=1e-06, embedding_dim=128, use_features=False, features=None, normalize=True, random_state=42)

Generate QuVINE polynomial filter embeddings.

Workflow: 1. Calibrate polynomial filter coefficients using quantum walk targets 2. Apply calibrated polynomial filter to node features 3. Return filtered features as embeddings

Parameters:

• G (Graph) – NetworkX graph

• q_targets (List[Dict]) – List of quantum walk target distributions

• K (int) – Polynomial degree

• ridge (float) – Ridge regularization parameter

• embedding_dim (int) – Embedding dimension (used if generating random features)

• use_features (bool) – Whether to use provided features or generate random ones

• features (Optional[ndarray]) – Node features [N, d] (optional)

• normalize (bool) – Whether to normalize Laplacian

• random_state (int) – Random seed

Return type:

ndarray

Returns:

Node embeddings [N, embedding_dim]

generate_baseline_filter_embedding(G, filter_type='heat', t=1.0, K=4, embedding_dim=128, use_features=False, features=None, normalize=True, random_state=42)

Generate baseline graph filter embeddings (without quantum calibration).

This serves as a baseline to compare against QuVINE methods.

Parameters:

• G (Graph) – NetworkX graph

• filter_type (str) – Type of filter (‘heat’ or ‘poly’)

• t (float) – Time parameter for heat kernel (if filter_type=’heat’)

• K (int) – Polynomial degree (if filter_type=’poly’)

• embedding_dim (int) – Embedding dimension

• use_features (bool) – Whether to use provided features or generate random ones

• features (Optional[ndarray]) – Node features [N, d] (optional)

• normalize (bool) – Whether to normalize Laplacian

• random_state (int) – Random seed

Return type:

ndarray

Returns:

Node embeddings [N, embedding_dim]

generate_baseline_heat_embedding(G, embedding_dim=128, scale=1.0, normalize=True, random_state=42)

Baseline heat-kernel embedding on random features (no quantum calibration).

Return type:

ndarray

generate_baseline_poly_embedding(G, embedding_dim=128, order=4, normalize=True, random_state=42)

Baseline polynomial-filter embedding on random features (no quantum calibration).

Return type:

ndarray