Quantum Geometry Trainer API

The QuantumGeometryTrainer is the flagship class that integrates all advanced quantum geometric features for comprehensive data analysis.

Overview

The quantum geometry trainer extends the base framework with sophisticated topological and quantum information analysis capabilities:

Matrix Laplacian computation for spectral analysis
Quantum fluctuation control with variance-based regularization
Eigenmap analysis for dimension reduction
Berry curvature fields over parameter space
Chern number calculation for topological invariants
Quantum information measures (entropy, Fisher information, coherence)

Core Classes

QuantumGeometryTrainer

class qgml.geometry.quantum_geometry_trainer.QuantumGeometryTrainer(N: int, D: int, fluctuation_weight: float = 1.0, topology_weight: float = 0.1, n_eigenmaps: int | None = None, **kwargs)[source]

Bases: BaseQuantumMatrixTrainer

Advanced QMML trainer with quantum geometric structures.

Extends the base framework with: - Matrix Laplacian: Δ = Σₐ [Xₐ, [Xₐ, ·]] - Quantum fluctuation control: σ²(x) analysis - Eigenmap analysis and dimension reduction - Topological invariant computation - Advanced loss functions with geometric terms

__init__(N: int, D: int, fluctuation_weight: float = 1.0, topology_weight: float = 0.1, n_eigenmaps: int | None = None, **kwargs)[source]

Initialize quantum geometry trainer.

Parameters:

N – Hilbert space dimension
D – Feature space dimension
fluctuation_weight – Weight for quantum fluctuation terms
topology_weight – Weight for topological penalty
n_eigenmaps – Number of eigenmaps to compute (None = all)
**kwargs – Additional base class arguments

invalidate_geometry_cache()[source]: Invalidate cached geometric structures when operators change.

compute_matrix_laplacian() → Tensor[source]

Compute matrix Laplacian: Δ = Σₐ [Xₐ, [Xₐ, ·]]

The matrix Laplacian encodes the quantum geometric structure and is used for spectral analysis and dimension estimation.

Returns:: Matrix Laplacian as (N²×N²) tensor representing the operator

compute_eigenmaps() → Tuple[Tensor, Tensor][source]

Compute eigenmaps of the matrix Laplacian.

Eigenmaps provide a spectral decomposition of the quantum geometry and are used for dimension reduction and topological analysis.

Returns:

eigenvalues: Real eigenvalues sorted ascending, shape (n_modes,)
eigenmaps: Eigenmap matrices, shape (n_modes, N, N)

Return type:

Tuple of (eigenvalues, eigenmaps)

compute_quantum_fluctuations(x: Tensor) → Dict[str, Tensor][source]

Compute quantum fluctuations σ²(x) = Σₐ (⟨Xₐ²⟩ - ⟨Xₐ⟩²).

Quantum fluctuations measure the quantum uncertainty in the encoding and are crucial for the quantum geometric loss function.

Parameters:

x – Input point of shape (D,)

Returns:

total_variance: Total quantum fluctuation σ²(x)
individual_variances: Per-operator variances σₐ²(x)
expectations: Operator expectations ⟨Xₐ⟩
ground_state_energy: 2λ(x) = σ²(x) + d²(x)
displacement_error: d²(x) = ||⟨X⟩ - x||²

Return type:

Dictionary with fluctuation analysis

compute_quantum_geometry_loss(points: Tensor) → Dict[str, Tensor][source]

Compute quantum geometry loss: L = Σᵢ [d²(xᵢ) + w·σ²(xᵢ)] + λ·topology.

This extends the basic QCML loss with quantum fluctuation control and topological constraints.

Parameters:: points – Batch of input points, shape (batch_size, D)
Returns:: Dictionary with loss components

estimate_intrinsic_dimension_weyl(lambda_max: float | None = None, n_points: int = 50) → Dict[str, Any][source]

Estimate intrinsic dimension using Weyl’s law: N(λ) ~ λ^(d/2).

This provides a quantum geometric approach to dimension estimation based on the eigenvalue density of the matrix Laplacian.

Parameters:

lambda_max – Maximum eigenvalue to consider (None = auto)
n_points – Number of points for eigenvalue counting

Returns:

Dictionary with dimension estimation results

compute_commutation_penalty() → Tensor[source]

Enhanced commutation penalty including geometric terms.

Extends the base commutation penalty with additional geometric constraints for smoother quantum geometry.

analyze_quantum_geometry(points: Tensor, compute_berry: bool = False) → Dict[str, Any][source]

Comprehensive quantum geometric analysis.

