---

name: operators-and-transforms description: "Operate on OpenFermion's symbolic and tensor operator representations, normalize and validate terms, and choose or apply fermion-to-qubit mappings." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Operators and transforms

Use this sub-skill when a task needs second-quantized operator algebra, Pauli strings, Majorana or bosonic ladder operators, tensor-backed interaction representations, normal ordering, Hermitian checks, commutators/BCH terms, or a fermion-to-qubit mapping. It covers the public OpenFermion APIs and small, inspectable operators; route model construction and chemistry file formats to hamiltonians-and-chemistry, circuit synthesis/simulation to circuits-and-simulation, and large eigensolvers or RDM workflows to analysis-and-measurements.

Fast route

1. Identify the representation. Use FermionOperator for arbitrary fermionic ladder-polynomials, QubitOperator for sums of Pauli strings, BosonOperator for bosonic ladders, and MajoranaOperator for products of Majorana generators. Use InteractionOperator or PolynomialTensor only when fixed tensor structure and array operations are useful.
2. Construct with explicit conventions. Fermion/boson strings use p^ for creation and p for annihilation. Qubit strings use X0, Y1, or Z2. The empty string/tuple is identity; a no-argument constructor is zero. Keep the factor order of fermionic terms until normal_ordered is called.
3. Validate before mapping. Check count_qubits(op), is_hermitian(op), and the relevant number-preservation predicate. For malformed input, inspect index/action types first; see troubleshooting.
4. Choose a map deliberately. Use jordan_wigner for the direct canonical mapping and broad compatibility; bravyi_kitaev for a Fenwick-tree mapping with an optional explicit qubit count; binary_code_transform for a supplied BinaryCode (including parity, checksum, or qubit-saving codes). Use reverse_jordan_wigner only for the JW inverse direction.
5. Compare representations, not term dictionaries. JW and BK generally produce different Pauli strings but represent equivalent operators. Compare spectra or sparse matrices only after choosing the same Hilbert-space size.
6. Cross the sparse boundary intentionally. Use get_sparse_operator only after mapping/normalization and pass n_qubits for padded fermion/qubit spaces. For bosons, pass a finite trunc; this is a Fock-space cutoff, not a qubit count.

Core recipes

from openfermion import (
    FermionOperator, QubitOperator, bravyi_kitaev, count_qubits,
    hermitian_conjugated, jordan_wigner, normal_ordered,
)

hop = FermionOperator("0^ 1", 0.5)
hop += hermitian_conjugated(hop)
hop = normal_ordered(hop)
assert hop.is_normal_ordered()
print(count_qubits(hop))                 # 2
jw = jordan_wigner(hop)                  # 0.25 [X0 X1] + 0.25 [Y0 Y1]
bk = bravyi_kitaev(hop, n_qubits=2)      # equivalent, different strings

Use op.terms for programmatic inspection. Its keys are tuples of (index, action) pairs: (index, 1)/(index, 0) for creation/annihilation and (index, "X"|"Y"|"Z") for Pauli factors. +=, -=, *=, and /= mutate; ordinary arithmetic returns a copy. Same-type products are algebraically simplified, including Pauli phases. compress() removes near-zero terms; isclose(other, rtol=..., atol=...) is preferable to comparing printed text.

For a quick CPU-only smoke check from any working directory, run the bundled smoke_transform.py helper:

python scripts/smoke_transform.py --help
python scripts/smoke_transform.py --mapping jw --sparse

The helper uses only public imports, a two-mode hopping term, and a tiny sparse matrix; it does not read source files or use the network.

Decision points and boundaries

• normal_ordered is a representation rewrite using canonical anti-commutation/commutation relations; it can increase term count and is exponential in the locality of a ladder term. For chemistry-style two-body operators, chemist_ordered requires a two-body, number-conserving FermionOperator.
• InteractionOperator assumes a number-conserving, Hermitian interaction Hamiltonian structure. It is not a general replacement for an arbitrary FermionOperator; use the latter for non-Hermitian or non-number-conserving expressions.
• jordan_wigner maps FermionOperator, MajoranaOperator, InteractionOperator, and diagonal Coulomb representations, but has no n_qubits argument. bravyi_kitaev accepts FermionOperator, MajoranaOperator, and InteractionOperator; its n_qubits may pad the first two kinds. Never pass a value below count_qubits.
• Custom binary codes are constrained by the code's n_modes and n_qubits; they are not a general way to pad an operator. Nonlinear or qubit-saving codes can expand a term into many Pauli strings.
• reverse_jordan_wigner accepts only a QubitOperator and returns a FermionOperator; it is not a general inverse for BK or arbitrary binary codes. Round-trip after compress() is the useful correctness check.
• Sparse conversion is a representation boundary, not a solver. Keep large eigenspectrum, ground-state, RDM, measurement, and model-builder work in the routed sub-skills.

For signatures, term schemas, tensor indexing, and concrete expected outputs, read api-reference.md. For mapping formulas, variants, qubit-count rules, and binary-code choices, read transforms.md. For failure diagnosis, read troubleshooting.md.

Recovery guidance

When recovering an operator transformation from partial notes, first reconstruct the exact term tuple and coefficient, then normal-order it and record count_qubits. Build the smallest Hermitian hopping or number-operator fixture, map it with JW and the selected alternative, and compare canonical algebra (commutator/anticommutator), term counts, and—when feasible—small sparse matrices. Do not infer a BK or binary-code qubit count from a printed term: carry the explicit n_qubits/code dimensions through the experiment. Preserve whether a mismatch is a convention issue (mode order, creation order, or Majorana indexing), an invalid input, or a true transform limitation.