Interfaces

Circuit(...) returns a different type of circuit depending on its interface= argument, which you set explicitly, as in PennyLane. Both interfaces run the same CircuitSpec on the same providers. They differ only in how you pass the weights and how you get gradients:

"numpy", the default, is the core circuit, which does not depend on any framework. You pass the weights at every call, and the gradients come from circuit.jacobian(...). It does not use PyTorch, and pip install eigenkit with no extra is enough.
"torch" is a torch.nn.Module that stores its weights as an nn.Parameter and computes gradients through torch.autograd. It is part of the optional PyTorch package (the torch extra).

	`numpy` (default)	`torch`
Returns	A `core.circuit.Circuit`.	A `TorchCircuit`, which is an `nn.Module`.
Weights	They are passed at each call: `circuit(weights, x)`.	The circuit stores them as an `nn.Parameter`: `circuit(x)`.
Gradients	`circuit.jacobian(weights, x)`.	`loss.backward()`, through autograd.
Dependency	The core (NumPy and SciPy).	The `torch` extra.
Best for	Chemistry and optimisation, variational loops, and custom training without a framework.	Hybrid quantum-classical models trained end to end in PyTorch.

Both accept the same provider= argument, in any of its forms. See Providers.

Circuit is a function, not a class

The top-level Circuit(...) is a factory function. It returns one of two concrete types, depending on interface=: the NumPy circuit eigenkit.core.circuit.Circuit, or the PyTorch circuit TorchCircuit, which is an nn.Module. So it is not a class: isinstance(obj, Circuit), issubclass(...), subclassing Circuit, and using Circuit as a type annotation do not work. Check the type against the concrete class, or subclass it, instead (from eigenkit.core.circuit import Circuit as NumpyCircuit, or from eigenkit.torch import TorchCircuit).

The NumPy interface (default)

Circuit(blocks, observables) returns the core NumPy circuit. It does not store parameters: you pass a 1-D weights vector, of length circuit.spec.n_weights, and an inputs vector at each call.

import numpy as np
from eigenkit import Circuit, Encoding, Variational, all_z

circuit = Circuit(
    blocks=[Encoding(in_features=4, rotation="RX"), Variational(depth=2)],
    observables=all_z(4),
)  # provider="numpy", interface="numpy"

weights = np.zeros(circuit.spec.n_weights)
x = np.array([0.1, 0.2, 0.3, 0.4])
y = circuit(weights, x)  # shape (4,): one expectation per observable

Forward calls and batching

inputs can be 1-D, for a single sample, or 2-D, with shape (batch, n_inputs). weights stays 1-D, because the weights are shared across the batch. The output has shape (n_observables,) or (batch, n_observables). It becomes a scalar, or shape (batch,), when a single observable is measured.

x_batch = np.random.uniform(0, np.pi, size=(32, 4))
circuit(weights, x_batch)  # shape (32, 4)

Gradients with `circuit.jacobian`

The NumPy interface is fully differentiable without PyTorch:

g = circuit.jacobian(weights, x)  # d<O>/d(weights)
gw, gx = circuit.jacobian(weights, x, input_grad=True)  # also d<O>/d(inputs)

jacobian returns shape (n_weights,) for a single observable, and (n_observables, n_weights) for several, in the same way as __call__. It uses the differentiation of the active backend when there is one, such as the analytic adjoint method of the NumPy simulator, or the automatic differentiation of PennyLane. Otherwise, it uses the parameter-shift rule, which works on any backend. Pass one 1-D sample. For a batch, loop over the rows. On a hardware backend, it raises an error, like .backward(), unless the configuration of the device sets enable_gradients=True.

The variational optimisation tools use this gradient, so a loop that finds a ground state takes a few lines and does not need PyTorch. These tools work on a purely variational circuit, which has no inputs, so the example takes an ansatz in place of the encoding circuit above:

from eigenkit import Variational, Z, minimize_expectation

ansatz = Circuit([Variational(depth=2)], observables=Z(0))  # n_inputs == 0

rng = np.random.default_rng(0)
x0 = rng.uniform(0, 2 * np.pi, size=ansatz.spec.n_weights)
result = minimize_expectation(ansatz, initial_parameters=x0)
print(result.optimal_value)