Parameters:

points – Sample points for analysis
compute_berry – Whether to compute Berry curvature (expensive)

Returns:

Dictionary with complete geometric analysis

compute_berry_curvature_field(x_grid: Tensor, mu: int = 0, nu: int = 1) → Tensor[source]

Compute Berry curvature field using topological analyzer.

Parameters:

x_grid – Grid of parameter points, shape (N_x, N_y, D)
mu – Parameter directions for curvature
nu – Parameter directions for curvature

Returns:

Berry curvature field, shape (N_x, N_y)

compute_chern_number(closed_path: Tensor, mu: int = 0, nu: int = 1) → Tensor[source]

Compute Chern number using topological analyzer.

Parameters:

closed_path – Points defining closed path, shape (N_points, D)
mu – Parameter directions for integration
nu – Parameter directions for integration

Returns:

Chern number (topological invariant)

detect_quantum_phase_transitions(parameter_path: Tensor, threshold: float = 0.1) → Dict[str, Any][source]

Detect quantum phase transitions using topological analyzer.

Parameters:

parameter_path – Path through parameter space
threshold – Threshold for detecting transitions

Returns:

Dictionary with transition analysis

compute_quantum_fisher_information_matrix(x: Tensor) → Tensor[source]

Compute quantum Fisher information matrix using quantum info analyzer.

Parameters:: x – Parameter point
Returns:: Fisher information matrix

compute_von_neumann_entropy(x: Tensor) → Tensor[source]

Compute von Neumann entropy of ground state.

Parameters:: x – Parameter point
Returns:: Von Neumann entropy

compute_entanglement_entropy(x: Tensor, subsystem_dims: Tuple[int, int] | None = None) → Tensor[source]

Compute entanglement entropy between subsystems.

Parameters:

x – Parameter point
subsystem_dims – Bipartition dimensions (auto-detected if None)

Returns:

Entanglement entropy

analyze_complete_quantum_geometry(points: Tensor, compute_topology: bool = True, compute_information: bool = True, output_dir: str | None = None) → Dict[str, Any][source]

Complete quantum geometric analysis combining all advanced features.

Parameters:

points – Sample points for analysis
compute_topology – Whether to compute topological properties
compute_information – Whether to compute quantum information measures
output_dir – Directory for saving visualizations

Returns:

Comprehensive analysis dictionary

forward(x: Tensor) → Tensor[source]

Forward pass - returns quantum geometry embedding.

Parameters:: x – Input point
Returns:: Quantum geometric embedding (expectations + fluctuation info)

compute_loss(points: Tensor) → Tensor[source]

Compute quantum geometry loss.

Parameters:: points – Batch of training points
Returns:: Total quantum geometry loss

Mathematical Foundation

Error Hamiltonian

The core mathematical object is the error Hamiltonian:

\[H(x) = \frac{1}{2} \sum_{k=1}^{D} (A_k - x_k I)^2\]

where: - \(A_k\) are the learned Hermitian feature operators - \(x_k\) are the components of the input data point - \(I\) is the identity matrix

The ground state \(|\psi_0(x)\rangle\) minimizes this Hamiltonian and encodes the classical data in quantum form.

Quantum Fluctuations

Quantum fluctuations measure the uncertainty in the quantum encoding:

\[\sigma^2(x) = \sum_k \sigma_k^2(x), \quad \sigma_k^2(x) = \langle \psi_0 | A_k^2 | \psi_0 \rangle - \langle \psi_0 | A_k | \psi_0 \rangle^2\]

Enhanced Loss Function

The quantum geometric loss combines displacement and fluctuation terms:

\[L = \sum_i \left[ d^2(x_i) + w \cdot \sigma^2(x_i) \right] + \lambda \cdot P_{\text{topology}}\]

where: - \(d^2(x) = \|\langle A \rangle - x\|^2\) is the reconstruction error - \(\sigma^2(x)\) controls quantum fluctuations - \(P_{\text{topology}}\) is a topological penalty term

Matrix Laplacian

The matrix Laplacian encodes the quantum geometric structure:

\[\Delta = \sum_k [A_k, [A_k, \cdot]]\]

Its eigendecomposition provides eigenmaps for dimension reduction and topological analysis.

Key Methods

Core Quantum Operations

QuantumGeometryTrainer.compute_quantum_fluctuations(x: Tensor) → Dict[str, Tensor][source]

Compute quantum fluctuations σ²(x) = Σₐ (⟨Xₐ²⟩ - ⟨Xₐ⟩²).

