API Reference

Python API documentation for the CV Cluster-State Compiler

class ClusterCompiler

Core Module

Main compiler class for CV cluster state generation and optimization.

from cv_cluster import ClusterCompiler

compiler = ClusterCompiler(
    graph="square",
    num_modes=4,
    squeezing_dB=6.0,
    mesh_architecture="clements"
)

result = compiler.optimize_phases()
print(f"Avg nullifier variance: {result.avg_variance:.3f} SNU")
__init__(graph, num_modes, squeezing_dB, mesh_architecture="clements")

Initialize compiler with target graph and hardware parameters.

optimize_phases(method="L-BFGS-B", tol=1e-6)

Run phase optimization to minimize nullifier variance. Returns OptimizationResult.

compute_nullifier_variances(phases=None)

Calculate nullifier variances for given phases. Returns array of N variances.

get_covariance_matrix(phases=None)

Compute output 2N×2N covariance matrix after mesh transformation.

class GraphState

Graph Module

Represents a CV cluster state graph with adjacency matrix and nullifiers.

from cv_cluster.graph import GraphState

# Create from preset
g = GraphState.square(4)
g = GraphState.hexagonal(7)
g = GraphState.ghz_rail(8)

# Or custom adjacency matrix
g = GraphState.from_adjacency(adj_matrix)
adjacency_matrix → N×N numpy array of edge weights
nullifier_coefficients(mode) → 2N coefficient vector for δ_mode
num_edges → Number of CZ interactions

class MeshOptimizer

Optimization

Phase optimization for Clements/Reck interferometer meshes.

__init__(num_modes, architecture="clements")
optimize(cost_function, method="L-BFGS-B")
symplectic_matrix(phases) → 2N×2N symplectic transformation

class MonteCarloAnalyzer

Analysis

Fabrication tolerance analysis via Monte Carlo sampling.

from cv_cluster.analysis import MonteCarloAnalyzer

mc = MonteCarloAnalyzer(compiler)
result = mc.run(
    num_trials=1000,
    phase_error_std=0.5,  # degrees
    bs_imbalance_std=0.02  # fraction
)
print(f"Success rate: {result.success_rate:.1%}")

class LossSimulator

Loss Modeling

Per-component loss modeling through interferometer mesh.

from cv_cluster.loss import LossSimulator

loss_sim = LossSimulator(
    compiler,
    loss_per_layer_dB=0.5,
    num_layers=4
)
result = loss_sim.analyze()
print(f"Entangled modes: {result.entangled_count}/{result.total_modes}")