Other primitives

zero_state_probability(weights, inputs), which gives the fidelity used to invert kernels, and probabilities(weights, inputs), which gives the whole distribution of measurement outcomes, take the same (weights, inputs) arguments:

circuit.zero_state_probability(weights, x)
circuit.probabilities(weights, x)  # shape (2**n_qubits,)

A circuit with no trainable weights, such as the inversion circuit of a kernel that uses only data, takes an empty weight vector: inversion.zero_state_probability([], x).

When to use it

The NumPy interface is the right default for the domains that do not use a framework (chemistry, optimization), for variational loops driven by SciPy, for any custom training where you control the optimiser, and for light installs that should not install PyTorch.

The PyTorch interface

Pass interface="torch" to get a torch.nn.Module. It stores its weights as an nn.Parameter, so you call it with the inputs only, and you train it with any PyTorch optimiser. It needs the torch extra, and it runs on the built-in NumPy simulator, which is differentiable:

import torch
from eigenkit import Circuit, Encoding, Variational, all_z

layer = Circuit(
    blocks=[Encoding(in_features=4), Variational(depth=2)],
    observables=all_z(4),
    interface="torch",
    init=None,  # optional initial weights, shape (n_weights,)
)

layer.weights  # nn.Parameter of shape (n_weights,)
list(layer.parameters())  # plugs into torch.optim like any module

init sets the initial weight tensor. When it is not given, the weights are drawn at random with torch.randn. Both the top-level Circuit(...) factory and a TorchCircuit(...) built directly default to provider="numpy".

What the layer exposes

Member	What it does
`layer(x)`	The forward pass. `x` can be 1-D (one sample) or 2-D, with shape `(batch, n_inputs)`.
`weights`	The trainable `nn.Parameter`, of shape `(n_weights,)`.
`spec`, `n_qubits`, `out_features`	The assembled `CircuitSpec`, and the two sizes derived from it.
`draw(decimals=3)`	A drawing of the circuit as text, over several lines. It takes no input, because the layer stores its weights.
`draw_mpl(**kwargs)`	The same drawing as a matplotlib `(fig, ax)`. It needs the `viz` extra.
`zero_state_probability(x)`	The probability of the all-zeros outcome, which is the fidelity that the kernels use.
`submit(x)`	Submits the circuit without waiting, and returns a `JobHandle`. It works on Braket, Qiskit Runtime and IQM only.
`dry_run_info()`	Gives, without submitting anything, the gate counts, the shots and the number of circuits that a call runs. It works on Braket, Qiskit Runtime and IQM, and the other backends raise `NotImplementedError`.
`with_provider(provider, ...)`	Builds the same circuit again on another backend. See below.

probabilities() and jacobian() are not available on the PyTorch circuit. The whole distribution of measurement outcomes is a primitive of the NumPy interface, and the gradients come from loss.backward() instead of a call to a jacobian. submit() and dry_run_info() are explained in QPU and Cloud.

Forward calls and batching

y = layer(torch.randn(8, 4))  # (8, 4): batch of 8, one value per observable

A 1-D input is a single sample, and a 2-D input is a batch. The weights are shared across the batch, exactly as in the NumPy interface.

Gradients with `loss.backward()`

The gradients flow through torch.autograd:

x = torch.randn(8, 4)
target = torch.zeros(8, 4)
opt = torch.optim.Adam(layer.parameters(), lr=0.05)
loss = (layer(x) - target).pow(2).mean()
loss.backward()  # weights.grad is populated
opt.step()

Backends with their own automatic differentiation, such as PennyLane, differentiate through their own engine. For the other backends, the forward pass is wrapped in a torch.autograd.Function, whose backward pass uses the same parameter-shift or adjoint jacobian as the NumPy interface. Backends without gradients (gradient_method="none", for example quantum hardware and Qiskit Runtime) raise a clear error on .backward(). See QPU and Cloud for the pattern of training on a simulator and then running on the device, and for enable_gradients=True, which lets a hardware configuration use the parameter-shift rule on the device.

