Particle

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

`Particle`

class Particle

A particle species in a loaded interaction model.

Particle records expose the signed PDG code, spin and color representations, electric charge, and the parameters used for mass and width.

Examples

from symbolica import S, E
from symbolica.community import hepkit as hep
model = hep.Model.standard_model()
electron = model.particle_by_pdg(11)
assert electron.name == "e-"

Attributes

Name	Description
`antiname`	Return the name of the corresponding antiparticle.
`antiparticle`	Return the corresponding antiparticle from the same model
`antitypstname`	Native Typst math label of the antiparticle, without dollar delimiters.
`charge`	Electric charge in units of e, as an exact Symbolica expression.
`color`	Return the signed UFO SU(3) color representation code.
`electric_charge`	Signed symbolic electric charge Q e, including the model’s coupling
`is_antiparticle`	Report whether this object represents an antiparticle.
`is_fermion`	Report whether the particle has fermionic spin.
`is_massless`	Report whether the particle’s mass parameter is zero.
`is_self_antiparticle`	Report whether the particle is its own antiparticle.
`mass`	Exact symbolic mass, with the UFO ZERO parameter represented as zero
`mass_parameter`	Return the name of the particle’s mass parameter.
`name`	Return the particle name used by the model.
`pdg_code`	Return the signed Particle Data Group code.
`spin`	Return the UFO spin code `2S + 1` (negative for ghost fields).
`typstname`	Native Typst math label, without dollar delimiters.
`weak_isospin`	Third weak-isospin component Q - Y/2; left-handed for fermions
`weak_isospin_right`	Right-handed fermion third weak-isospin component, if specified.
`width_parameter`	Return the name of the particle’s width parameter.
`y_charge`	Hypercharge in Q = T3 + Y/2; left-handed for fermions
`y_charge_right`	Right-handed fermion hypercharge in Q = T3 + Y/2, if specified.

`antiname`

Particle.antiname: builtins.str

Return the name of the corresponding antiparticle.

Examples

Using the setup in the Particle class example:

assert electron.antiname == "e+"

`antiparticle`

Particle.antiparticle: Particle

Return the corresponding antiparticle from the same model.

Self-conjugate particles map to themselves.

Examples

Using the setup in the Particle class example:

electron = model.particle_by_pdg(11)
electron.antiparticle.name
'e+'
model.particle_by_pdg(22).antiparticle.name  # the photon is self-conjugate
'a'

`antitypstname`

Particle.antitypstname: typing.Optional[builtins.str]

Native Typst math label of the antiparticle, without dollar delimiters.

Examples

from symbolica.community import hepkit as hep
hep.Model.qcd().particle("u").antitypstname
'overline(u)'

`charge`

Particle.charge: Expression

Electric charge in units of e, as an exact Symbolica expression.

Examples

Using the setup in the Particle class example:

model.particle("c").charge

`color`

Particle.color: builtins.int

Return the signed UFO SU(3) color representation code.

Examples

Using the setup in the Particle class example:

model.particle_by_pdg(11).color  # color-singlet electron
1

`electric_charge`

Particle.electric_charge: Expression

Signed symbolic electric charge Q e, including the model’s coupling. An electron has charge -e and a positron +e. Neutral particles return exact zero. Use charge for the dimensionless charge Q. The unit charge is inferred from minimal photon (PDG 22) interactions with fermions or scalars, including their Lorentz normalization; no parameter name is assumed. Use -electron.electric_charge for positive e.

Examples

from symbolica.community import hepkit as hep
qed_model = hep.Model.qed()
electron = qed_model.particle("e-")
mass, charge = electron.mass, electron.electric_charge
assert electron.antiparticle.electric_charge == -charge
assert qed_model.particle("a").electric_charge == 0

Raises

ModelError: If a charged particle’s model has no supported minimal photon vertex, or its photon vertices imply inconsistent unit charges.

`is_antiparticle`

Particle.is_antiparticle: builtins.bool

Report whether this object represents an antiparticle.

Examples

Using the setup in the Particle class example:

model.particle_by_pdg(11).is_antiparticle
False

`is_fermion`

Particle.is_fermion: builtins.bool

Report whether the particle has fermionic spin.

Examples

Using the setup in the Particle class example:

model.particle_by_pdg(11).is_fermion
True

`is_massless`

Particle.is_massless: builtins.bool

Report whether the particle’s mass parameter is zero.

Examples

Using the setup in the Particle class example:

model.particle_by_pdg(22).is_massless
True

`is_self_antiparticle`

Particle.is_self_antiparticle: builtins.bool

Report whether the particle is its own antiparticle.

Examples

Using the setup in the Particle class example:

model.particle_by_pdg(22).is_self_antiparticle
True

`mass`

Particle.mass: Expression

Exact symbolic mass, with the UFO ZERO parameter represented as zero. Other parameters remain symbolic, even when their current value is zero.

Examples

Using the setup in the Particle class example:

model.particle("c").mass

`mass_parameter`

