Model

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

Model

class Model

A loaded particle model ready for diagram generation.

Models provide typed access to particles, parameters, couplings, interaction rules, propagators, and numerical parameter-card updates.

Examples

Built-in models need no external files. To import your own UFO directory, see UfoLoader; to restore a normalized JSON model, use Model(path) or Model.from_json.

from symbolica import S, E
from symbolica.community import hepkit as hep
model = hep.Model.standard_model()
photon = model.particle("a")
process = model.process(["e-", "e+"], ["mu-", "mu+"])
result = process.generate_diagrams()
assert result.report.completed
scalar_model = hep.Model.phi4()
assert scalar_model.particle("phi").spin == 1

Parameters

• path (str or os.PathLike) Path to a normalized HEP JSON model.

Attributes

Name	Description
couplings	Return all interaction couplings in model order.
form_factors	Return all momentum-dependent model form factors in model order.
functions	Return all helper functions available to model expressions.
lorentz_structures	Return all reusable Lorentz structures in model order.
name	Return the model name.
parameters	Return all external and internal parameters in model order.
particles	Return all particle species in deterministic model order.
propagators	Return all model-defined propagators in model order.
restriction	Return the applied restriction name, when present.
vertex_rules	Return all interaction vertex rules in model order.

couplings

Model.couplings: builtins.list[Coupling]

Return all interaction couplings in model order.

Examples

Using the setup in the Model class example:

qed = [c for c in model.couplings if c.orders.get("QED", 0) > 0]

form_factors

Model.form_factors: builtins.list[FormFactor]

Return all momentum-dependent model form factors in model order.

Examples

Using the setup in the Model class example:

form_factors = {factor.name: factor for factor in model.form_factors}

functions

Model.functions: builtins.list[ModelFunction]

Return all helper functions available to model expressions.

Examples

Using the setup in the Model class example:

functions = {function.name: function for function in model.functions}

lorentz_structures

Model.lorentz_structures: builtins.list[LorentzStructure]

Return all reusable Lorentz structures in model order.

Examples

Using the setup in the Model class example:

lorentz_by_name = {item.name: item for item in model.lorentz_structures}

name

Model.name: builtins.str

Return the model name.

Examples

Using the setup in the Model class example:

model = hep.Model.standard_model()
model_name = model.name

parameters

Model.parameters: builtins.list[Parameter]

Return all external and internal parameters in model order.

Examples

Using the setup in the Model class example:

external = [p for p in model.parameters if p.nature == hep.ParameterNature.EXTERNAL]

particles

Model.particles: builtins.list[Particle]

Return all particle species in deterministic model order.

Examples

Using the setup in the Model class example:

fermions = [particle for particle in model.particles if particle.spin == 2]

propagators

Model.propagators: builtins.list[Propagator]

Return all model-defined propagators in model order.

Examples

Using the setup in the Model class example:

propagators_by_name = {item.name: item for item in model.propagators}

restriction

Model.restriction: typing.Optional[builtins.str]

Return the applied restriction name, when present.

Examples

Using the setup in the Model class example:

model = hep.Model.standard_model()
restriction = model.restriction

vertex_rules

Model.vertex_rules: builtins.list[VertexRule]

Return all interaction vertex rules in model order.

Examples

Using the setup in the Model class example:

electron_vertices = [v for v in model.vertex_rules if "e-" in v.particles]

Methods

