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_parametersintSize 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_gatesintNumber 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_modesintNumber of modes the simulator acts on (qubits, in the Pauli basis).
attributegraph_layersintNumber of evolved monomials (graph layers).
attributeschrodingerboolWhether the simulator is in the Schrodinger picture (else Heisenberg).
attributecutoffintCurrent cutoff value for the simulation.
attributelower_atolNone | floatCurrent lower absolute tolerance for the cutoff function (None if unset).
attributeupper_atolNone | floatCurrent upper absolute tolerance for the cutoff function (None if unset).
attributecutoff_typestrCurrent cutoff type, "length" or "support"; read-only outside the Majorana front-end.
Functions
funcfrom_circuit(cls, circuit, initial_operator, **config) -> SelfConstruct 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.).
paramclsparamcircuitCircuitparaminitial_operatorobjectparamconfigobject= {}Returns
typing.SelfA 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) -> NoneAppend 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.
paramselfparamcircuitCircuitGates to append, as a Circuit.
paramseed_parametersParameterValues= NoneFull 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= NoneIf 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
Nonefuncpropagate(self, circuit, *, only_rotate_len_k=None) -> NoneEvolve 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.
paramselfparamcircuitCircuitGates to apply, and the angle values to apply them at.
paramonly_rotate_len_kint | None= NoneSee build_graph.
Returns
Nonefuncexpectation_value(self, parameters=None) -> floatCompute the expectation value at parameters.
Replays the stored graph against the current initial operator and reference state.
paramselfparamparametersParameterValues= NoneVariational parameter values, as a sequence in parameter-index order or a
Circuit (whose parameters are used). None means an
empty parameter vector.
Returns
floatfuncexpectation_value_and_gradient(self, parameters=None) -> tuple[float, np.ndarray]Compute the expectation value and gradient in a single backward pass over the graph.
paramselfparamparametersParameterValues= NoneVariational parameter values (see expectation_value).
Returns
tuple(expectation_value, gradient), with gradient in parameter-axis order.
funcgradient(self, parameters=None) -> np.ndarrayCompute the gradient at parameters, as float64 in parameter-axis order.
paramselfparamparametersParameterValues= NoneVariational parameter values (see expectation_value).
Returns
numpy.numpy.ndarrayfuncexpectation_value_functional(self, pare_threshold=None) -> Callable[..., float]Return a reusable callable computing the expectation value from parameters.
paramselfparampare_thresholdfloat | None= NoneEdge-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.CallableA 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.
paramselfparampare_thresholdfloat | None= NoneReturns
collections.abc.CallableA callable fn(parameters=None) -> (float, np.ndarray), gradient in parameter order.
funcexpval(self, parameters=None) -> floatShorthand for expectation_value.
See expectation_value for full documentation.
paramselfparamparametersParameterValues= NoneReturns
floatfuncgrad(self, parameters=None) -> np.ndarrayfuncexpval_and_grad(self, parameters=None) -> tuple[float, np.ndarray]Shorthand for expectation_value_and_gradient.
See expectation_value_and_gradient for full documentation.
paramselfparamparametersParameterValues= NoneReturns
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.
paramselfparampare_thresholdfloat | None= NoneReturns
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.
paramselfparampare_thresholdfloat | None= NoneReturns
collections.abc.Callable[..., tuple]funccontract_partially(self, parameters=None, *, inplace=True) -> np.ndarrayContract 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.
paramselfparamparametersParameterValues= NoneVariational parameter values (see expectation_value).
paraminplacebool= TrueTrue (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.ndarrayThe 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_opReturn the evolved operator/state without modifying simulator state.
Equivalent to contract_partially with inplace=False, decoded into a term dict.
paramselfparamparametersParameterValues= NoneVariational parameter values (see expectation_value).
paramatolfloat= 1e-12Terms with |coeff| \< atol are dropped; 0.0 keeps all of them.
Returns
monoprop.monomial_propagator.T_opThe 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) -> NoneReplace coefficients of the initial operator (existing terms only).
A re-weight, not a rebuild: the graph, its gates, and their generator coefficients are kept.
paramselfparamnew_operatorT_opMonomial index tuples mapped to their new complex coefficients.
Returns
Nonefuncsize(self) -> intNumber of distinct monomial terms in the simulator's current representation.
paramselfReturns
intfuncgraph_size(self) -> tuple[int, int]Size metrics of the evolution graph.
paramselfReturns
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.