Kinematics

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

Kinematics

class Kinematics

Scoped symbolic scalar products and two-to-two Mandelstam kinematics.

The immutable object uses Spenso’s dot products and metric shorthand. Apply it after contracting tensors with Idenso. Momentum inputs are unindexed names, and mass inputs are squared masses.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
P = hep.Kinematics.external_momentum()
p1, p2, p3, p4 = [P(i) for i in range(4)]
s, t, u = hep.Kinematics.s(), hep.Kinematics.t(), hep.Kinematics.u()
kin = hep.Kinematics.mandelstam([p1, p2, p3, p4], [E("0")]*4, [s, t, u])
assert kin.scalar_product(p1, p2) == s/2

Attributes

Name	Description
dimension	Lorentz dimension as a Symbolica integer or symbol.

dimension

Kinematics.dimension: Expression

Lorentz dimension as a Symbolica integer or symbol.

Examples

Using the setup in the Kinematics class example:

assert hep.Kinematics(S("D")).dimension == S("D")

Methods

Name	Description
__new__	Start with no scalar-product assumptions in the chosen dimension.
apply	Substitute scalar products without mutating global assumptions
external_momentum	External momentum family indexed by physical leg.
flux	Return the initial-state denominator for a cross section or decay rate
loop_momentum	Loop momentum family indexed by loop basis position.
mandelstam	Set the invariants for p1 + p2 -> p3 + p4
s	Mandelstam invariant s=(p1+p2)^2 for p1 + p2 -> p3 + p4.
scalar_product	Expand a bilinear scalar product and apply known assumptions
t	Mandelstam invariant t=(p1-p3)^2 for p1 + p2 -> p3 + p4.
three_body_phase_space	Return four-dimensional three-body phase space per two Dalitz invariants
two_body_phase_space	Return four-dimensional two-body phase space per unit solid angle
u	Mandelstam invariant u=(p1-p4)^2 for p1 + p2 -> p3 + p4.
with_scalar_product	Return a new context with one scalar product set.

__new__

Kinematics.__new__(
    dimension: typing.Optional[Expression] = None,
    *,
    momenta: typing.Optional[typing.Sequence[Expression]] = None,
) -> Kinematics

Related type: Expression

Start with no scalar-product assumptions in the chosen dimension.

Examples

Using the setup in the Kinematics class example:

kin = hep.Kinematics()
dimensional = hep.Kinematics(S("D"))

Parameters

• dimension (Expression | None) Integer or symbolic Lorentz dimension; defaults to four.
• momenta (list[Expression] | None) Momentum names used in linear combinations with scalar coefficients.

apply

Kinematics.apply(expression: TensorExpression) -> TensorExpression
Kinematics.apply(expression: Expression | int | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | ComplexFloat | Float | builtins.int | builtins.float | builtins.str | decimal.Decimal | builtins.complex | tuple[Float | builtins.int | builtins.float | builtins.str | decimal.Decimal, Float | builtins.int | builtins.float | builtins.str | decimal.Decimal]) -> Expression

Related types: TensorExpression, Expression, Float, ComplexFloat

Substitute scalar products without mutating global assumptions.

Accepts a scalar Expression or a tensor expression. Tensor results retain the ordered open slots, including when the result is zero.

Examples

Using the setup in the Kinematics class example:

p1, p2, p3, p4, s, t, u = S("p1", "p2", "p3", "p4", "s", "t", "u")
free = hep.Kinematics(momenta=[p1, p2, p3, p4])
kin = hep.Kinematics.mandelstam([p1, p2, p3, p4], [E("0")]*4, [s, t, u])
contracted_expression = free.scalar_product(p1, p2)
assert kin.apply(contracted_expression) == s/2

Parameters

• expression (Expression) Expression with compact scalar products.

external_momentum

Kinematics.external_momentum() -> Expression

Related type: Expression

External momentum family indexed by physical leg.

Examples

from symbolica.community import hepkit as hep
reference = hep.Kinematics.external_momentum()

flux

Kinematics.flux(first: Expression, second: typing.Optional[Expression] = None) -> Expression

Related type: Expression

Return the initial-state denominator for a cross section or decay rate.

Two momenta give 4*sqrt((p1.p2)**2-p1**2*p2**2). One momentum gives 2*sqrt(p**2) for a decay in its rest frame. Divide the squared matrix element times phase space by this value. Inputs must be physical, future-directed on-shell momenta. Symbolica retains square-root branches; declare positive invariants with S("s", is_positive=True) when known.

Examples

Using the setup in the Kinematics class example:

p1, p2, s = S("p1", "p2", "s")
kin = hep.Kinematics(momenta=[p1, p2])
kin = kin.with_scalar_product(p1, p1, E("0")).with_scalar_product(p2, p2, E("0"))
kin = kin.with_scalar_product(p1, p2, s/2)
flux = kin.flux(p1, p2)

Parameters

• first (Expression) Incoming unindexed momentum or declared linear combination.
• second (Expression | None) Other incoming momentum; None selects a rest-frame decay.

loop_momentum

Kinematics.loop_momentum() -> Expression

Related type: Expression

Loop momentum family indexed by loop basis position.

