fockit 0.0.2__py3-none-any.whl

fockit/__init__.py

@@ -0,0 +1,53 @@
+"""Symbolic operator algebra for fermions, bosons, and beyond."""
+
+from fockit.constructors import (
+    b,
+    bdag,
+    c,
+    cdag,
+    n,
+    nb,
+    sigma_x,
+    sigma_y,
+    sigma_z,
+    sm,
+    sp,
+)
+from fockit.display import to_latex, to_text
+from fockit.inspection import degree, modes, num_terms
+from fockit.normal_order import is_normal_ordered, normal_order
+from fockit.operators import (
+    identity,
+    zero,
+)
+from fockit.simplify import drop_zeros, simplify_coeffs
+from fockit.transforms import anticommutator, commutator, hc, substitute_modes
+
+__all__ = [
+    "anticommutator",
+    "b",
+    "bdag",
+    "c",
+    "cdag",
+    "commutator",
+    "degree",
+    "drop_zeros",
+    "hc",
+    "identity",
+    "is_normal_ordered",
+    "modes",
+    "n",
+    "nb",
+    "normal_order",
+    "num_terms",
+    "sigma_x",
+    "sigma_y",
+    "sigma_z",
+    "simplify_coeffs",
+    "sm",
+    "sp",
+    "substitute_modes",
+    "to_latex",
+    "to_text",
+    "zero",
+]

fockit/_types.py