Training also works on the default NumPy provider, without PennyLane. The analytic adjoint method of the NumPy backend differentiates a whole batch in one sweep, so Circuit(..., interface="torch"), with the NumPy provider by default, trains hybrid models efficiently. Switch to provider="pennylane" if you prefer its simulator. Both process batches natively: the forward and backward passes of a (B, …) batch run in one call, not in a Python loop over the samples.

Moving a circuit to another provider with `with_provider`

with_provider builds the same CircuitSpec and observables again on a different backend, without listing the blocks again:

fast = layer.with_provider("qiskit")  # clones weights
fresh = layer.with_provider("qiskit", copy_weights=False)  # re-initialises
exact = layer.with_provider(
    "qiskit",
    init=torch.zeros(layer.spec.n_weights, dtype=torch.float64),
)

The weights are cloned by default. copy_weights=False draws new random weights, and init= sets them explicitly (it takes precedence over copy_weights). The new layer takes its data type from init, so pass dtype=torch.float64 to keep the double precision that a layer built from blocks starts with. A plain torch.zeros(n) is float32, and it would halve the precision without any warning.

Composing and saving

Because it is a plain nn.Module, a PyTorch circuit can be used inside nn.Sequential and next to the ready-made layers (see Layers). The scikit-learn compatible estimators (HQNC, HQNR and others) are built on it. Its state can be saved and restored with the usual PyTorch methods (state_dict() and load_state_dict()), and fitted estimators are saved as .eigenkit bundles. See Model persistence.

When to use it

Use the PyTorch interface when the quantum circuit is one layer in a larger PyTorch model, or whenever you want to train end to end with automatic differentiation and the optimisers and tools of PyTorch.

Same circuit, both interfaces

The interface is a choice made when the code runs, over one definition of the circuit. The blocks, the observables and the numerical results of the provider are the same:

import numpy as np, torch
from eigenkit import Circuit, Encoding, Variational, all_z

blocks = [Encoding(in_features=2), Variational(depth=1)]

np_circuit = Circuit(blocks, all_z(2))  # numpy
tc = Circuit(blocks, all_z(2), interface="torch")  # torch

w = tc.weights.detach().numpy()
x = np.array([0.3, -0.2])
np.allclose(np_circuit(w, x), tc(torch.tensor(x)).detach().numpy())  # True

API reference

The factory function that chooses the type from interface=, and the two concrete types that it returns.

`eigenkit.circuit.Circuit(blocks, observables=None, provider='numpy', interface='numpy', init=None)`

Build a circuit and compile it for a backend.

This is the entry point for the rest of the library: you give it blocks, and it returns a circuit that you can call. The type of the circuit depends on interface. The NumPy interface returns a core Circuit, and the PyTorch interface returns a TorchCircuit.

Parameters:

Name	Type	Description	Default
`blocks`	`_BlocksOrSpec`	The circuit. It can be a list of blocks to assemble, a `CircuitSpec` that is already assembled, or a `CircuitBuilder`. A builder is built when `Circuit` is called, so gates added to it afterwards are not part of this circuit. A builder can also take the place of a block in the list.	required
`observables`	`ObservableLike`	What to measure. `None` measures `Z` on every qubit and returns one value per qubit. A single `Observable` or `PauliExpr` returns a single value, and a list of them returns one value for each. Default: `None`.	`None`
`provider`	`ProviderSpec`	The backend that runs the circuit. It can be a registered name (`"numpy"`, `"pennylane"`, `"qiskit"` and others), a configuration instance such as `PennyLaneConfig(...)`, or a backend object. Default: `"numpy"`.	`'numpy'`
`interface`	`_Interface`	`"numpy"` returns a circuit that takes the weights at each call and does not depend on any framework. `"torch"` returns a `TorchCircuit`, which is a PyTorch `nn.Module` that stores the weights. Default: `"numpy"`.	`'numpy'`
`init`	`Tensor \| None`	The initial weights of the PyTorch circuit, of shape `(n_weights,)`. They are random when `init` is not given. The NumPy interface stores no weights, so passing `init` with it raises a `ValueError`. Default: `None`.	`None`

Returns:

