TensorPattern

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

TensorPattern

class TensorPattern

Representation-aware Symbolica patterns for matching tensor expressions.

Scalar arguments and structural ports are specified separately. Either section can contain Symbolica wildcards, including sequence wildcards. Unlike TensorExpression, a pattern does not require a concrete rank or compatible external tensor axes. Use patterns with TensorRule for checked whole-tensor replacements, or with ordinary Expression matching.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.dirac_gamma(D_, i_, j_, mu_)

Methods

Name	Description
__new__	Match a fixed tensor function with separately specified arguments and ports.
antisymmetric	Match a normalized antisymmetric group of matrix factors.
any	Match any tensor-tagged function.
casimir	Match a symbolic Casimir invariant.
chain	Match an ordered tensor chain with endpoints and factor patterns.
charge_conjugation	Match the Dirac charge-conjugation matrix.
color_f	Match the antisymmetric color structure constants f^{abc}.
color_t	Match the fundamental color generators T^a.
cyclic	Match a normalized cyclic group of matrix factors.
dirac_gamma	Match the Dirac gamma matrices for Clifford algebra.
dot	Match a compact tensor dot product.
dynkin_index	Match a symbolic Dynkin index.
flat	Match the metric map for raising or lowering an index.
g	Match the metric pairing.
gamma0	Match the time-component Dirac matrix gamma^0.
gamma5	Match the Dirac chirality matrix gamma^5.
levi_civita	Match the totally antisymmetric Levi-Civita tensor.
projm	Match the left-chiral Dirac projector (I - gamma^5)/2.
projp	Match the right-chiral Dirac projector (I + gamma^5)/2.
sigma	Match the antisymmetric Dirac sigma tensor.
symmetric	Match a normalized symmetric group of matrix factors.
trace	Match a compact cyclic trace.
vector	Match a function tagged as a rank-one tensor.

__new__

TensorPattern.__new__(
    head: TensorName,
    *,
    args: typing.Sequence[_ScalarInput] = [],
    ports: typing.Sequence[Slot | Representation | _ScalarInput] = [],
) -> TensorPattern

Related types: TensorName, Slot, Representation

Match a fixed tensor function with separately specified arguments and ports.

Parameters

• head (TensorName) Exact tensor function head to match.
• args (sequence of scalar expressions, default []) Non-index tensor arguments, including ordinary or sequence wildcards.
• ports (sequence of Slot, Representation, or Expression, default []) Structural port patterns, placed after args. PortPattern and sequence wildcards can describe representations, indices, or variable arity.

Returns

• TensorPattern Pattern expression with args before ports.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern(TensorName("B"), ports=[PortPattern.exact(Representation.euc(3), i_)])

antisymmetric

TensorPattern.antisymmetric(*factors: _ScalarInput) -> TensorPattern

Match a normalized antisymmetric group of matrix factors.

Parameters

• *factors (scalar expression) Patterns for the grouped factors, including sequence wildcards.

Returns

• TensorPattern Pattern for the compact FactorProjector syntax inside a chain or trace.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.antisymmetric(S("factors___"))

any

TensorPattern.any(
    name: builtins.str,
    *,
    args: typing.Sequence[_ScalarInput] = [],
    ports: typing.Sequence[Slot | Representation | _ScalarInput] = [],
) -> TensorPattern

Related types: Slot, Representation

Match any tensor-tagged function.

Parameters

• name (str) Wildcard function name ending in exactly one underscore.
• args (sequence of scalar expressions, default []) Non-index tensor arguments, including ordinary or sequence wildcards.
• ports (sequence of Slot, Representation, or Expression, default []) Structural port patterns, placed after args. PortPattern and sequence wildcards can describe representations, indices, or variable arity.

Returns

• TensorPattern Tagged pattern. Concrete arity is not imposed, so sequence wildcards can match the argument and port lists.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
rest = S("ports___")
pattern = TensorPattern.any("T_", ports=[rest])

casimir

TensorPattern.casimir(
    degree: _ScalarInput,
    representation: Representation | Expression,
) -> TensorPattern

Related types: Representation, Expression

Match a symbolic Casimir invariant.

Parameters

• degree (scalar expression) Invariant degree or wildcard.
• representation (Representation or Expression) Exact representation, representation pattern, or wildcard.

Returns

• TensorPattern Pattern for a scalar representation invariant.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.casimir(S("degree_"), S("rep_"))

