Circuits

The circuit pool and quantum-kernel computation. The seven bundled encoding circuits are described in Circuit Pool; all are implemented in the bundled Qsun simulator.

Registering a custom circuit is a dict insertion - see Advanced Usage, and mind the input-range warning on UNIT_RANGE_CIRCUITS.

Qmes.CIRCUIT_POOL module-attribute

CIRCUIT_POOL = {
    "unit": lambda x: unit_encode(x),
    "SRx": lambda x: SeparableRXEncoding_encode(x),
    "RY": lambda x: angle_encode(x),
    "HERx": lambda x: HardwareEfficientEmbeddingRx_encode(
        x
    ),
    "RY_CX": lambda x: RY_CX_linear_encode(x),
    "ZFM": lambda x: ZFeatureMap_encode(x),
    "HD": lambda x: HighDim_encode(x),
}

Registry of the seven encoding circuits shipped with Qmes.

Maps circuit name to an encoding function x -> quantum state, where x is a single preprocessed sample (one rotation angle per qubit, except HD which encodes three angles per qubit). All circuits are implemented in the bundled Qsun simulator.

The pool is a plain dict and intentionally extensible: registering a new circuit is adding an entry (CIRCUIT_POOL["name"] = fn) - no subclassing required. If the new circuit expects inputs in [0, 1] rather than rotation angles in [0, pi], also add its name to UNIT_RANGE_CIRCUITS.

Qmes.circuits.UNIT_RANGE_CIRCUITS module-attribute

UNIT_RANGE_CIRCUITS = {'unit'}

Names of circuits whose inputs must be scaled to [0, 1] instead of [0, pi].

The evaluators pick the MinMaxScaler feature range per circuit from this set. Only unit needs [0, 1] out of the box: its amplitude encoding computes sqrt(x) and sqrt(1 - x), which is undefined outside that interval. Getting this wrong for a custom circuit does not raise - it silently degrades the kernel (see the Advanced Usage guide).

Qmes.get_circuit_names

get_circuit_names()

Return the names of all circuits in the pool.

Returns:

Type	Description
list[str]	Circuit names in the insertion order of CIRCUIT_POOL:
``unit``, ``SRx``, ``RY``, ``HERx``, ``RY_CX``, ``ZFM``, ``HD``.

Qmes.circuits.get_circuit_fn

get_circuit_fn(name)

Look up an encoding function in CIRCUIT_POOL by name.

Parameters:

Name	Type	Description	Default
name	str	Circuit name, e.g. 'RY'.	required

Returns:

Type	Description
callable	The encoding function x -> quantum state.

Raises:

Type	Description
ValueError	If name is not in CIRCUIT_POOL.

Qmes.circuits.compute_kernel_matrix

compute_kernel_matrix(X1, X2, circuit_fn)

Compute the quantum fidelity kernel matrix between two sample sets.

Each entry is the squared state overlap K[i, j] = |<phi(x1_i)|phi(x2_j)>|^2, where phi is the feature map induced by circuit_fn. Every sample is encoded once (n1 + n2 circuit simulations), then all pairwise overlaps are taken - this is the O(n^2) cost that Qmes avoids at inference time.

Parameters:

Name	Type	Description	Default
X1	(ndarray, shape(n1, n_features))	First sample set. Must already be scaled to the circuit's expected input range (see UNIT_RANGE_CIRCUITS).	required
X2	(ndarray, shape(n2, n_features))	Second sample set. If X2 is the same object as X1, the matrix is symmetric and only the upper triangle is computed.	required
circuit_fn	callable	Encoding function from CIRCUIT_POOL.	required

Returns:

Type	Description
(ndarray, shape(n1, n2))	Kernel matrix. Any NaN entries are replaced with 0.0 and logged as a warning rather than raised.