Name	Type	Description
`circuit`	`Circuit \| TorchCircuit`	The circuit for the requested `interface`.

Raises:

Type	Description
`ValueError`	If `interface` is neither `"numpy"` nor `"torch"`, or if `init` is passed with the NumPy interface.

Example

import numpy as np
from eigenkit import Circuit, Encoding, Variational, all_z

circuit = Circuit(
    blocks=[Encoding(in_features=4), Variational(depth=2)],
    observables=all_z(4),
)
weights = np.zeros(circuit.spec.n_weights)
values = circuit(weights, np.random.uniform(0, np.pi, size=4))

`eigenkit.core.circuit.Circuit`

A compiled circuit, ready to evaluate.

It holds a CircuitSpec, the observables to measure and a compiled backend handle. The circuit is compiled once, when the instance is created, and every call reuses the compiled handle. The instance does not store weights: you pass the weights at each call.

This is the NumPy interface. The top-level Circuit(...) function of the package returns this class for interface="numpy" and a TorchCircuit for interface="torch".

Parameters:

Name	Type	Description	Default
`spec`	`CircuitSpec`	The circuit to run, usually built with `assemble(blocks)`.	required
`observables`	`ObservableLike`	What to measure. `None` measures `Z` on every qubit and returns one value per qubit. A single `Observable` or `PauliExpr` returns a single value, and a list of them returns one value for each. Default: `None`.	`None`
`provider`	`ProviderSpec`	The backend that runs the circuit. It can be a registered name (`"numpy"`, `"pennylane"` and others), a configuration instance, or a provider object. Default: `"numpy"`.	`'numpy'`
`interface`	`Interface`	How a call is evaluated. With `"numpy"`, a call runs the NumPy path and returns NumPy values. With `"torch"`, each call is passed to the registered PyTorch interface, and `TorchCircuit` builds its core circuit in this way. The top-level `Circuit` function always passes `"numpy"`. Default: `"numpy"`.	`'numpy'`

Example

import numpy as np
from eigenkit import Circuit, Encoding, Variational, all_z

circuit = Circuit(
    blocks=[Encoding(in_features=2), Variational(depth=1)],
    observables=all_z(2),
)

# The circuit stores no weights, so you pass them at every call.
weights = np.zeros(circuit.spec.n_weights)
values = circuit(weights, np.array([0.1, 0.2]))

# Gradients, without PyTorch.
grad = circuit.jacobian(weights, np.array([0.1, 0.2]))

`draw(*, decimals=3)`

Return a text drawing of the circuit, over several lines.

The drawing does not depend on the provider: it is built from the CircuitSpec, not from the compiled backend object. See eigenkit.core.draw for the details of the layout.

Parameters:

Name	Type	Description	Default
`decimals`	`int`	The number of significant digits shown for a numeric gate angle. Default: `3`.	`3`

Returns:

Type	Description
`str`	The drawing, as a single string that contains newlines.

`draw_mpl(**kwargs)`

Draw the circuit as a matplotlib figure, and return (fig, ax).

Gates are drawn as labelled boxes and controls as filled dots, and each measured wire (from self.observables) ends with a measurement symbol. As with draw(), the picture is built from the CircuitSpec and the observables, not from the compiled backend, so it does not depend on the provider.

Pass style="eigen" for the brand colours (each gate is coloured by its kind: rotations, H and block gates, and measurements), or style="roles" to colour the outline of each gate by its role (encoding, trainable or fixed). The default is black on white. Each style has a "-dark" variant (for example "eigen-dark") for dark backgrounds, and "eigen-universal" is a single image that works on both.

matplotlib is an optional dependency. Install it with eigenkit[viz].

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Arguments passed to `draw_mpl()`: `decimals`, `show_params`, `show_measurements`, `fontsize`, `style`, `legend` and `ax`.	`{}`

Returns:

Name	Type	Description
`fig_ax`	`tuple`	The matplotlib `(fig, ax)` pair.

`dry_run_info()`

Describe the prepared circuit in a dictionary, without submitting it.

