TensorRule

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

TensorRule

class TensorRule

A reusable replacement rule that preserves tensor interfaces.

Use with TensorExpression.replace. A replacement must preserve the matched tensor’s external indices, including their representations. Literal replacements are checked where possible at construction; wildcard-dependent replacements are checked when matched.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import TensorRule
indexed = A("i", "j")
rule = TensorRule(indexed, 2 * indexed)
indexed.replace(rule).rank
2

Methods

Name Description
__new__ Construct a checked whole-tensor replacement rule.
__repr__ Return a readable object description for inspection.

__new__

TensorRule.__new__(
    pattern: TensorExpression | _ScalarInput | HeldExpression,
    rhs: TensorExpression | _ScalarInput | HeldExpression | typing.Callable[[dict[Expression, Expression]], TensorExpression | _ScalarInput],
    *,
    cond: typing.Optional[PatternRestriction | Condition] = None,
    rhs_cache_size: builtins.int = 100,
) -> TensorRule

Related types: TensorExpression, HeldExpression, Expression, PatternRestriction, Condition

Construct a checked whole-tensor replacement rule.

Parameters

  • pattern (TensorExpression, scalar expression, or HeldExpression) Tensor to match. TensorPattern can describe wildcard tensor syntax.
  • rhs (TensorExpression, scalar expression, HeldExpression, or callable) Replacement with the same external interface. A callable receives a dict from wildcard Expressions to matched Expressions and returns the replacement. Zero retains the matched tensor’s interface.
  • cond (PatternRestriction or Condition, optional) Condition evaluated for each candidate match.
  • rhs_cache_size (int, default 100) Maximum number of cached replacement results per application. Use zero for a callback whose side effects must run at every match.

Returns

  • TensorRule Reusable replacement, without applying it yet.

Notes

Right-hand-side wildcards must be bound by the pattern. Index multiplicity and external representations must remain valid after substitution.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(2)
A = TensorName("M")(space, space)
from symbolica.community.tensor import TensorRule
indexed = A("i", "j")
rule = TensorRule(indexed, 2 * indexed)
result = indexed.replace(rule)

__repr__

TensorRule.__repr__() -> builtins.str

Return a readable object description for inspection.

Examples

from symbolica.community import tensor as sp
r = sp.Representation.euc(2)
A = sp.TensorName("docs::A")(r, r)
rule = sp.TensorRule(A("i", "j"), 2 * A("i", "j"))
text = repr(rule)