@@ -0,0 +1,48 @@
+"""Shared typing helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from typing import Protocol, SupportsComplex, SupportsFloat, SupportsIndex, cast
+
+type Mode = Hashable
+
+
+class SymbolicCoefficient(Protocol):
+    """Protocol for symbolic coefficient objects."""
+
+    def __hash__(self) -> int: ...
+
+    def __add__(self, other: object, /) -> object: ...
+
+    def __radd__(self, other: object, /) -> object: ...
+
+    def __sub__(self, other: object, /) -> object: ...
+
+    def __rsub__(self, other: object, /) -> object: ...
+
+    def __mul__(self, other: object, /) -> object: ...
+
+    def __rmul__(self, other: object, /) -> object: ...
+
+    def __neg__(self) -> object: ...
+
+    def __abs__(self) -> object: ...
+
+    def __eq__(self, other: object, /) -> bool: ...
+
+    def conjugate(self) -> object: ...
+
+
+type Coefficient = int | float | complex | SymbolicCoefficient
+type ComplexConvertible = complex | SupportsComplex | SupportsFloat | SupportsIndex
+
+
+def as_coefficient(value: object) -> Coefficient:
+    """Cast a coefficient result back to ``Coefficient``."""
+    return cast(Coefficient, value)
+
+
+def as_complex(value: Coefficient) -> complex:
+    """Convert a coefficient to ``complex``."""
+    return complex(cast(ComplexConvertible, value))

fockit/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.2'
+__version_tuple__ = version_tuple = (0, 0, 2)
+
+__commit_id__ = commit_id = None

fockit/algebra.py

@@ -0,0 +1,275 @@
+"""Algebra rules protocol and concrete implementations."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from dataclasses import dataclass, replace
+from enum import StrEnum
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from fockit._types import Coefficient
+
+if TYPE_CHECKING:
+    from fockit.operators import Op
+
+
+class Ladder(StrEnum):
+    """Operator kinds for fermions and bosons."""
+
+    CREATE = "+"
+    ANNIHILATE = "-"
+
+
+class Pauli(StrEnum):
+    """Operator kinds for Pauli matrices."""
+
+    X = "x"
+    Y = "y"
+    Z = "z"
+
+
+@dataclass(frozen=True)
+class SwapResult:
+    """Result of swapping two adjacent operators.
+
+    Each entry in ``terms`` is a ``(Coefficient, tuple[Op, ...])`` pair,
+    where the tuple replaces the original two-operator subsequence.
+
+    Parameters
+    ----------
+    terms : tuple[tuple[Coefficient, tuple[Op, ...]], ...]
+        The replacement terms.
+
+    Notes
+    -----
+    For the normal ordering algorithm to terminate, each replacement must
+    either shorten the pair (length 0 or 1) or reduce the number of
+    inversions (length 2).
+
+    """
+
+    terms: tuple[tuple[Coefficient, tuple[Op, ...]], ...]
+
+
+@runtime_checkable
+class AlgebraRules(Protocol):
+    """Protocol defining the (anti)commutation relations for an algebra.
+
+    Methods only ever receive operators of this algebra. Operators of
+    different algebras commute.
+
+    Notes
+    -----
+    Implementations MUST define ``__eq__`` and ``__hash__`` so that two
+    instances representing the same algebra compare equal and are usable
+    as ``lru_cache`` keys.
+
+    """
+
+    def swap(self, left: Op, right: Op) -> SwapResult:
+        """Define what happens when ``left`` and ``right`` are exchanged.
+
+        Parameters
+        ----------
+        left : Op
+        right : Op
+
+        Returns
+        -------
+        SwapResult
+
+        """
+        ...
+
+    def is_normal_ordered_pair(self, left: Op, right: Op) -> bool:
+        """Return True if ``(left, right)`` is already in normal order.
+
+        Parameters
+        ----------
+        left : Op
+        right : Op
+
+        Returns
+        -------
+        bool
+
+        """
+        ...
+
+    def dagger(self, op: Op) -> Op:
+        """Return the Hermitian conjugate of a single operator.
+
+        Parameters
+        ----------
+        op : Op
+
+        Returns
+        -------
+        Op
+
+        """
+        ...
+
+    def __hash__(self) -> int:
+        """Return hash for use as ``lru_cache`` key."""
+        ...
+
+
+class FermionRules:
+    """Canonical anticommutation relations: {c_a, c†_b} = delta_{ab}."""
+
+    def swap(self, left: Op, right: Op) -> SwapResult:
+        """Apply fermion swap rules."""
+        if left == right:
+            return SwapResult(terms=())  # c c = 0
+        swapped = ((-1, (right, left)),)
+        if (
+            left.kind is Ladder.ANNIHILATE
+            and right.kind is Ladder.CREATE
+            and left.mode == right.mode
+        ):
+            return SwapResult(terms=((1, ()), *swapped))
+        return SwapResult(terms=swapped)
+
+    def is_normal_ordered_pair(self, left: Op, right: Op) -> bool:
+        """Check if a pair is in fermionic normal order.
+
+        Creators left, canonical mode order within blocks.
+        """
+        if left == right:
+            return False
+        if left.kind is Ladder.CREATE and right.kind is Ladder.ANNIHILATE:
+            return True
+        if left.kind is Ladder.ANNIHILATE and right.kind is Ladder.CREATE:
+            return False
+        return mode_sort_key(left.mode) <= mode_sort_key(right.mode)
+
+    def dagger(self, op: Op) -> Op:
+        """Flip creation ↔ annihilation."""
+        flipped = Ladder.CREATE if op.kind is Ladder.ANNIHILATE else Ladder.ANNIHILATE
+        return replace(op, kind=flipped)
+
+    def __eq__(self, other: object) -> bool:  # noqa: D105
+        return isinstance(other, FermionRules)
+
+    def __hash__(self) -> int:  # noqa: D105
+        return hash(type(self))
+
+    def __repr__(self) -> str:  # noqa: D105
+        return "FermionRules()"
+
+
+class BosonRules:
+    """Canonical commutation relations: [b_a, b†_b] = delta_{ab}."""
+
+    def swap(self, left: Op, right: Op) -> SwapResult:
+        """Apply boson swap rules."""
+        swapped = ((+1, (right, left)),)
+        if (
+            left.kind is Ladder.ANNIHILATE
+            and right.kind is Ladder.CREATE
+            and left.mode == right.mode
+        ):
+            return SwapResult(terms=((1, ()), *swapped))
+        return SwapResult(terms=swapped)
+
+    def is_normal_ordered_pair(self, left: Op, right: Op) -> bool:
+        """Check normal ordering for bosonic operators."""
+        if left.kind is Ladder.CREATE and right.kind is Ladder.ANNIHILATE:
+            return True
+        if left.kind is Ladder.ANNIHILATE and right.kind is Ladder.CREATE:
+            return False
+        return mode_sort_key(left.mode) <= mode_sort_key(right.mode)
+
+    def dagger(self, op: Op) -> Op:
+        """Flip creation ↔ annihilation."""
+        flipped = Ladder.CREATE if op.kind is Ladder.ANNIHILATE else Ladder.ANNIHILATE
+        return replace(op, kind=flipped)
+
+    def __eq__(self, other: object) -> bool:  # noqa: D105
+        return isinstance(other, BosonRules)
+
+    def __hash__(self) -> int:  # noqa: D105
+        return hash(type(self))
+
+    def __repr__(self) -> str:  # noqa: D105
+        return "BosonRules()"
+
+
+_PAULI_PRODUCT: dict[tuple[Hashable, Hashable], tuple[complex, Hashable]] = {
+    (Pauli.X, Pauli.Y): (1j, Pauli.Z),
+    (Pauli.Y, Pauli.X): (-1j, Pauli.Z),
+    (Pauli.Y, Pauli.Z): (1j, Pauli.X),
+    (Pauli.Z, Pauli.Y): (-1j, Pauli.X),
+    (Pauli.Z, Pauli.X): (1j, Pauli.Y),
+    (Pauli.X, Pauli.Z): (-1j, Pauli.Y),
+}
+
+
+class PauliRules:
+    """Pauli algebra: σ_a σ_b = δ_ab + i ε_abc σ_c on a site, commute across sites."""
+
+    def swap(self, left: Op, right: Op) -> SwapResult:
+        """Commute across sites, multiply out on the same site."""
+        if left.mode != right.mode:
+            return SwapResult(terms=((+1, (right, left)),))
+        if left.kind == right.kind:
+            return SwapResult(terms=((1, ()),))
+        phase, kind = _PAULI_PRODUCT[(left.kind, right.kind)]
+        return SwapResult(terms=((phase, (replace(left, kind=kind),)),))
+
+    def is_normal_ordered_pair(self, left: Op, right: Op) -> bool:
+        """Sites in mode order, at most one operator per site."""
+        if left.mode == right.mode:
+            return False
+        return mode_sort_key(left.mode) <= mode_sort_key(right.mode)
+
+    def dagger(self, op: Op) -> Op:
+        """Pauli operators are Hermitian: dagger is identity."""
+        return op
+
+    def __eq__(self, other: object) -> bool:  # noqa: D105
+        return isinstance(other, PauliRules)
+
+    def __hash__(self) -> int:  # noqa: D105
+        return hash(type(self))
+
+    def __repr__(self) -> str:  # noqa: D105
+        return "PauliRules()"
+
+
+FERMION = FermionRules()
+BOSON = BosonRules()
+PAULI = PauliRules()
+
+
+def mode_sort_key(mode: Hashable) -> tuple[object, ...]:
+    """Canonical sort key for modes.
+
+    Stratifies by type first, then compares within type.
+
+    Parameters
+    ----------
+    mode : Hashable
+        The mode label.
+
+    Returns
+    -------
+    tuple
+        A universally comparable sort key.
+
+    Notes
+    -----
+    ``bool`` is a subclass of ``int``, so ``True`` and ``1`` produce
+    identical sort keys. Avoid using ``bool`` values as modes.
+
+    """
+    match mode:
+        case int():
+            return (0, mode)
+        case str():
+            return (1, mode)
+        case tuple():
+            return (2, *(mode_sort_key(m) for m in mode))
+        case _:
+            return (3, repr(mode))

