symop.ccr.algebra.op.from_words

Construct operator terms from ladder-operator words.

This module provides a small helper that materializes operator words into tuples of ladder operators and pairs them with coefficients. The resulting term objects are created via a caller-provided factory, which keeps this function independent of concrete term implementations and avoids import cycles.

In the operator-algebra view, a single term corresponds to a “word” in ladder operators with a scalar prefactor:

\[T = c * o_1 o_2 ... o_L,\]

where each \(o_k\) is a ladder operator instance.

Functions

from_words(words[, coeffs])

Build operator terms from raw operator words and coefficients.
from_words(words: Iterable[Iterable[LadderOp]], coeffs: Iterable[complex] | None = None, *, term_factory: Callable[[tuple[LadderOp, ...], complex], OpTermT]) → tuple[OpTermT, ...]

Build operator terms from raw operator words and coefficients.

Each input word is materialized into a tuple of ladder operators and paired with a coefficient. The output term objects are constructed using the provided term_factory.

Parameters:

  • words (Iterable[Iterable[LadderOp]]) – Iterable of operator words, each a sequence of ladder operators.

  • coeffs (Iterable[complex] | None) – Optional coefficients. If omitted, each word gets coefficient 1.0. If provided, the number of coefficients must match the number of words.

  • term_factory (Callable[[tuple[LadderOp, ...], complex], TypeVar(OpTermT, bound= OpTerm)]) – Callable constructing a term from (ops, coeff).

Returns:

Tuple of constructed operator terms.

Return type:

tuple[OpTermT, …]

Raises:

ValueError – If coeffs is provided and its length does not match the number of materialized words.

Notes

This function intentionally does not provide a default factory to avoid coupling to concrete implementations and to prevent circular imports. Callers such as OpPoly.from_words should supply their concrete term class.