It is available only on backends whose CompiledCircuit provides a dry_run_info method. Currently, these are Braket (on its local simulator as well as on cloud devices), Qiskit Runtime and IQM. It is useful to check the size of the circuit, the gate counts after transpilation, the number of shots and the number of circuits that each call runs, before you submit to a cloud simulator or a quantum processing unit (QPU). It does not estimate a price.

`jacobian(weights, inputs=None, *, input_grad=False)`

Return the gradient of the expectation values with respect to the weights.

It returns d<O>/d(weights), of shape (n_weights,) for a single observable or (n_observables, n_weights) for a list of observables, like the output of __call__(). Pass a single 1-D inputs sample. For a batch, call it once for each row.

The NumPy interface can compute every gradient without PyTorch. This method uses the same sequence of gradient methods as the variational optimisation tools and the PyTorch interface. It uses the backend's own differentiation when the backend has one (the analytic adjoint method of the NumPy simulator, the differentiation of PennyLane, and so on), and otherwise the parameter-shift rule, which works on any backend.

With input_grad=True, it returns (weight_jacobian, input_jacobian), where input_jacobian is d<O>/d(inputs), with the same leading shape.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray \| None`	One 1-D sample, of shape `(n_inputs,)`. This method takes a single sample, so for a batch, call it once for each row. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`
`input_grad`	`bool`	If True, also return the jacobian with respect to the inputs. Default: `False`.	`False`

Returns:

Name	Type	Description
`jacobian`	`ndarray \| tuple[ndarray, ndarray]`	The weight jacobian, or `(weight_jacobian, input_jacobian)` when `input_grad` is True.

Raises:

Type	Description
`RuntimeError`	On a hardware backend whose configuration leaves `enable_gradients` off (`gradient_method="none"`).

`probabilities(weights, inputs=None)`

Return the measurement distribution over all 2**n_qubits basis states.

The basis states are ordered with qubit 0 as the most significant bit. The distribution is used to decode samples. For example, the quantum approximate optimisation algorithm (QAOA) reads the most probable bitstrings from the optimised state.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray \| None`	One 1-D sample. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Type	Description
`ndarray`	The probabilities of all basis states, of shape `(2**n_qubits,)`.

Raises:

Type	Description
`NotImplementedError`	On a backend that has neither a `probabilities()` method nor a state vector to compute the probabilities from.

`resources(**kwargs)`

Report the resources that the circuit uses once transpiled for its target.

It reports the native gate counts, the number of two-qubit gates and the two-qubit depth, the physical qubits chosen by the layout, the number of two-qubit gates added by routing (compared with the same circuit on the native gates with all-to-all connectivity), and the success probability predicted by the error rates of the target. Nothing is submitted.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Arguments passed to the backend, for example `measured=False` on Qiskit Runtime for the bare estimator circuit.	`{}`

Returns:

Type	Description
`dict`	A dictionary. See `QiskitRuntimeCompiled.resources()` for its keys.

Raises:

Type	Description
`NotImplementedError`	On backends that do not transpile for a device, which includes every simulator. To inspect a device locally, use Qiskit Runtime or IQM with a fake `backend_instance`.

`sample(weights, inputs=None)`

Return the raw measurement histogram, which maps each bitstring to a count.

It is what a sampling backend measured, before any averaging. These are the counts behind probabilities(), and it is the only form that stays usable when the circuit has too many qubits for a dense distribution. In each bitstring, qubit 0 is the most significant bit, so "100" means that qubit 0 was measured in state 1.

Only sampling backends can return a histogram, because it needs a finite number of shots. Exact statevector simulators raise an error instead of making up a histogram. Use probabilities() with those.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray \| None`	One 1-D sample. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Name	Type	Description
`counts`	`dict[str, int]`	The number of shots for each measured bitstring. The counts add up to the number of shots set for the backend.

Raises:

Type	Description
`NotImplementedError`	On backends that do not sample. This includes every exact simulator, which has no shots to report.

`statevector(weights, inputs=None, initial_state=None)`

Return the full complex statevector after the circuit runs.