fockit/constructors.py

@@ -0,0 +1,280 @@
+"""Constructor functions for operator expressions."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+
+from fockit.algebra import BOSON, FERMION, PAULI, AlgebraRules, Ladder, Pauli
+from fockit.operators import Monomial, Op, OpSum
+
+
+def _mode(*labels: Hashable) -> Hashable:
+    return labels if len(labels) > 1 else labels[0]
+
+
+def create(*labels: Hashable, rules: AlgebraRules = FERMION) -> OpSum:
+    """Creation operator with the given mode label(s).
+
+    If one label given: mode is that label.
+    If multiple labels given: mode is the tuple of labels.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+    rules : AlgebraRules, optional
+        Algebra rules. Default: ``FERMION``.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return OpSum({Monomial(ops=(Op(_mode(*labels), Ladder.CREATE, rules),)): 1})
+
+
+def annihilate(*labels: Hashable, rules: AlgebraRules = FERMION) -> OpSum:
+    """Annihilation operator.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+    rules : AlgebraRules, optional
+        Algebra rules. Default: ``FERMION``.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return OpSum({Monomial(ops=(Op(_mode(*labels), Ladder.ANNIHILATE, rules),)): 1})
+
+
+def number(*labels: Hashable, rules: AlgebraRules = FERMION) -> OpSum:
+    """Return the number operator create† * annihilate.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+    rules : AlgebraRules, optional
+        Algebra rules. Default: ``FERMION``.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return create(*labels, rules=rules) * annihilate(*labels, rules=rules)
+
+
+def cdag(*labels: Hashable) -> OpSum:
+    """Fermionic creation operator c†.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return create(*labels, rules=FERMION)
+
+
+def c(*labels: Hashable) -> OpSum:
+    """Fermionic annihilation operator c.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return annihilate(*labels, rules=FERMION)
+
+
+def n(*labels: Hashable) -> OpSum:
+    """Fermionic number operator n = c† c.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return number(*labels, rules=FERMION)
+
+
+def bdag(*labels: Hashable) -> OpSum:
+    """Bosonic creation operator b†.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return create(*labels, rules=BOSON)
+
+
+def b(*labels: Hashable) -> OpSum:
+    """Bosonic annihilation operator b.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return annihilate(*labels, rules=BOSON)
+
+
+def nb(*labels: Hashable) -> OpSum:
+    """Bosonic number operator n_b = b† b.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return number(*labels, rules=BOSON)
+
+
+def sp(*labels: Hashable) -> OpSum:
+    """Pauli raising operator σ+ = (σx + iσy)/2.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return 0.5 * sigma_x(*labels) + 0.5j * sigma_y(*labels)
+
+
+def sm(*labels: Hashable) -> OpSum:
+    """Pauli lowering operator σ- = (σx - iσy)/2.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return 0.5 * sigma_x(*labels) - 0.5j * sigma_y(*labels)
+
+
+def sigma_plus(*labels: Hashable) -> OpSum:
+    """Pauli raising operator σ+.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return sp(*labels)
+
+
+def sigma_minus(*labels: Hashable) -> OpSum:
+    """Pauli lowering operator σ-.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    return sm(*labels)
+
+
+def sigma_x(*labels: Hashable) -> OpSum:
+    """Pauli σ_x operator.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    mode = _mode(*labels)
+    return OpSum({Monomial(ops=(Op(mode, Pauli.X, PAULI),)): 1})
+
+
+def sigma_y(*labels: Hashable) -> OpSum:
+    """Pauli σ_y operator.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    mode = _mode(*labels)
+    return OpSum({Monomial(ops=(Op(mode, Pauli.Y, PAULI),)): 1})
+
+
+def sigma_z(*labels: Hashable) -> OpSum:
+    """Pauli σ_z operator.
+
+    Parameters
+    ----------
+    *labels : Hashable
+        Mode label components.
+
+    Returns
+    -------
+    OpSum
+
+    """
+    mode = _mode(*labels)
+    return OpSum({Monomial(ops=(Op(mode, Pauli.Z, PAULI),)): 1})