monoprop

MonomialPropagator

Abstract base for the classical monomial-propagation simulators.

Subclasses implement __init__ -- resolve their operator family to a MajoranaOperator, then call _init_simulator -- and _circuit_gates, which validates the circuit's gate family.

Note: Heisenberg evolution consumes each build_graph / propagate call's gates back-to-front, so splitting one circuit across several calls is not equivalent to a single call; in the Schrodinger picture (front-to-back) it is.

Attributes

attributen_parametersint

Size of the current graph's parameter axis.

Follows the graph rather than accumulating: build_graph extends it, a re-wire through parameter_mapping resets it, and an in-place contract_partially shrinks it to the axis of the layers that are left.

attributen_gatesint

Number of distinct authoring gates currently in the graph.

A multi-term gate expands to several layers sharing one gate, so n_gates \<= graph_layers.

attributeparameter_mappinglist[int]

The parameter mapping owned by the graph, one entry per graph layer.

Entry i is the parameter index driving graph layer i (one generated monomial), in parameter-vector order -- finer-grained than the authoring circuit's per-gate mapping.

attributenum_modesint

Number of modes the simulator acts on (qubits, in the Pauli basis).

attributegraph_layersint

Number of evolved monomials (graph layers).

attributeschrodingerbool

Whether the simulator is in the Schrodinger picture (else Heisenberg).

attributecutoffint

Current cutoff value for the simulation.

attributelower_atolNone | float

Current lower absolute tolerance for the cutoff function (None if unset).

attributeupper_atolNone | float

Current upper absolute tolerance for the cutoff function (None if unset).

attributecutoff_typestr

Current cutoff type, "length" or "support"; read-only outside the Majorana front-end.

Functions

funcfrom_circuit(cls, circuit, initial_operator, **config) -> Self

Construct a propagator from a circuit and propagate it in one step.

The circuit supplies both the gates and the initial state; **config is forwarded to the constructor (cutoff, etc.).

paramcls
paramcircuitCircuit
paraminitial_operatorobject
paramconfigobject
= {}

Returns

typing.Self

A propagator with circuit already evolved via propagate and no graph stored; use build_graph instead when a reusable graph is wanted.

funcbuild_graph(self, circuit, *, seed_parameters=None, only_rotate_len_k=None) -> None

Append a circuit to the propagation graph.

Builds (or extends) the reusable evolution graph, recording each layer's driving parameter and generator coefficient so later evaluation takes only parameters. A circuit's angle indices are local (0-based) and shift onto the accumulated axis when extending.

paramself
paramcircuitCircuit

Gates to append, as a Circuit.

paramseed_parametersParameterValues
= None

Full parameter vector for the whole accumulated graph; regenerates the coefficient seed so truncation sees realistic coefficients. Needed only when extending a non-empty graph with coefficient-informed truncation. Defaults to the circuit's own parameters on the first call; omitted while extending, the new layers are built structurally.

paramonly_rotate_len_kint | None
= None

If given, apply gates to monomials of length <= k even where they anticommute -- useful ahead of expectation-value estimation in the Schrodinger picture with many free-fermionic (length-2 Majorana) generators.

Returns

None
funcpropagate(self, circuit, *, only_rotate_len_k=None) -> None

Evolve and contract immediately, without storing a graph.

Retains no graph, so it is cheaper than build_graph but is one-shot, at the circuit's own parameters.

paramself
paramcircuitCircuit

Gates to apply, and the angle values to apply them at.

paramonly_rotate_len_kint | None
= None

See build_graph.

Returns

None
funcexpectation_value(self, parameters=None) -> float

Compute the expectation value at parameters.

Replays the stored graph against the current initial operator and reference state.

paramself
paramparametersParameterValues
= None

Variational parameter values, as a sequence in parameter-index order or a Circuit (whose parameters are used). None means an empty parameter vector.

Returns

float
funcexpectation_value_and_gradient(self, parameters=None) -> tuple[float, np.ndarray]

Compute the expectation value and gradient in a single backward pass over the graph.

paramself
paramparametersParameterValues
= None

Variational parameter values (see expectation_value).

Returns

tuple

(expectation_value, gradient), with gradient in parameter-axis order.

funcgradient(self, parameters=None) -> np.ndarray

Compute the gradient at parameters, as float64 in parameter-axis order.

paramself
paramparametersParameterValues
= None

Variational parameter values (see expectation_value).

Returns