It is a flat array of length 2**n_qubits, ordered with qubit 0 as the most significant bit. A 2-D inputs batch returns an array of shape (B, 2**n_qubits). With initial_state, a normalised flat statevector in the same order, the evolution starts from that state instead of |0…0⟩. Reading a state out and passing it back in this way is the basic operation behind the state carried over in quantum reservoirs and behind amplitude encoding.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray \| None`	A 1-D sample, or a 2-D batch. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`
`initial_state`	`ndarray \| None`	The state to start the evolution from, instead of `\|0…0⟩`. It is a normalised flat statevector in the same order. Default: `None`.	`None`

Returns:

Type	Description
`ndarray`	The statevector, of shape `(2n_qubits,)`, or `(B, 2n_qubits)` for a batch.

Raises:

Type	Description
`NotImplementedError`	On backends without access to the statevector, which is the case for most quantum processing unit (QPU) and cloud backends.

`submit(weights, inputs=None)`

Submit a job without waiting for it, and return a JobHandle.

handle.result() returns the expectation value of each observable.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray \| None`	One 1-D sample. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Name	Type	Description
`handle`	`JobHandle`	A handle for the submitted job.

Raises:

Type	Description
`NotImplementedError`	If the `CompiledCircuit` of the backend does not provide `submit`. Currently, Braket, Qiskit Runtime and IQM provide it.

`transpiled_circuit(**kwargs)`

Return the qiskit.QuantumCircuit that a hardware backend submits.

The circuit is transpiled for the target of the backend. Use it to draw the circuit (.draw("mpl")) or to inspect it.

Raises:

Type	Description
`NotImplementedError`	On backends that do not transpile for a device.

`zero_state_probabilities(weights, inputs)`

Compute zero_state_probability() for every row of a batch of inputs.

inputs has shape (B, n_inputs), and the result is an array of shape (B,) of all-zeros probabilities. Backends that provide a batched zero_state_probabilities (such as the NumPy simulator) compute the whole batch at once. The other backends call the single-sample method once for each row. This is what lets QuantumKernel build a fidelity matrix without a Python loop over pairs of samples.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray`	A batch, of shape `(B, n_inputs)`.	required

Returns:

Type	Description
`ndarray`	One all-zeros probability for each row, as an array of shape `(B,)`.

`zero_state_probability(weights, inputs=None)`

Return the probability of measuring the all-zeros state after the circuit.

It is useful for quantities based on fidelity: quantum kernels built from inversion circuits, swap tests and the Bures distance. Each backend computes it in its own way. PennyLane returns qml.probs(...)[0], the Qiskit and NumPy simulators return the squared amplitude of the all-zeros basis state, Braket uses its own probability result, and IQM and Qiskit Runtime estimate it from shots. This method does not go through the Observable path, because the value is not the expectation value of a Pauli operator.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	The weight vector, of shape `(n_weights,)`.	required
`inputs`	`ndarray \| None`	One 1-D sample. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Type	Description
`float`	The probability, a float in `[0, 1]`.

Raises:

Type	Description
`NotImplementedError`	If the active backend does not provide `zero_state_probability`.

`eigenkit.torch.circuit.TorchCircuit`

Bases: Module

A quantum layer that stores trainable weights and runs on any registered backend.

It runs through the PyTorch interface, so that PyTorch can compute the gradients of its output.

Parameters:

Name	Type	Description	Default
`blocks`	`_BlocksOrSpec`	The circuit. It can be a list of blocks to assemble, a `CircuitSpec` that is already assembled, or a `CircuitBuilder`. A builder is built when the layer is created, so gates added to it afterwards are not part of this layer.	required
`observables`	`ObservableLike`	What to measure. `None` measures `Z` on every qubit and returns one value per qubit. A single `Observable` or `PauliExpr` returns a single value, and a list of them returns one value for each. Default: `None`.	`None`
`provider`	`ProviderSpec`	The backend that runs the circuit. It can be a registered name, a configuration instance, or a provider object. Any backend works. A backend that computes gradients itself avoids the fallback to the parameter-shift rule. Default: `"numpy"`.	`'numpy'`
`init`	`Tensor \| None`	The initial weights, of shape `(n_weights,)`. They are random when `init` is not given. Default: `None`.	`None`

`n_qubits` `property`

