TensorName

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

`TensorName`

class TensorName

A registered function name for symbolic tensors of arbitrary index spaces.

Call a name with scalar arguments followed by Slots or Representations to create a TensorExpression. The latter leave axes unresolved for later indexing. Use vector for a rank-one name that also supports compact dot notation. Predefined accessors identify standard tensors; use TensorExpression factories to construct their correctly ordered axes and TensorPattern for matching.

Examples

from symbolica.community.tensor import Representation, TensorName, TensorExpression
space = Representation.euc(3)
A = TensorName("A")(space, space)
A("i", "j").rank
2

Methods

Name	Description
`__call__`	Construct a tensor with scalar arguments and ordered axes.
`__new__`	Register a tensor function name.
`__repr__`	Return a readable object description for inspection.
`__str__`	Return a readable text representation.
`_repr_html_`
`_repr_latex_`
`charge_conjugation`	Return the registered name of the Dirac charge-conjugation matrix.
`color_f`	Return the registered name of the antisymmetric color structure constants f^{abc}.
`color_t`	Return the registered name of the fundamental color generators T^a.
`dirac_gamma`	Return the registered name of the Dirac gamma matrices for Clifford algebra.
`flat`	Return the registered name of the metric map for raising or lowering an index.
`g`	Return the registered name of the metric pairing.
`gamma0`	Return the registered name of the time-component Dirac matrix gamma^0.
`gamma5`	Return the registered name of the Dirac chirality matrix gamma^5.
`get_tags`	List the tags attached to the registered function.
`has_tag`	Check whether the registered function carries a tag.
`levi_civita`	Return the registered name of the totally antisymmetric Levi-Civita tensor.
`projm`	Return the registered name of the left-chiral Dirac projector (I - gamma^5)/2.
`projp`	Return the registered name of the right-chiral Dirac projector (I + gamma^5)/2.
`sigma`	Return the registered name of the antisymmetric Dirac sigma tensor.
`to_expression`	Return this function name as a Symbolica symbol.
`vector`	Register a tensor function with exactly one axis.

`call`

TensorName.__call__(*args: Slot | Representation | _ScalarInput) -> TensorExpression

Construct a tensor with scalar arguments and ordered axes.

Parameters

*args (scalar expression, Slot, or Representation) Scalar arguments first, then labeled Slots or unresolved Representations. A compact vector may bind an axis of a generic tensor, producing a contraction instead of a stored-data descriptor.

Returns

TensorExpression The tensor call, including a scalar tensor when there are no axes. Repeated compatible explicit labels are contracted.

Notes

For predefined metrics, Dirac matrices, and color tensors, prefer the corresponding TensorExpression factory. Fixed-structure names reject direct calls. Symmetries act on the full argument list; an antisymmetric name called twice with exactly the same representation argument is zero.

Examples

from symbolica import S
from symbolica.community.tensor import TensorName, Representation
space = Representation.euc(3)
tensor = TensorName("B")(S("x"), 7, space("i"), space)
tensor.rank
2

`new`

TensorName.__new__(
    name: builtins.str,
    *,
    rank: typing.Optional[builtins.int] = None,
    is_symmetric: typing.Optional[builtins.bool] = None,
    is_antisymmetric: typing.Optional[builtins.bool] = None,
    is_cyclesymmetric: typing.Optional[builtins.bool] = None,
    is_linear: typing.Optional[builtins.bool] = None,
    is_flat: typing.Optional[builtins.bool] = None,
    is_scalar: typing.Optional[builtins.bool] = None,
    is_real: typing.Optional[builtins.bool] = None,
    is_integer: typing.Optional[builtins.bool] = None,
    is_positive: typing.Optional[builtins.bool] = None,
    tags: typing.Optional[typing.Sequence[builtins.str]] = None,
    aliases: typing.Optional[typing.Sequence[builtins.str]] = None,
    normalization: typing.Optional[symbolica.core.Transformer | typing.Callable[[symbolica.core.Expression], symbolica.core.Expression]] = None,
    print: typing.Optional[dict[str, str] | typing.Callable[..., str | None]] = None,
    derivative: typing.Optional[typing.Any] = None,
    series: typing.Optional[typing.Any] = None,
    eval: typing.Optional[typing.Any] = None,
    data: typing.Optional[_ScalarInput | str | dict | list | bytes] = None,
) -> TensorName

Parameters