Name	Description
__new__	Load a model from a normalized HEP JSON file.
__repr__	Summarize the defining data as well as the name and particle count.
_repr_html_	Render a compact inventory of the model in notebook frontends.
_repr_pretty_	Write the concise model summary to an IPython pretty printer.
coupling	Look up a coupling by name.
default_parameter_card	Build a parameter card from the model’s current external values.
electroweak	Load the electroweak Standard Model, retaining quarks, Higgs, Goldstones, and electroweak ghosts, and removing gluons and gluon ghosts.
expand_couplings	Replace named UFO coefficients by their analytic model expressions
form_factor	Look up a form factor by name.
from_json	Parse a model from its JSON representation.
function	Look up a model function by name.
lorentz_structure	Look up a Lorentz structure by name.
parameter	Look up a parameter by name.
particle	Look up a particle by name.
particle_by_pdg	Look up a particle by PDG code.
phi3	Load a real scalar phi with L_int = -g phi^3 / 3!
phi4	Load a real scalar phi with L_int = -lam phi^4 / 4!
phi_3_4	Load a real scalar phi with L_int = -g phi^3 / 3! - lam phi^4 / 4!
process	Define a process with model-validated external states and sector restrictions
propagator	Look up a propagator by name.
qcd	Load QCD with six quark flavors, gluons, and gluon ghosts, filtered from the Standard Model
qcd_qed	Load strong and electromagnetic interactions of all quarks and charged leptons, including gluon ghosts, with Standard Model parameters.
qed	Load QED with photons and all charged fermions (including quarks), filtered from the Standard Model
recompute_with	Return a copy with all dependent values recomputed by a callback.
scalar_qed	Load scalar QED in Feynman gauge with a, phi+, and phi-
standard_model	Load the complete embedded Standard Model with default parameters
to_json	Serialize the model as JSON.
vertex_rule	Look up a vertex rule by name.
with_parameter_card	Return a copy with a parameter card applied atomically.
write_json	Write the model to a JSON file.
yang_mills	Load pure SU(3) Yang-Mills theory: gluons and gluon ghosts without quarks.

__new__

Model.__new__(path: builtins.str | os.PathLike | pathlib.Path) -> Model

Load a model from a normalized HEP JSON file.

Examples

Using the setup in the Model class example:

from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory() as directory:
    path = Path(directory) / "model.json"
    model.write_json(path)
    restored = hep.Model(path)
    assert restored.name == model.name

Parameters

• path (str or os.PathLike) Path to the JSON model.

__repr__

Model.__repr__() -> builtins.str

Summarize the defining data as well as the name and particle count.

Examples

Using the setup in the Model class example:

print(model)

_repr_html_

Model._repr_html_() -> builtins.str

Render a compact inventory of the model in notebook frontends.

Examples

Using the setup in the Model class example:

from IPython.display import display
display(model)

_repr_pretty_

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

Write the concise model summary to an IPython pretty printer.

Examples

Using the setup in the Model class example:

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

Parameters

• pretty (object) The IPython pretty-printer object.
• cycle (bool) Whether this object is part of a recursive formatting cycle.

coupling

Model.coupling(name: builtins.str) -> Coupling

Related type: Coupling

Look up a coupling by name.

Examples

Using the setup in the Model class example:

coupling = model.coupling("GC_1")

Parameters

• name (str) Coupling name.

default_parameter_card

Model.default_parameter_card() -> ParameterCard

Related type: ParameterCard

Build a parameter card from the model’s current external values.

Examples

Using the setup in the Model class example:

card = model.default_parameter_card()

electroweak

Model.electroweak() -> Model

Load the electroweak Standard Model, retaining quarks, Higgs, Goldstones, and electroweak ghosts, and removing gluons and gluon ghosts.

Examples

Using the setup in the Model class example:

model = hep.Model.electroweak()

expand_couplings

Model.expand_couplings(expression: TensorExpression) -> TensorExpression
Model.expand_couplings(expression: Expression) -> Expression

Related types: TensorExpression, Expression

Replace named UFO coefficients by their analytic model expressions.

The input and the stored model are unchanged.

Examples

Using the setup in the Model class example:

analytic = model.expand_couplings(S("UFO::GC_11"))

Parameters

• expression (Expression) Symbolica expression containing named couplings from this model.

form_factor

Model.form_factor(name: builtins.str) -> FormFactor

Related type: FormFactor

Look up a form factor by name.

Examples

Using model from the class example. A model may have no form factors:

form_factors = [model.form_factor(item.name) for item in model.form_factors]

Parameters

• name (str) Form-factor name.

from_json

Model.from_json(json: builtins.str) -> Model

Parse a model from its JSON representation.