Particle.mass_parameter: builtins.str

Return the name of the particle’s mass parameter.

Examples

Using the setup in the Particle class example:

particle = model.particle_by_pdg(13)
mass = model.parameter(particle.mass_parameter)

`name`

Particle.name: builtins.str

Return the particle name used by the model.

Examples

Using the setup in the Particle class example:

assert electron.name == "e-"

`pdg_code`

Particle.pdg_code: builtins.int

Return the signed Particle Data Group code.

Examples

Using the setup in the Particle class example:

model.particle("e-").pdg_code
11

`spin`

Particle.spin: builtins.int

Return the UFO spin code 2S + 1 (negative for ghost fields).

Examples

Using the setup in the Particle class example:

model.particle_by_pdg(11).spin  # spin-1/2 electron
2

`typstname`

Particle.typstname: typing.Optional[builtins.str]

Native Typst math label, without dollar delimiters.

Examples

from symbolica.community import hepkit as hep
hep.Model.qcd().particle("g").typstname
'g'

`weak_isospin`

Particle.weak_isospin: typing.Optional[Expression]

Third weak-isospin component Q - Y/2; left-handed for fermions. Antiparticle chiralities are exchanged by charge conjugation.

Examples

Using the setup in the Particle class example:

model.particle("c").weak_isospin

`weak_isospin_right`

Particle.weak_isospin_right: typing.Optional[Expression]

Right-handed fermion third weak-isospin component, if specified.

Examples

Using the setup in the Particle class example:

model.particle("c").weak_isospin_right

`width_parameter`

Particle.width_parameter: builtins.str

Return the name of the particle’s width parameter.

Examples

Using the setup in the Particle class example:

particle = model.particle_by_pdg(23)
width = model.parameter(particle.width_parameter)

`y_charge`

Particle.y_charge: typing.Optional[Expression]

Hypercharge in Q = T3 + Y/2; left-handed for fermions. None means absent, undefined, or unspecified, rather than zero.

Examples

Using the setup in the Particle class example:

model.particle("c").y_charge

`y_charge_right`

Particle.y_charge_right: typing.Optional[Expression]

Right-handed fermion hypercharge in Q = T3 + Y/2, if specified.

Examples

Using the setup in the Particle class example:

model.particle("c").y_charge_right

Methods

Name	Description
`__repr__`	Summarize the defining data as well as the name and PDG code.
`_repr_html_`	Display the model member’s physical data and defining expressions.
`_repr_pretty_`	Write the complete text summary to an IPython pretty printer.
`color_sum`	Construct the identity on this particle’s color space
`spin_sum`	Construct this particle’s external-state spin or polarization sum
`sum_spins`	Sum paired generated external wavefunctions for one edge

`repr`

Particle.__repr__() -> builtins.str

Summarize the defining data as well as the name and PDG code.

Examples

Using the setup in the Particle class example:

print(model.particle_by_pdg(11))

`_repr_html_`

Particle._repr_html_() -> builtins.str

Display the model member’s physical data and defining expressions.

Examples

Using the setup in the Particle class example:

from IPython.display import display
display(electron)

`_repr_pretty_`

Particle._repr_pretty_(pretty: typing.Any, cycle: builtins.bool) -> None

Write the complete text summary to an IPython pretty printer.

Examples

Using the setup in the Particle class example:

from IPython.lib.pretty import pretty
text = pretty(electron)

Parameters

pretty (object) IPython pretty printer receiving the text.
cycle (bool) Whether the object occurs recursively in the current display.

`color_sum`

Particle.color_sum(
    left: Expression,
    right: Expression,
    *,
    average: builtins.bool = False,
) -> Expression

Construct the identity on this particle’s color space.

The bare left index carries the particle representation; right carries its dual. Antiquarks and antisextets reverse the dual orientation. Supports UFO singlet, fundamental, sextet and adjoint representations. average=True divides by the number of color states (1, 3, 6 or 8). This sums color only; spin sums and color-algebra simplification remain separate operations. To close an existing tensor, use indices whose slots are dual to the open color slots of that tensor.

Examples

Using the setup in the Particle class example:

from symbolica import S
i, j = S("i", "j")
color_projector = model.particle_by_pdg(5).color_sum(i, j, average=True)
model.particle_by_pdg(11).color_sum(i, j) == 1
True

Parameters

left (Expression) Bare index in the particle’s color representation.
right (Expression) Bare index in its dual representation.
average (bool, optional) Divide by the number of color states. Defaults to False.

Returns

Expression Spenso color identity, or one for a color singlet.

Raises

ValueError: If the particle’s UFO color representation is unsupported.

`spin_sum`

Particle.spin_sum(
    momentum: Expression,
    left: Expression,
    right: Expression,
    *,
    average: builtins.bool = False,
    reference: typing.Optional[Expression] = None,
    covariant: builtins.bool = False,
    spin_vector: typing.Optional[Expression] = None,
    dimension: typing.Optional[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]] = None,
) -> Expression