The number of qubits of the circuit in spec.

`out_features` `property`

The number of observables, or 1 for a single observable.

`provider` `property`

The backend that this circuit was compiled for.

It is the same as Circuit.provider, which turns the provider= argument (a registered name, a configuration or a backend object) into one Provider. The registered name is provider.name. To run the same circuit on another backend, use with_provider(), which returns a new instance and leaves this one unchanged.

`spec` `property`

The circuit that this layer runs.

It is the CircuitSpec assembled from blocks, or the one that was passed in already assembled.

`draw(*, decimals=3)`

Return a text drawing of the circuit, over several lines.

The drawing does not depend on the provider: it is built from the CircuitSpec, so it is the same whatever the active backend is. Print the returned string directly.

Example

from eigenkit import Circuit, Encoding, Variational

blocks = [Encoding(in_features=2), Variational(depth=1)]
circuit = Circuit(blocks=blocks, interface="torch")
print(circuit.draw())
# q_0: ──RY(x_0)──RY(w_0)──●──
#                          │
# q_1: ──RY(x_1)──RY(w_1)──X──

Parameters:

Name	Type	Description	Default
`decimals`	`int`	The number of significant digits shown for a numeric gate angle. Default: `3`.	`3`

Returns:

Type	Description
`str`	The drawing, as a single string that contains newlines.

`draw_mpl(**kwargs)`

Draw the circuit as a matplotlib figure, and return (fig, ax).

The picture does not depend on the provider, because it is built from the CircuitSpec and the observables. matplotlib is an optional dependency. Install it with eigenkit[viz]. The keyword arguments are passed to draw_mpl().

`dry_run_info()`

Describe the prepared circuit in a dictionary, without submitting it.

It is useful to check the size of the circuit, the gate counts after transpilation, the number of shots and the number of circuits that each call runs, before you submit to a cloud simulator or a quantum processing unit (QPU). It does not estimate a price. It is available only on the backends that provide it. Currently, these are Braket (on its local simulator as well as on cloud devices), Qiskit Runtime and IQM. Other backends raise a NotImplementedError.

`forward(x=None)`

Run the layer.

Parameters:

Name	Type	Description	Default
`x`	`Tensor`	The input batch, of shape `(batch, in_features)`.	`None`

Returns:

Type	Description
`Tensor`	The output of the layer for that batch.

`reset_parameters()`

Draw new circuit weights from the current PyTorch random number generator.

Every nn.Module that PyTorch provides defines this method. The estimators call model.apply(reset_parameters) after setting the seed, so that random_state controls the whole initialisation. Without this method, the estimators would skip the layer: two fits with different values of random_state would give different classical weights but exactly the same quantum weights, and a user who restarts with new seeds to escape a barren plateau would change only the part of the model that is not the circuit.

`sample(x=None)`

Return the raw measurement histogram for the current weights and input.

The histogram maps each bitstring to its number of shots. In each bitstring, qubit 0 is the most significant bit.

It is the second step of the workflow in which you train on a simulator and then run on hardware: you train the layer, and then you read what the device measured. It takes one sample, and its result is not differentiable, because the counts are integers that PyTorch does not record for automatic differentiation.

Parameters:

Name	Type	Description	Default
`x`	`Tensor \| None`	The input features of one sample, as a 1-D tensor. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Name	Type	Description
`counts`	`dict[str, int]`	The number of shots for each measured bitstring.

Raises:

Type	Description
`NotImplementedError`	On backends that do not sample.
`ValueError`	If `x` is 2-D.

`submit(x=None)`

Submit a job without waiting for it, and return a JobHandle.

Only the backends that provide submission support it (Braket, Qiskit Runtime and IQM).

Parameters:

Name	Type	Description	Default
`x`	`Tensor \| None`	One 1-D input sample. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Name	Type	Description
`handle`	`JobHandle`	A handle for the submitted job.

`with_provider(provider, *, copy_weights=True, init=None)`

Return a new TorchCircuit for another provider.

The new circuit has the same spec and the same observables argument as this instance, and it is compiled for the given provider.

provider accepts the same forms as in __init__(): a registered name (a str), a configuration object with a make_backend() method (for example PennyLaneConfig), or a backend instance.