chain

TensorPattern.chain(
    start: Slot | Representation | _ScalarInput,
    end: Slot | Representation | _ScalarInput,
    *factors: _ScalarInput,
) -> TensorPattern

Related types: Slot, Representation

Match an ordered tensor chain with endpoints and factor patterns.

Parameters

• start, end (Slot, Representation, or Expression) Endpoint patterns.
• *factors (scalar expression) Ordered factor patterns, optionally including sequence wildcards. Contextual PortPattern.chain_in() and chain_out() can select a factor’s orientation.

Returns

• TensorPattern A chain pattern that does not infer a concrete matrix interface.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.chain(i_, j_, S("factors___"))

charge_conjugation

TensorPattern.charge_conjugation(
    spinor_dimension: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the Dirac charge-conjugation matrix.

Parameters

• spinor_dimension (scalar expression) Spinor dimension or wildcard.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.charge_conjugation(D_, i_, j_)

color_f

TensorPattern.color_f(
    adjoint_dimension: _ScalarInput,
    a: _ScalarInput,
    b: _ScalarInput,
    c: _ScalarInput,
) -> TensorPattern

Match the antisymmetric color structure constants f^{abc}.

Parameters

• adjoint_dimension (scalar expression) Adjoint dimension or wildcard, e.g. 8 for SU(3).
• a, b, c (scalar expression) Patterns for the three adjoint indices.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.color_f(D_, a_, b_, c_)

color_t

TensorPattern.color_t(
    adjoint_dimension: _ScalarInput,
    fundamental_dimension: _ScalarInput,
    a: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the fundamental color generators T^a.

Parameters

• adjoint_dimension (scalar expression) Adjoint dimension or wildcard, e.g. 8 for SU(3).
• fundamental_dimension (scalar expression) Fundamental dimension or wildcard, e.g. 3 for SU(3).
• a (scalar expression) Adjoint-index pattern.
• i, j (scalar expression) Fundamental and antifundamental index patterns, or contextual endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.color_t(D_, S("N_"), a_, i_, j_)

cyclic

TensorPattern.cyclic(*factors: _ScalarInput) -> TensorPattern

Match a normalized cyclic group of matrix factors.

Parameters

• *factors (scalar expression) Patterns for the grouped factors, including sequence wildcards.

Returns

• TensorPattern Pattern for the compact FactorProjector syntax inside a chain or trace.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.cyclic(S("factors___"))

dirac_gamma

TensorPattern.dirac_gamma(
    minkowski_dimension: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
    mu: _ScalarInput,
) -> TensorPattern

Match the Dirac gamma matrices for Clifford algebra.

Parameters

• minkowski_dimension (scalar expression) Minkowski dimension or wildcard. Spinor dimensions are fixed at four.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.
• mu (scalar expression) Lorentz-index pattern.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.dirac_gamma(D_, i_, j_, mu_)

dot

TensorPattern.dot(left: _ScalarInput, right: _ScalarInput) -> TensorPattern

Match a compact tensor dot product.

Parameters

• left, right (scalar expression) Operand patterns, including unrestricted wildcards.

Returns

• TensorPattern Pattern for the compact dot notation, not explicit indexed products.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.dot(S("left_"), S("right_"))

dynkin_index

TensorPattern.dynkin_index(
    degree: _ScalarInput,
    representation: Representation | Expression,
) -> TensorPattern

Related types: Representation, Expression

Match a symbolic Dynkin index.

Parameters

• degree (scalar expression) Invariant degree or wildcard.
• representation (Representation or Expression) Exact representation, representation pattern, or wildcard.

Returns

• TensorPattern Pattern for a scalar representation invariant.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.dynkin_index(S("degree_"), S("rep_"))

flat

TensorPattern.flat(
    rep_pattern: Representation | Expression,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Related types: Representation, Expression

Match the metric map for raising or lowering an index.

Parameters

• rep_pattern (Representation or Expression) Exact space or a representation-only PortPattern.
• i, j (scalar expression) Index values, wildcards, or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.flat(Representation.euc(D_), i_, j_)

g

TensorPattern.g(
    rep_pattern: Representation | Expression,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Related types: Representation, Expression

Match the metric pairing.

Parameters

• rep_pattern (Representation or Expression) Exact space or a representation-only PortPattern.
• i, j (scalar expression) Index values, wildcards, or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.g(Representation.euc(D_), i_, j_)

gamma0

TensorPattern.gamma0(
    spinor_dimension: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the time-component Dirac matrix gamma^0.

Parameters

• spinor_dimension (scalar expression) Spinor dimension or wildcard.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.gamma0(D_, i_, j_)

gamma5

TensorPattern.gamma5(
    spinor_dimension: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the Dirac chirality matrix gamma^5.

Parameters

• spinor_dimension (scalar expression) Spinor dimension or wildcard.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.gamma5(D_, i_, j_)

levi_civita

TensorPattern.levi_civita(
    rep_pattern: Representation | Expression,
    *indices: _ScalarInput,
) -> TensorPattern

Related types: Representation, Expression

Match the totally antisymmetric Levi-Civita tensor.

Parameters

• rep_pattern (Representation or Expression) Exact space or a representation-only PortPattern.
• *indices (scalar expression) One index pattern per axis; their number fixes the rank.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Notes

For an unrestricted number of epsilon axes, use TensorPattern(TensorName.levi_civita(), ports=[ports___]).

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.levi_civita(Representation.euc(D_), i_, j_, a_)

projm

TensorPattern.projm(
    spinor_dimension: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the left-chiral Dirac projector (I - gamma^5)/2.

Parameters

• spinor_dimension (scalar expression) Spinor dimension or wildcard.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.projm(D_, i_, j_)

projp

TensorPattern.projp(
    spinor_dimension: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the right-chiral Dirac projector (I + gamma^5)/2.

Parameters

• spinor_dimension (scalar expression) Spinor dimension or wildcard.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.projp(D_, i_, j_)

sigma

TensorPattern.sigma(
    minkowski_dimension: _ScalarInput,
    mu: _ScalarInput,
    nu: _ScalarInput,
    i: _ScalarInput,
    j: _ScalarInput,
) -> TensorPattern

Match the antisymmetric Dirac sigma tensor.

Parameters

• minkowski_dimension (scalar expression) Minkowski dimension or wildcard. Spinor dimensions are fixed at four.
• i, j (scalar expression) Spinor-index patterns or contextual chain endpoints.
• mu, nu (scalar expression) Lorentz-index patterns.

Returns

• TensorPattern Registered tensor syntax with representation-aware port patterns. Wildcards are retained rather than checked as a concrete tensor.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.sigma(D_, mu_, nu_, i_, j_)

symmetric

TensorPattern.symmetric(*factors: _ScalarInput) -> TensorPattern

Match a normalized symmetric group of matrix factors.

Parameters

• *factors (scalar expression) Patterns for the grouped factors, including sequence wildcards.

Returns

• TensorPattern Pattern for the compact FactorProjector syntax inside a chain or trace.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.symmetric(S("factors___"))

trace

TensorPattern.trace(
    representation: Representation | Expression,
    *factors: _ScalarInput,
) -> TensorPattern

Related types: Representation, Expression

Match a compact cyclic trace.

Parameters

• representation (Representation or Expression) Exact traced space, representation pattern, or wildcard.
• *factors (scalar expression) Factor patterns, optionally including sequence wildcards.

Returns

• TensorPattern Trace pattern with the cyclic factor wrapper used by tensor notation.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
pattern = TensorPattern.trace(Representation.euc(3), S("factors___"))

vector

TensorPattern.vector(
    name: builtins.str,
    *,
    args: typing.Sequence[_ScalarInput] = [],
    ports: typing.Sequence[Slot | Representation | _ScalarInput] = [],
) -> TensorPattern

Related types: Slot, Representation

Match a function tagged as a rank-one tensor.

Parameters

• name (str) Wildcard function name ending in exactly one underscore.
• args (sequence of scalar expressions, default []) Non-index tensor arguments, including ordinary or sequence wildcards.
• ports (sequence of Slot, Representation, or Expression, default []) Structural port patterns, placed after args. PortPattern and sequence wildcards can describe representations, indices, or variable arity.

Returns

• TensorPattern Tagged pattern. Concrete arity is not imposed, so sequence wildcards can match the argument and port lists.

Examples

from symbolica import S
from symbolica.community.tensor import TensorPattern, PortPattern, Representation, TensorName
D_, i_, j_, mu_, nu_, a_, b_, c_ = S("D_", "i_", "j_", "mu_", "nu_", "a_", "b_", "c_")
rest = S("ports___")
pattern = TensorPattern.vector("V_", ports=[rest])