Protocols

This module provides various protocols used throughout the package.

A typing.Protocol is an interface that a class can fulfill structurally, without explicitly inheriting from it. For example, any class that implements a __len__ method satisfies Sized, whether or not it says so anywhere in its class hierarchy.

The protocols in this module follow the same idea, but each one centers on a single, otherwise unremarkable dunder-style method (for example _majorana_operator_). A class implementing that one method thereby satisfies the corresponding protocol (SupportsMajoranaOperator in this example) and becomes usable wherever that protocol is expected, without any explicit registration. Note that “protocol” is sometimes also used loosely to refer to a type-agnostic dispatch function built on top of a protocol (for example fermion_operator()) rather than the interface itself; the distinction should be clear from context.

Some protocols below are paired with a small, type-agnostic helper function that dispatches to the protocol method on whatever object it is given.

Protocol	Method	Helper function
SupportsFermionOperator	_fermion_operator_(self)	fermion_operator()
SupportsMajoranaOperator	_majorana_operator_(self)	majorana_operator()
SupportsApplyUnitaryPlaced	_apply_unitary_placed_(self, vec, norb, nelec, copy, freg_indices)	–
SupportsCommutators	_commutator_, _anti_commutator_, _double_commutator_ (all @staticmethod)	commutator(), anti_commutator(), double_commutator()

SupportsApplyUnitaryPlaced(*args, **kwargs)	A package-specific extension of ffsim.SupportsApplyUnitary.
SupportsCommutators(*args, **kwargs)	A Protocol indicating support for efficient commutator generation.
SupportsFermionOperator(*args, **kwargs)	This package's operator-conversion contract, converting an operator to a FermionOperator.
SupportsMajoranaOperator(*args, **kwargs)	An equivalent of the SupportsFermionOperator protocol, targeting Majorana operators.

Protocols implemented from ffsim

Simulation is ffsim’s concern, and its protocols are defined there rather than restated here. The gates and operators of this package implement the following, so ffsim’s dispatchers accept them directly:

ffsim protocol	Method	Implemented by
ffsim.SupportsApplyUnitary	_apply_unitary_(self, vec, norb, nelec, copy)	FermionicCircuit and every FermionicGate
ffsim.SupportsLinearOperator	_linear_operator_(self, norb, nelec)	FermionOperator
ffsim.SupportsTrace	_trace_(self, norb, nelec)	FermionOperator

Caution

ffsim.SupportsFermionOperator shares the _fermion_operator_ method name with this package’s SupportsFermionOperator, but the two are not the same contract: ours returns this package’s FermionOperator rather than ffsim’s unrelated type. Since ffsim.fermion_operator() dispatches purely on the method name, calling it on an object of this package returns our type.