wire

`eigenkit.core.wire`

A stable JSON form for circuits and observables.

The functions of this module convert a CircuitSpec and its observables to plain JSON types (dict, list, str, int, float, bool and None), and back. .eigenkit bundles use the same encoding, so a change to it would break the saved models.

Example

import json

from eigenkit.core import wire
from eigenkit.core.blocks import AngleEncoding, BasicVariational, assemble
from eigenkit.core.observables import all_z

spec = assemble([AngleEncoding(in_features=2), BasicVariational(depth=1)])
payload = json.dumps(
    {
        "circuit": wire.circuit_spec_to_json(spec),
        "observables": wire.observables_to_json(all_z(2)),
    }
)

data = json.loads(payload)
assert wire.circuit_spec_from_json(data["circuit"]) == spec
assert wire.observables_from_json(data["observables"]) == all_z(2)

`circuit_spec_from_json(data)`

Decode a circuit encoded by circuit_spec_to_json.

Parameters:

Name	Type	Description	Default
`data`	`dict`	The encoded circuit, for example as returned by `json.loads`.	required

Returns:

Type	Description
`CircuitSpec`	The circuit, equal to the one that was encoded.

`circuit_spec_to_json(spec)`

Encode a circuit as a dictionary that can be saved as JSON.

Parameters:

Name	Type	Description	Default
`spec`	`CircuitSpec`	The assembled circuit.	required

Returns:

Type	Description
`dict`	A dictionary with the keys `n_qubits`, `n_weights`, `n_inputs` and `gates`, made of plain JSON types only.

`observables_from_json(data)`

Decode observables encoded by observables_to_json.

Parameters:

Name	Type	Description	Default
`data`	`list \| dict`	The encoded observables, for example as returned by `json.loads`.	required

Returns:

Type	Description
`Observable \| list[Observable]`	An `Observable` when `data` is a dictionary, or a list of observables when `data` is a list.

`observables_to_json(observables)`

Encode one observable, or a list of them, as data that can be saved as JSON.

Each observable becomes {"terms": [{"coeff": c, "paulis": [[op, q], ...]}]}. A coefficient that is a Python int or float is written unchanged. A NumPy integer becomes an int, and any other real number (a NumPy float or a Fraction, for example) becomes a float, so the output is plain JSON for any encoder.

Parameters:

Name	Type	Description	Default
`observables`	`Observable \| Sequence[Observable]`	A single observable, or a list or tuple of observables.	required

Returns:

Type	Description
`list \| dict`	A dictionary for a single observable, or, for a list or tuple, a list of dictionaries in the order of the input.

Raises:

Type	Description
`TypeError`	If a coefficient is a `bool` or is not a real number.