Quantum fluctuations measure the quantum uncertainty in the encoding and are crucial for the quantum geometric loss function.

Parameters:

x – Input point of shape (D,)

Returns:

total_variance: Total quantum fluctuation σ²(x)
individual_variances: Per-operator variances σₐ²(x)
expectations: Operator expectations ⟨Xₐ⟩
ground_state_energy: 2λ(x) = σ²(x) + d²(x)
displacement_error: d²(x) = ||⟨X⟩ - x||²

Return type:

Dictionary with fluctuation analysis

QuantumGeometryTrainer.compute_matrix_laplacian() → Tensor[source]

Compute matrix Laplacian: Δ = Σₐ [Xₐ, [Xₐ, ·]]

The matrix Laplacian encodes the quantum geometric structure and is used for spectral analysis and dimension estimation.

Returns:: Matrix Laplacian as (N²×N²) tensor representing the operator

QuantumGeometryTrainer.compute_eigenmaps() → Tuple[Tensor, Tensor][source]

Compute eigenmaps of the matrix Laplacian.

Eigenmaps provide a spectral decomposition of the quantum geometry and are used for dimension reduction and topological analysis.

Returns:

eigenvalues: Real eigenvalues sorted ascending, shape (n_modes,)
eigenmaps: Eigenmap matrices, shape (n_modes, N, N)

Return type:

Tuple of (eigenvalues, eigenmaps)

QuantumGeometryTrainer.estimate_intrinsic_dimension_weyl(lambda_max: float | None = None, n_points: int = 50) → Dict[str, Any][source]

Estimate intrinsic dimension using Weyl’s law: N(λ) ~ λ^(d/2).

This provides a quantum geometric approach to dimension estimation based on the eigenvalue density of the matrix Laplacian.

Parameters:

lambda_max – Maximum eigenvalue to consider (None = auto)
n_points – Number of points for eigenvalue counting

Returns:

Dictionary with dimension estimation results

Topological Analysis

QuantumGeometryTrainer.compute_berry_curvature_field(x_grid: Tensor, mu: int = 0, nu: int = 1) → Tensor[source]

Compute Berry curvature field using topological analyzer.

Parameters:

x_grid – Grid of parameter points, shape (N_x, N_y, D)
mu – Parameter directions for curvature
nu – Parameter directions for curvature

Returns:

Berry curvature field, shape (N_x, N_y)

QuantumGeometryTrainer.compute_chern_number(closed_path: Tensor, mu: int = 0, nu: int = 1) → Tensor[source]

Compute Chern number using topological analyzer.

Parameters:

closed_path – Points defining closed path, shape (N_points, D)
mu – Parameter directions for integration
nu – Parameter directions for integration

Returns:

Chern number (topological invariant)

QuantumGeometryTrainer.detect_quantum_phase_transitions(parameter_path: Tensor, threshold: float = 0.1) → Dict[str, Any][source]

Detect quantum phase transitions using topological analyzer.

Parameters:

parameter_path – Path through parameter space
threshold – Threshold for detecting transitions

Returns:

Dictionary with transition analysis

Quantum Information

QuantumGeometryTrainer.compute_von_neumann_entropy(x: Tensor) → Tensor[source]

Compute von Neumann entropy of ground state.

Parameters:: x – Parameter point
Returns:: Von Neumann entropy

QuantumGeometryTrainer.compute_entanglement_entropy(x: Tensor, subsystem_dims: Tuple[int, int] | None = None) → Tensor[source]

Compute entanglement entropy between subsystems.

Parameters:

x – Parameter point
subsystem_dims – Bipartition dimensions (auto-detected if None)

Returns:

Entanglement entropy

QuantumGeometryTrainer.compute_quantum_fisher_information_matrix(x: Tensor) → Tensor[source]

Compute quantum Fisher information matrix using quantum info analyzer.

Parameters:: x – Parameter point
Returns:: Fisher information matrix

Comprehensive Analysis

QuantumGeometryTrainer.analyze_complete_quantum_geometry(points: Tensor, compute_topology: bool = True, compute_information: bool = True, output_dir: str | None = None) → Dict[str, Any][source]

Complete quantum geometric analysis combining all advanced features.

Parameters:

points – Sample points for analysis
compute_topology – Whether to compute topological properties
compute_information – Whether to compute quantum information measures
output_dir – Directory for saving visualizations

Returns:

Comprehensive analysis dictionary

Usage Examples

Basic Quantum Geometry Analysis

import torch
from qgml.geometry.quantum_geometry_trainer import QuantumGeometryTrainer