Examples

Using the setup in the Model class example:

model_json = model.to_json()
restored = hep.Model.from_json(model_json)
assert restored.name == model.name

Parameters

• json (str) Serialized model object.

function

Model.function(name: builtins.str) -> ModelFunction

Related type: ModelFunction

Look up a model function by name.

Examples

Using model from the class example. A model may have no helper functions:

functions = [model.function(item.name) for item in model.functions]

Parameters

• name (str) Function name.

lorentz_structure

Model.lorentz_structure(name: builtins.str) -> LorentzStructure

Related type: LorentzStructure

Look up a Lorentz structure by name.

Examples

Using the setup in the Model class example:

lorentz = model.lorentz_structure("FFV1")

Parameters

• name (str) Lorentz-structure name.

parameter

Model.parameter(name: builtins.str) -> Parameter

Related type: Parameter

Look up a parameter by name.

Examples

Using the setup in the Model class example:

mass = model.parameter("MM")
assert mass.nature == hep.ParameterNature.EXTERNAL

Parameters

• name (str) Parameter name.

particle

Model.particle(name: builtins.str) -> Particle

Related type: Particle

Look up a particle by name.

Examples

Using the setup in the Model class example:

electron = model.particle("e-")
assert electron.pdg_code == 11

Parameters

• name (str) Particle name or antiname.

particle_by_pdg

Model.particle_by_pdg(pdg: builtins.int) -> Particle

Related type: Particle

Look up a particle by PDG code.

Examples

Using the setup in the Model class example:

particle = model.particle_by_pdg(11)

Parameters

• pdg (int) Signed PDG particle code.

phi3

Model.phi3() -> Model

Load a real scalar phi with L_int = -g phi^3 / 3!. The external parameters mass and g default to one; the width is zero.

Examples

Using the setup in the Model class example:

model = hep.Model.phi3()

phi4

Model.phi4() -> Model

Load a real scalar phi with L_int = -lam phi^4 / 4!. The external parameters mass and lam default to one; the width is zero.

Examples

Using the setup in the Model class example:

model = hep.Model.phi4()

phi_3_4

Model.phi_3_4() -> Model

Load a real scalar phi with L_int = -g phi^3 / 3! - lam phi^4 / 4!. Independent parameters mass, g, and lam default to one; the width is zero.

Examples

Using the setup in the Model class example:

model = hep.Model.phi_3_4()

process

Model.process(
    incoming: typing.Sequence[Particle | ParticleSelector | builtins.str | builtins.int],
    outgoing: typing.Sequence[Particle | ParticleSelector | builtins.str | builtins.int],
    *,
    particle_veto: typing.Optional[typing.Sequence[Particle | ParticleSelector | builtins.str | builtins.int]] = None,
    vertex_allow: typing.Optional[typing.Sequence[VertexRule | builtins.str]] = None,
    vertex_veto: typing.Optional[typing.Sequence[VertexRule | builtins.str]] = None,
) -> Process

Related types: Particle, ParticleSelector, VertexRule, Process

Define a process with model-validated external states and sector restrictions. The returned process is immutable; loops and other calculation choices are arguments to its generate_diagrams, generate_amplitude and generate_cross_section methods.

Examples

Using the setup in the Model class example:

process = model.process(["e-", "e+"], ["a", "a"])
amplitude = process.generate_amplitude(loops=0)

Parameters

• incoming (sequence[Particle | ParticleSelector | str | int]) Ordered incoming external states.
• outgoing (sequence[Particle | ParticleSelector | str | int]) Ordered outgoing external states.
• particle_veto (sequence[Particle | ParticleSelector | str | int] or None, optional) Excluded species, including their antiparticles.
• vertex_allow (sequence[VertexRule | str] or None, optional) Allowed interactions. None allows all; an empty list allows none.
• vertex_veto (sequence[VertexRule | str] or None, optional) Excluded interactions.

propagator

Model.propagator(name: builtins.str) -> Propagator

Related type: Propagator

Look up a propagator by name.

Examples

Using the setup in the Model class example:

name = model.propagators[0].name
propagator = model.propagator(name)

Parameters

• name (str) Propagator name.

qcd

Model.qcd() -> Model

Load QCD with six quark flavors, gluons, and gluon ghosts, filtered from the Standard Model. Preserves its parameters and their default values.

Examples

Using the setup in the Model class example:

model = hep.Model.qcd()

qcd_qed

Model.qcd_qed() -> Model

Load strong and electromagnetic interactions of all quarks and charged leptons, including gluon ghosts, with Standard Model parameters.

Examples

Using the setup in the Model class example:

model = hep.Model.qcd_qed()

qed

Model.qed() -> Model

Load QED with photons and all charged fermions (including quarks), filtered from the Standard Model. Preserves its parameters and their default values.

Examples

Using the setup in the Model class example:

model = hep.Model.qed()

recompute_with

Model.recompute_with(evaluator: collections.abc.Callable[[EvaluationRequest], EvaluatedValues]) -> Model

Related types: EvaluationRequest, EvaluatedValues

Return a copy with all dependent values recomputed by a callback.

Examples

This callback evaluates the built-in scalar model at its default coupling lam=1. See EvaluationRequest for callback inputs.

from symbolica import S, E
from symbolica.community import hepkit as hep
model = hep.Model.phi4()
process = model.process(["phi", "phi"], ["phi", "phi"])
requests = []
def evaluate(request):
    requests.append(request)
    return hep.EvaluatedValues(
        couplings={"SCALAR_COUPLING": (0.0, -1.0)},
    )
updated_model = model.recompute_with(evaluate)
request = requests[0]
formulas = {item.name: item.expression for item in request.couplings}

Parameters

• evaluator (Callable[[EvaluationRequest], EvaluatedValues]) Callback that evaluates every expression in a request.

scalar_qed

Model.scalar_qed() -> Model

Load scalar QED in Feynman gauge with a, phi+, and phi-. Parameters mass=e=1 and lam=0; the scalar potential is mass^2 |phi|^2 + lam |phi|^4 / 4, and all widths vanish.

Examples

Using the setup in the Model class example:

model = hep.Model.scalar_qed()

standard_model

Model.standard_model() -> Model

Load the complete embedded Standard Model with default parameters. No model files or UFO installation are required.

Examples

Using the setup in the Model class example:

model = hep.Model.standard_model()

to_json

Model.to_json(pretty: builtins.bool = True) -> builtins.str

Serialize the model as JSON.

Examples

Using the setup in the Model class example:

model.to_json(pretty=False)

Parameters

• pretty (bool) Indent the output when true.

vertex_rule

Model.vertex_rule(name: builtins.str) -> VertexRule

Related type: VertexRule

Look up a vertex rule by name.

Examples

Using the setup in the Model class example:

vertex = model.vertex_rule("V_1")

Parameters

• name (str) Vertex-rule name.

with_parameter_card

Model.with_parameter_card(
    card: ParameterCard,
    evaluator: collections.abc.Callable[[EvaluationRequest], EvaluatedValues] | None = None,
) -> Model

Related types: ParameterCard, EvaluationRequest, EvaluatedValues

Return a copy with a parameter card applied atomically.

Examples

Using the setup in the Model class example:

card = model.default_parameter_card()
card.set("MM", 0.105658, 0.0)
updated = model.with_parameter_card(card)

Parameters

• card (ParameterCard) External parameter values to apply.
• evaluator (Callable[[EvaluationRequest], EvaluatedValues] or None) Optional evaluator used to recompute dependent values.

write_json

Model.write_json(path: builtins.str | os.PathLike | pathlib.Path) -> None

Write the model to a JSON file.

Examples

Using the setup in the Model class example:

model.write_json("model.json")

Parameters

• path (str or os.PathLike) Destination for the JSON model.

yang_mills

Model.yang_mills() -> Model

Load pure SU(3) Yang-Mills theory: gluons and gluon ghosts without quarks.

Examples

Using the setup in the Model class example:

model = hep.Model.yang_mills()