numpy.numpy.ndarray
funcexpectation_value_functional(self, pare_threshold=None) -> Callable[..., float]

Return a reusable callable computing the expectation value from parameters.

paramself
parampare_thresholdfloat | None
= None

Edge-retention cutoff for this functional's masked plan: edges contributing below it are pared away and skipped during replay, trading memory and accuracy for speed. None (default) disables paring.

Returns

collections.abc.Callable

A callable fn(parameters=None) -> float.

funcexpectation_value_and_gradient_functional(self, pare_threshold=None) -> Callable[..., tuple]

Return a reusable callable computing (expectation value, gradient).

Like expectation_value_functional, but one backward pass also yields the gradient.

paramself
parampare_thresholdfloat | None

Returns

collections.abc.Callable

A callable fn(parameters=None) -> (float, np.ndarray), gradient in parameter order.

funcexpval(self, parameters=None) -> float

Shorthand for expectation_value.

See expectation_value for full documentation.

paramself
paramparametersParameterValues
= None

Returns

float
funcgrad(self, parameters=None) -> np.ndarray

Shorthand for gradient.

See gradient for full documentation.

paramself
paramparametersParameterValues
= None

Returns

numpy.numpy.ndarray
funcexpval_and_grad(self, parameters=None) -> tuple[float, np.ndarray]

Shorthand for expectation_value_and_gradient.

See expectation_value_and_gradient for full documentation.

paramself
paramparametersParameterValues
= None

Returns

tuple[float, numpy.numpy.ndarray]
funcexpval_functional(self, pare_threshold=None) -> Callable[..., float]

Shorthand for expectation_value_functional.

See expectation_value_functional for full documentation.

paramself
parampare_thresholdfloat | None
= None

Returns

collections.abc.Callable[..., float]
funcexpval_and_grad_functional(self, pare_threshold=None) -> Callable[..., tuple]

Shorthand for expectation_value_and_gradient_functional.

See expectation_value_and_gradient_functional for full documentation.

paramself
parampare_thresholdfloat | None
= None

Returns

collections.abc.Callable[..., tuple]
funccontract_partially(self, parameters=None, *, inplace=True) -> np.ndarray

Contract the graph into the operator/state at parameters.

Folds the stored gates, evaluated at parameters, into the operand -- the initial operator in the Heisenberg picture, the reference state in the Schrodinger picture.

paramself
paramparametersParameterValues
= None

Variational parameter values (see expectation_value).

paraminplacebool
= True

True (default) consumes the graph into the internal state, which also rewinds n_parameters to the axis of the layers left behind -- a following build_graph numbers its angles from there. False only returns the coefficients, leaving both the graph and the axis untouched.

Returns

numpy.ndarray

The evolved coefficients as a NumPy array, core term excluded -- of the state in the Schrodinger picture, of the operator in the Heisenberg picture. The array carries no term labels, and across partitions it is each partition's block concatenated in partition order: the same values as an unpartitioned run, but not in a reproducible order, since the partition count is auto-picked from the host's core count. Use evolved_operator when you need coefficients tied to their terms.

funcevolved_operator(self, parameters=None, *, atol=1e-12) -> T_op

Return the evolved operator/state without modifying simulator state.

Equivalent to contract_partially with inplace=False, decoded into a term dict.

paramself
paramparametersParameterValues
= None

Variational parameter values (see expectation_value).

paramatolfloat
= 1e-12

Terms with |coeff| \< atol are dropped; 0.0 keeps all of them.

Returns

monoprop.monomial_propagator.T_op

The evolved operator (Heisenberg picture) or evolved state (Schrodinger picture), keyed by index tuples -- Majorana indices, or gamma slots in the Pauli basis.

funcupdate_initial_operator(self, new_operator) -> None

Replace coefficients of the initial operator (existing terms only).

A re-weight, not a rebuild: the graph, its gates, and their generator coefficients are kept.

paramself
paramnew_operatorT_op

Monomial index tuples mapped to their new complex coefficients.

Returns

None
funcsize(self) -> int

Number of distinct monomial terms in the simulator's current representation.

paramself

Returns

int
funcgraph_size(self) -> tuple[int, int]

Size metrics of the evolution graph.

paramself

Returns

int

(n_cos_indices, n_cycles): cosine-only indices -- terms scaled by a cosine without being a rotation endpoint -- and rotation cycles. The cosine-only count is legitimately 0 when nothing is truncated: every anticommuting term's sine partner then survives.

On this page