name (str) Symbolica function name. Passing only a previously registered name reuses its attributes and printers.
rank (int, optional) None permits arbitrary rank. Only rank=1 is supported as a fixed rank; it requires exactly one structural axis in each call.
is_symmetric, is_antisymmetric, is_cyclesymmetric (bool, optional) Symmetry of the function arguments under all permutations, signed permutations, or cyclic rotations. These affect scalar arguments as well as index arguments. Repeated arguments in an antisymmetric call make that call zero.
is_linear (bool, optional) Distribute the function over sums in its arguments.
is_flat (bool, optional) Flatten nested calls with the same head.
is_scalar (bool, optional) Declare calls scalar for Symbolica’s algebra. Do not use True for a tensor head with free indices.
is_real, is_integer, is_positive (bool, optional) Assumptions used by Symbolica for the registered symbol.
tags (sequence of str, optional) Additional Symbolica tags; Spenso’s required tags are included automatically.
aliases (sequence of str, optional) Additional names for the same Symbolica symbol.
normalization (Transformer or callable, optional) Normalize a newly constructed call. A callable receives an Expression and returns its normalized Expression; tensor interfaces must remain valid.
print (dict of str to str or callable, optional) A mapping with keys “plain”, “latex”, or “typst” changes just the displayed tensor name. Values are source without math delimiters, for example {“typst”: “macron(J)”}. Spenso adds arguments and indices. A callable uses Symbolica’s print callback convention and replaces the complete display; returning None selects the standard display.
derivative, series, eval (callable, optional) Symbolica callbacks for differentiation, series expansion, and numerical evaluation. Their arguments and results follow symbolica.S.
data (object, optional) Symbolica user data attached to the symbol, such as a dict, list, or bytes.

Returns

TensorName A callable name for constructing symbolic tensors.

Examples

from symbolica.community.tensor import TensorName, Representation
J = TensorName("Jbar", print={"typst": "macron(J)"})
vector = J(Representation.euc(3))
vector.rank
1

`repr`

TensorName.__repr__() -> builtins.str

Return a readable object description for inspection.

Examples

from symbolica.community import tensor as sp
name = sp.TensorName("docs::A")
text = repr(name)

`str`

TensorName.__str__() -> builtins.str

Return a readable text representation.

Examples

from symbolica.community import tensor as sp
name = sp.TensorName("docs::A")
text = str(name)

`_repr_html_`

TensorName._repr_html_() -> typing.Optional[builtins.str]

`_repr_latex_`

TensorName._repr_latex_() -> builtins.str

`charge_conjugation`

TensorName.charge_conjugation() -> TensorName

Return the registered name of the Dirac charge-conjugation matrix.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.charge_conjugation to construct a tensor with distinct unresolved axes, or TensorPattern.charge_conjugation to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.charge_conjugation().to_expression()

`color_f`

TensorName.color_f() -> TensorName

Return the registered name of the antisymmetric color structure constants f^{abc}.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.color_f to construct a tensor with distinct unresolved axes, or TensorPattern.color_f to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.color_f().to_expression()

`color_t`

TensorName.color_t() -> TensorName

Return the registered name of the fundamental color generators T^a.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.color_t to construct a tensor with distinct unresolved axes, or TensorPattern.color_t to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.color_t().to_expression()

`dirac_gamma`

TensorName.dirac_gamma() -> TensorName

Return the registered name of the Dirac gamma matrices for Clifford algebra.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.dirac_gamma to construct a tensor with distinct unresolved axes, or TensorPattern.dirac_gamma to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.dirac_gamma().to_expression()

`flat`

TensorName.flat() -> TensorName

Return the registered name of the metric map for raising or lowering an index.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.flat to construct a tensor with distinct unresolved axes, or TensorPattern.flat to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.flat().to_expression()

`g`

TensorName.g() -> TensorName

Return the registered name of the metric pairing.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.g to construct a tensor with distinct unresolved axes, or TensorPattern.g to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.g().to_expression()

`gamma0`

TensorName.gamma0() -> TensorName

Return the registered name of the time-component Dirac matrix gamma^0.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.gamma0 to construct a tensor with distinct unresolved axes, or TensorPattern.gamma0 to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.gamma0().to_expression()

`gamma5`

TensorName.gamma5() -> TensorName

Return the registered name of the Dirac chirality matrix gamma^5.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.gamma5 to construct a tensor with distinct unresolved axes, or TensorPattern.gamma5 to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.gamma5().to_expression()

`get_tags`

TensorName.get_tags() -> builtins.list[builtins.str]

List the tags attached to the registered function.

Returns

list of str Fully qualified tags, including the tags required by Spenso.

Examples

from symbolica.community.tensor import TensorName
name = TensorName("tagged_TensorName", tags=["example::example"])
"example::example" in name.get_tags()
True

`has_tag`

TensorName.has_tag(tag: builtins.str) -> builtins.bool

Check whether the registered function carries a tag.

Parameters

tag (str) Exact tag name. An unqualified name also matches its “python::” form.

Returns

bool Whether the tag is present.

Examples

from symbolica.community.tensor import TensorName
name = TensorName("tagged_TensorName", tags=["example::example"])
name.has_tag("example::example")
True

`levi_civita`