The gradients follow the gradient_method of the new backend. The forward values should match across simulators up to numerical tolerance, but not exactly.

Parameters:

Name	Type	Description	Default
`provider`	`ProviderSpec`	The backend for the new circuit.	required
`copy_weights`	`bool`	If True, the new circuit starts from a copy of `self.weights`. It is ignored when `init` is given. Default: `True`.	`True`
`init`	`Tensor \| None`	An optional weight tensor of shape `(spec.n_weights,)`. When it is given, it takes precedence over `copy_weights`. Default: `None`.	`None`

Returns:

Type	Description
`'TorchCircuit'`	The new `TorchCircuit`.

`zero_state_probability(x=None)`

Return the probability of measuring the all-zeros state.

It uses the current weights and the given input. It is useful for fidelity kernels and swap tests.

It takes one sample, and its result is not differentiable. The core reads the amplitude through the backend's access to the state and returns a plain float, so PyTorch does not record it for automatic differentiation. A batch raises an error, because a single number cannot hold a batch axis. For a batch, call this method once for each row, or use Circuit.zero_state_probabilities.

Parameters:

Name	Type	Description	Default
`x`	`Tensor \| None`	The input features of one sample, as a 1-D tensor. `None` works only for a circuit that takes no inputs, and it raises a `ValueError` for any other circuit. Default: `None`.	`None`

Returns:

Type	Description
`float`	The all-zeros probability, a float in `[0, 1]`.

Raises:

Type	Description
`ValueError`	If `x` is 2-D.

Interfaces

The NumPy interface (default)

Forward calls and batching

Gradients with circuit.jacobian

Other primitives

When to use it

The PyTorch interface

What the layer exposes

Forward calls and batching

Gradients with loss.backward()

Moving a circuit to another provider with with_provider

Composing and saving

When to use it

Same circuit, both interfaces

API reference

eigenkit.circuit.Circuit(blocks, observables=None, provider='numpy', interface='numpy', init=None)

eigenkit.core.circuit.Circuit

draw(*, decimals=3)

draw_mpl(**kwargs)

dry_run_info()

jacobian(weights, inputs=None, *, input_grad=False)

probabilities(weights, inputs=None)

resources(**kwargs)

sample(weights, inputs=None)

statevector(weights, inputs=None, initial_state=None)

submit(weights, inputs=None)

transpiled_circuit(**kwargs)

zero_state_probabilities(weights, inputs)

zero_state_probability(weights, inputs=None)

eigenkit.torch.circuit.TorchCircuit

n_qubits property

out_features property

provider property

spec property

draw(*, decimals=3)

draw_mpl(**kwargs)

dry_run_info()

forward(x=None)

reset_parameters()

sample(x=None)

submit(x=None)

with_provider(provider, *, copy_weights=True, init=None)

zero_state_probability(x=None)

Gradients with `circuit.jacobian`

Gradients with `loss.backward()`

Moving a circuit to another provider with `with_provider`

`eigenkit.circuit.Circuit(blocks, observables=None, provider='numpy', interface='numpy', init=None)`

`eigenkit.core.circuit.Circuit`

`draw(*, decimals=3)`

`draw_mpl(**kwargs)`

`dry_run_info()`

`jacobian(weights, inputs=None, *, input_grad=False)`

`probabilities(weights, inputs=None)`

`resources(**kwargs)`

`sample(weights, inputs=None)`

`statevector(weights, inputs=None, initial_state=None)`

`submit(weights, inputs=None)`

`transpiled_circuit(**kwargs)`

`zero_state_probabilities(weights, inputs)`

`zero_state_probability(weights, inputs=None)`

`eigenkit.torch.circuit.TorchCircuit`

`n_qubits` `property`

`out_features` `property`

`provider` `property`

`spec` `property`

`draw(*, decimals=3)`

`draw_mpl(**kwargs)`

`dry_run_info()`

`forward(x=None)`

`reset_parameters()`

`sample(x=None)`

`submit(x=None)`

`with_provider(provider, *, copy_weights=True, init=None)`

`zero_state_probability(x=None)`