# Initialize trainer
trainer = QuantumGeometryTrainer(
    N=8, D=2,
    fluctuation_weight=1.0,
    topology_weight=0.1
)

# Sample data point
x = torch.tensor([0.5, -0.3])

# Analyze quantum fluctuations
fluctuations = trainer.compute_quantum_fluctuations(x)
print(f"Total variance: {fluctuations['total_variance']}")
print(f"Displacement error: {fluctuations['displacement_error']}")

Berry Curvature Field Computation

# Create 2D parameter grid
n_grid = 10
x_range = torch.linspace(-1, 1, n_grid)
y_range = torch.linspace(-1, 1, n_grid)
X, Y = torch.meshgrid(x_range, y_range, indexing='ij')

grid_points = torch.zeros((n_grid, n_grid, 2))
grid_points[:, :, 0] = X
grid_points[:, :, 1] = Y

# Compute Berry curvature field
curvature_field = trainer.compute_berry_curvature_field(grid_points, 0, 1)

# Visualize
import matplotlib.pyplot as plt
plt.imshow(curvature_field, origin='lower', cmap='RdBu_r')
plt.colorbar(label='Berry Curvature Ω₁₂')
plt.title('Berry Curvature Field')
plt.show()

Intrinsic Dimension Estimation

# Compute eigenmaps of matrix Laplacian
eigenvalues, eigenmaps = trainer.compute_eigenmaps()

# Estimate intrinsic dimension using Weyl's law
dim_results = trainer.estimate_intrinsic_dimension_weyl()

print(f"Estimated intrinsic dimension: {dim_results['estimated_dimension']}")
print(f"Confidence: {dim_results['confidence']}")

Complete Quantum Geometric Analysis

# Generate sample manifold data
n_points = 50
t = torch.linspace(0, 2*np.pi, n_points)
manifold_data = torch.stack([
    torch.cos(t) + 0.1*torch.randn(n_points),
    torch.sin(t) + 0.1*torch.randn(n_points)
], dim=1)

# Comprehensive analysis
analysis = trainer.analyze_complete_quantum_geometry(
    manifold_data,
    compute_topology=True,
    compute_information=True,
    output_dir="geometry_analysis"
)

# Extract key insights
topology = analysis['topology']
info = analysis['quantum_information']
insights = analysis['insights']

print("Topological Properties:")
print(f"  Berry curvature: {topology.get('sample_berry_curvature', 'N/A')}")
print(f"  Quantum metric trace: {topology.get('quantum_metric_trace', 'N/A')}")

print("Quantum Information:")
print(f"  Von Neumann entropy: {info['von_neumann_entropy']}")
print(f"  Information capacity: {info['capacity_measures']['information_capacity']}")

print("Geometric Insights:")
for key, value in insights.items():
    print(f"  {key}: {value}")

Performance Considerations

Computational Complexity

The computational complexity of key operations:

Ground state computation: \(O(N^3)\) per eigendecomposition
Berry curvature field: \(O(G^2 \cdot N^3)\) for \(G \times G\) grid
Matrix Laplacian eigenmaps: \(O(N^6)\) for full eigendecomposition
Quantum Fisher information: \(O(D^2 \cdot N^3)\) for \(D\) parameters

Memory Requirements

Feature operators: \(D \cdot N^2\) complex numbers
Matrix Laplacian: \(N^4\) complex numbers (can be large!)
Eigenmap cache: \(n_{\text{modes}} \cdot N^2\) complex numbers

Optimization Tips

Limit eigenmap computation: Set n_eigenmaps to reduce memory usage
Use caching: Enable geometry caching for repeated analysis
Batch processing: Process multiple points together when possible
GPU acceleration: Move computations to GPU for larger problems

# Memory-efficient configuration
trainer = QuantumGeometryTrainer(
    N=8,  # Keep moderate for memory
    D=2,
    n_eigenmaps=10,  # Limit eigenmap computation
    device='cuda' if torch.cuda.is_available() else 'cpu'
)

Quantum Geometry Trainer API

Overview

Core Classes

QuantumGeometryTrainer

Mathematical Foundation

Error Hamiltonian

Quantum Fluctuations

Enhanced Loss Function

Matrix Laplacian

Key Methods

Core Quantum Operations

Topological Analysis

Quantum Information

Comprehensive Analysis

Usage Examples

Basic Quantum Geometry Analysis

Berry Curvature Field Computation

Intrinsic Dimension Estimation

Complete Quantum Geometric Analysis

Performance Considerations

Computational Complexity

Memory Requirements

Optimization Tips

See Also