TensorName.levi_civita() -> TensorName

Return the registered name of the totally antisymmetric Levi-Civita tensor.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.levi_civita to construct a tensor with distinct unresolved axes, or TensorPattern.levi_civita to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.levi_civita().to_expression()

`projm`

TensorName.projm() -> TensorName

Return the registered name of the left-chiral Dirac projector (I - gamma^5)/2.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.projm to construct a tensor with distinct unresolved axes, or TensorPattern.projm to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.projm().to_expression()

`projp`

TensorName.projp() -> TensorName

Return the registered name of the right-chiral Dirac projector (I + gamma^5)/2.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.projp to construct a tensor with distinct unresolved axes, or TensorPattern.projp to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.projp().to_expression()

`sigma`

TensorName.sigma() -> TensorName

Return the registered name of the antisymmetric Dirac sigma tensor.

Returns

TensorName The existing symbolic function head, including its tags and symmetries.

Notes

Use TensorExpression.sigma to construct a tensor with distinct unresolved axes, or TensorPattern.sigma to construct a rewrite pattern. The Python accessor name does not change the underlying Symbolica symbol.

Examples

from symbolica.community.tensor import TensorName
head = TensorName.sigma().to_expression()

`to_expression`

TensorName.to_expression() -> Expression

Return this function name as a Symbolica symbol.

Examples

from symbolica.community import tensor as sp
name = sp.TensorName("docs::A")
symbolic_head = name.to_expression()

Returns

Expression The bare function head, without arguments or tensor structure.

Examples

from symbolica.community.tensor import TensorName
name = TensorName("tagged_TensorName", tags=["example::example"])
head = name.to_expression()

`vector`

TensorName.vector(
    name: builtins.str,
    *,
    is_symmetric: typing.Optional[builtins.bool] = None,
    is_antisymmetric: typing.Optional[builtins.bool] = None,
    is_cyclesymmetric: typing.Optional[builtins.bool] = None,
    is_linear: typing.Optional[builtins.bool] = None,
    is_flat: typing.Optional[builtins.bool] = None,
    is_scalar: typing.Optional[builtins.bool] = None,
    is_real: typing.Optional[builtins.bool] = None,
    is_integer: typing.Optional[builtins.bool] = None,
    is_positive: typing.Optional[builtins.bool] = None,
    tags: typing.Optional[typing.Sequence[builtins.str]] = None,
    aliases: typing.Optional[typing.Sequence[builtins.str]] = None,
    normalization: typing.Optional[symbolica.core.Transformer | typing.Callable[[symbolica.core.Expression], symbolica.core.Expression]] = None,
    print: typing.Optional[dict[str, str] | typing.Callable[..., str | None]] = None,
    derivative: typing.Optional[typing.Any] = None,
    series: typing.Optional[typing.Any] = None,
    eval: typing.Optional[typing.Any] = None,
    data: typing.Optional[_ScalarInput | str | dict | list | bytes] = None,
) -> TensorName

Parameters

name (str) Symbolica function name. Passing only a previously registered name reuses its attributes and printers.
is_symmetric, is_antisymmetric, is_cyclesymmetric (bool, optional) Symmetry of the function arguments under all permutations, signed permutations, or cyclic rotations. These affect scalar arguments as well as index arguments. Repeated arguments in an antisymmetric call make that call zero.
is_linear (bool, optional) Distribute the function over sums in its arguments.
is_flat (bool, optional) Flatten nested calls with the same head.
is_scalar (bool, optional) Declare calls scalar for Symbolica’s algebra. Do not use True for a tensor head with free indices.
is_real, is_integer, is_positive (bool, optional) Assumptions used by Symbolica for the registered symbol.
tags (sequence of str, optional) Additional Symbolica tags; Spenso’s required tags are included automatically.
aliases (sequence of str, optional) Additional names for the same Symbolica symbol.
normalization (Transformer or callable, optional) Normalize a newly constructed call. A callable receives an Expression and returns its normalized Expression; tensor interfaces must remain valid.
print (dict of str to str or callable, optional) A mapping with keys “plain”, “latex”, or “typst” changes just the displayed tensor name. Values are source without math delimiters, for example {“typst”: “macron(J)”}. Spenso adds arguments and indices. A callable uses Symbolica’s print callback convention and replaces the complete display; returning None selects the standard display.
derivative, series, eval (callable, optional) Symbolica callbacks for differentiation, series expansion, and numerical evaluation. Their arguments and results follow symbolica.S.
data (object, optional) Symbolica user data attached to the symbol, such as a dict, list, or bytes.

Returns

TensorName A callable name for constructing symbolic tensors.

Examples

from symbolica.community.tensor import TensorName, Representation
J = TensorName.vector("Jbar_vector", print={"typst": "macron(J)"})
vector = J(Representation.euc(3))
vector.rank
1