Examples

from symbolica.community import hepkit as hep
reference = hep.Kinematics.loop_momentum()

mandelstam

Kinematics.mandelstam(
    momenta: typing.Sequence[Expression],
    mass_squared: typing.Sequence[Expression],
    invariants: typing.Sequence[Expression],
) -> Kinematics

Related type: Expression

Set the invariants for p1 + p2 -> p3 + p4.

The convention is s=(p1+p2)^2, t=(p1-p3)^2, and u=(p1-p4)^2. These obey s+t+u=sum(mass_squared); use Symbolica substitution when you want to eliminate one invariant.

Examples

Using the setup in the Kinematics class example:

kin = hep.Kinematics.mandelstam([p1, p2, p3, p4], [E("0")]*4, [s, t, u])

Parameters

• momenta (list[Expression]) Four unindexed momenta, with the incoming pair first.
• mass_squared (list[Expression]) Four squared masses in the same order.
• invariants (list[Expression]) The three symbols or expressions s, t, u.

s

Kinematics.s() -> Expression

Related type: Expression

Mandelstam invariant s=(p1+p2)^2 for p1 + p2 -> p3 + p4.

Examples

from symbolica.community import hepkit as hep
s = hep.Kinematics.s()

scalar_product

Kinematics.scalar_product(left: Expression, right: Expression) -> Expression

Related type: Expression

Expand a bilinear scalar product and apply known assumptions.

For linear combinations, declare the momentum names in the constructor or by setting scalar products. Other symbols are scalar coefficients. Nonlinear momentum expressions raise KinematicsError.

Examples

Using the setup in the Kinematics class example:

assert kin.scalar_product(p1, p2) == s/2
assert kin.scalar_product(p1 + p2, p1 + p2) == s

Parameters

• left (Expression) First unindexed momentum or linear combination.
• right (Expression) Second unindexed momentum or linear combination.

t

Kinematics.t() -> Expression

Related type: Expression

Mandelstam invariant t=(p1-p3)^2 for p1 + p2 -> p3 + p4.

Examples

from symbolica.community import hepkit as hep
t = hep.Kinematics.t()

three_body_phase_space

Kinematics.three_body_phase_space(
    first: Expression,
    second: Expression,
    third: Expression,
) -> Expression

Related type: Expression

Return four-dimensional three-body phase space per two Dalitz invariants.

This is dPhi_3/(ds12*ds23) = 1/(128*pi**3*P**2), where P=first+second+third and sij=(pi+pj)**2. The overall spatial orientation is integrated. Use an orientation-independent or orientation-averaged squared amplitude and physical on-shell momenta. The measure includes (2*pi)**4*delta**4 and one d**3p/((2*pi)**3*2E) for each final particle.

Masses constrain the allowed Dalitz region; its boundaries are not imposed here. Flux, spin/color averages and identical-particle factors remain separate. Non-four-dimensional contexts are rejected.

Examples

Using the setup in the Kinematics class example:

k1, k2, k3 = S("k1", "k2", "k3")
kin = hep.Kinematics(momenta=[k1, k2, k3])
density = kin.three_body_phase_space(k1, k2, k3)

Parameters

• first, second, third (Expression) Final-state on-shell momenta. Their scalar products determine the total invariant mass squared through this kinematic context.

two_body_phase_space

Kinematics.two_body_phase_space(first: Expression, second: Expression) -> Expression

Related type: Expression

Return four-dimensional two-body phase space per unit solid angle.

This is dPhi_2/dOmega in the final pair’s rest frame, with (2*pi)**4*delta**4(P-p1-p2) and d**3p/((2*pi)**3*2E) for each final particle. Use physical on-shell momenta above threshold. Flux, spin/color averages and identical-particle factors are separate. For an angle-independent amplitude, integrating this measure gives 4*pi times the returned expression. Non-four-dimensional contexts are rejected.

Examples

Using the setup in the Kinematics class example:

p1, p2, p3, p4, s, t, u = S("p1", "p2", "p3", "p4", "s", "t", "u")
kin = hep.Kinematics.mandelstam([p1, p2, p3, p4], [E("0")]*4, [s, t, u])
density = kin.two_body_phase_space(p3, p4)

Parameters

• first (Expression) First outgoing unindexed momentum or declared linear combination.
• second (Expression) Second outgoing unindexed momentum or declared linear combination.

u

Kinematics.u() -> Expression

Related type: Expression

Mandelstam invariant u=(p1-p4)^2 for p1 + p2 -> p3 + p4.

Examples

from symbolica.community import hepkit as hep
u = hep.Kinematics.u()

with_scalar_product

Kinematics.with_scalar_product(left: Expression, right: Expression, value: Expression) -> Kinematics

Related type: Expression

Return a new context with one scalar product set.

Examples

Using the setup in the Kinematics class example:

p, m = S("p", "m")
kin = hep.Kinematics(momenta=[p]).with_scalar_product(p, p, m**2)
assert kin.scalar_product(p, p) == m**2

Parameters

• left (Expression) First unindexed momentum.
• right (Expression) Second unindexed momentum.
• value (Expression) Assumed scalar product.