Construct this particle’s external-state spin or polarization sum.

Return an ordinary Symbolica expression using Spenso gamma matrices and metrics. Indices are bare symbols; momentum and reference are unindexed symbols or labeled calls such as Q(1). The calculation defaults to four-dimensional external states. dimension changes the Lorentz dimension while Dirac spinor slots retain dimension four. Massive vectors use the Proca projector. For massless vectors, supply a reference for a physical axial sum, or omit it for the covariant sum of a gauge-invariant amplitude. Subsequent kinematic substitutions must enforce on-shell conditions and a nonzero momentum-reference scalar product.

For a massive Dirac particle, spin_vector selects one physical spin state instead of summing states. Supply a dimensionless unindexed vector satisfying p.s = 0 and s.s = -1: the rest-frame spin direction, boosted with the particle. The same projector sign applies to fermions and antifermions; do not reverse this vector for an antiparticle. This option requires average=False and four Lorentz dimensions.

Examples

Using the setup in the Particle class example:

from symbolica import S
p, i, j = S("p", "i", "j")
projector = model.particle("e-").spin_sum(p, i, j, average=True)
polarized = model.particle("ta-").spin_sum(p, i, j, spin_vector=S("s"))
dimensional = model.particle("g").spin_sum(p, i, j, dimension=S("D"))
six_dimensional = model.particle("g").spin_sum(p, i, j, dimension=6)

Parameters

momentum (Expression) Unindexed external momentum.
left (Expression) Open index on the amplitude.
right (Expression) Open index on the conjugate amplitude.
average (bool) Divide by two for Dirac fermions, D-2 for massless vectors, or D-1 for massive vectors. Scalars have one state.
dimension (Expression | int | None) Integer or symbolic Lorentz dimension; defaults to four. Dirac spinor slots and their trace dimension stay four. To use a fixed two-state vector average at symbolic D, leave average=False and divide the result by two.
reference (Expression | None) Axial reference momentum for a massless vector; need not be null.
covariant (bool) Use the Feynman-gauge vector numerator even for a massive vector.
spin_vector (Expression | None) Physical spin vector of a massive Dirac state, with p.s = 0 and s.s = -1. Requires average=False; None sums both states.

Raises

ValueError: If spin_vector is used with averaging, a massless particle, or a particle other than a Dirac fermion, non-four-dimensional Lorentz slots, or is not an unindexed name. Also raised for an invalid dimension or a concrete dimension with no physical vector states.

`sum_spins`

Particle.sum_spins(
    expression: Expression,
    momentum: Expression,
    *,
    edge: builtins.int,
    average: builtins.bool = False,
    reference: typing.Optional[Expression] = None,
    covariant: builtins.bool = False,
    spin_vector: typing.Optional[Expression] = None,
    dimension: typing.Optional[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]] = None,
) -> Expression

Sum paired generated external wavefunctions for one edge.

Replace this particle’s wavefunction and its adjoint using the same completeness relation as spin_sum. The expression may be a sewn diagram’s projector_expression() or a squared amplitude. Only pairs with the supplied edge label are replaced; unpaired wavefunctions stay unchanged. Scalar particles have no external wavefunction factors. Vector wavefunction slots must use the requested Lorentz dimension. External states default to four dimensions; reference and gauge conventions are those of spin_sum. For a massive Dirac particle, spin_vector selects the same physical spin state as in spin_sum, including for antiparticles. This does not sum color, conjugate amplitudes, or apply graph symmetry factors.

Examples

Using the setup in the Particle class example:

from symbolica import S, E
from symbolica.community import hepkit as hep
model = hep.Model.standard_model()
diagram = model.process(["e-", "e+"], ["mu-", "mu+"]).generate_diagrams().diagrams[0]
electron = model.particle("e-")
projector = diagram.projector_expression()
spin_summed = electron.sum_spins(projector, S("gammalooprs::P")(1), edge=1)

Parameters

expression (Expression) Projector or squared expression containing paired wavefunctions.
momentum (Expression) Unindexed external momentum in the physical particle direction.
edge (int) Generated edge label of the pair to replace.
average (bool) Divide by two for Dirac fermions, D-2 for massless vectors, or D-1 for massive vectors. Scalars have one state.
dimension (Expression | int | None) Integer or symbolic Lorentz dimension; defaults to four. Dirac spinor slots and their trace dimension stay four. To use a fixed two-state vector average at symbolic D, leave average=False and divide the result by two.
reference (Expression | None) Axial reference for a massless vector; need not be null.
covariant (bool) Use the Feynman-gauge vector numerator even for a massive vector.
spin_vector (Expression | None) Physical spin vector of a massive Dirac state, with p.s = 0 and s.s = -1. Requires average=False; None sums both states.

Raises

ValueError: If spin_vector is used with averaging, a massless particle, or a particle other than a Dirac fermion, non-four-dimensional Lorentz slots, or is not an unindexed name. Also raised for an invalid dimension or a concrete dimension with no physical vector states.