UFO Model Loader

UFO Model Loader is a Python CLI and library to work with High-Energy Physics models in the UFO format.
It can:

• Load UFO models or pre-exported JSON models
• Apply restrictions from parameter cards
• Evaluate all dependent parameters from input parameters using Symbolica
• Simplify couplings and disable zero contributions
• Preserve propagating/Goldstone flags, custom propagators, particle chemical potentials, declared functions, and form-factor metadata
• Export the result as a flat JSON model

Limitations:

• Only tree-level information is being retained and exported
• Current version only supports export of model expression in the Symbolica notation

Installation

Version 1.0.0 requires Python 3.11 or newer and Symbolica 3.0.0 or newer. Symbolica is available on PyPI and is installed automatically as a dependency; no separate Git-source installation is needed.

From PyPI:

pip install ufo-model-loader

From GitHub:

pip install "git+https://github.com/alphal00p/ufo_model_loader.git"

Command Line Usage

ufo_model_loader --help

Example:

ufo_model_loader -i sm -r no_b_mass -o sm_flat.json

This will:

1. Load the default UFO sm model shipped with this python module
2. Apply restrictions from restrict_no_b_mass.dat
3. Simplify the model by removing zero contributions and parameters set to zero.
4. Write the model sm_flat.json and its corresponding parameter card sm_flat_param_card.json to the current directory.

Library Usage

When using UFO Model Loader as a library, you can import the main functions:

from ufo_model_loader.commands import load_model, export_model, JSONLook

loaded_sm_no_b_mass, input_param_card_no_b_mass = load_model(
    input_model_path = 'sm',
    restriction_name = 'no_b_mass',
    simplify_model = True,
)

exported_model_path = export_model(
    model = loaded_sm_no_b_mass,
    input_param_card = input_param_card_no_b_mass,
    output_model_path = 'sm_no_b_mass_simplified_flat.json',
    json_look = JSONLook.VERBOSE,
    allow_overwrite = True
)

Built-in models

UFO Model Loader comes with the following built-in models: sm, scalars, and scalar_gravity, which can be specified as input models directly from their names (the corresponding UFO directories are shipped with the Python package).

The sm model attaches a chemical potential to every particle that carries baryon number, electric charge, or lepton flavour. The independent chemical potentials are the external parameters muB, muQ, muLe, muLmu, and muLtau in the CHEMICALPOTENTIAL block. All default to zero for ordinary vacuum use. Since restriction with simplification freezes zero-valued external parameters, load with simplify_model=False to vary these inputs, or provide an explicit nonzero parameter card before simplification. Each particle's chemical potential is derived from its charges, and antiparticles carry the opposite value through the corresponding minus_<name> parameter. Chemical potentials do not enter vacuum couplings.

Particle electric charges are numeric inside the loader and exported exactly as JSON integers or rational strings such as "2/3". Hypercharges use Q = T3 + Y/2: y_charge is left-handed for fermions, and the optional y_charge_right is right-handed. Charge conjugation swaps these chiralities and negates their values. Missing/undefined hypercharge is null, not zero; in particular the real neutral H and G0 fields have no definite hypercharge. The bundled SM metadata matches Symbolica 3.0.0 HepKit's Model.standard_model(). Models without these optional fields remain supported, and older numeric JSON charges can still be loaded. Consumers of the 1.0.0 JSON format must accept rational strings and optional hypercharges.

The scalars model is a purely scalar toy model, with a number of scalars controlled by the environment variable UFO_SCALARS_MODEL_N_SCALARS, and all possible n-point interactions mixing these scalars, with n given by the environment variable UFO_SCALARS_MODEL_N_POINT_INTERACTIONS. By default, UFO_SCALARS_MODEL_N_SCALARS="3" and UFO_SCALARS_MODEL_N_POINT_INTERACTIONS="3,4,5,6,7,8,9,10".

The scalar_gravity model couples a configurable number of scalar fields to a massless spin-2 graviton. The number of scalars is controlled by UFO_GRAVITY_MODEL_N_SCALARS and defaults to three.

For example, the following:

UFO_SCALARS_MODEL_N_SCALARS=7 UFO_SCALARS_MODEL_N_POINT_INTERACTIONS="3,4,5,6,7,8" ufo_model_loader -j compact -i scalars -o scalars_big_model.json; du -hc scalars_big_model.json

yields a pretty big model :)

[23:34:27] INFO    : Loading UFO model scalars from directory '[...]/ufo_model_loader/src/ufo_model_loader/data/models'
Loading UFO scalars model with 7 scalars
Loading UFO scalars model with n-point interactions, n=[3|4|5|6|7|8]
[23:34:28] INFO    : Applying default restriction to model scalars
[23:34:28] INFO    : The following 6 external parameters were forced to zero by the restriction card:
width_scalar_1, width_scalar_2, width_scalar_3, width_scalar_4, width_scalar_5, width_scalar_6
[23:34:28] INFO    : Model scalars successfully loaded (7 particles, 20 parameters, 6399 interactions, 1 couplings, 6 Lorentz structures)
[23:34:28] INFO    : Successfully exported model in compact JSON format to file 'scalars_big_model.json' and corresponding input parameter card to 'scalars_big_model_param_card.json'
1.5M	scalars_big_model.json
1.5M	total

Tests

Install the test dependencies and test your installation with

python -m pip install "ufo-model-loader[dev,prettyjson]"
python -m pytest --pyargs ufo_model_loader_tests

Main options

• --input_model, -i
  UFO directory or JSON file path to load.

• --restriction_name, -r
  Restriction to apply (restrict_<restriction_name>.dat in UFO or restrict_<restriction_name>.json beside a JSON model). Without this option, restrict_default.dat or restrict_default.json is applied when present. Legacy <model>_default.json cards remain accepted.

• --simplify / --no-simplify
  Remove zero contributions in the model given specified restriction. Default: enabled.

• --wrap_indices_in_lorentz_structures Wrap indices in Lorentz structures when exporting. This is particularly useful for spin-2 models, mapping <1 or 2>00<p_id> conventions to idx(1 or 2, p_id). Default: disabled.

• --output_model_path, -o
  Output path for the JSON model. Defaults to current directory.

• --json_look, -j
  Output format: compact, pretty, or verbose. Default: verbose. Note: pretty requires the optional python package jsbeautifier.

• --verbosity, -v
  Logging level: debug, info, critical.

• --overwrite, -w
  Allow overwriting existing output files.

Development

Clone the repo and install in editable mode:

git clone https://github.com/alphal00p/ufo_model_loader.git
cd ufo_model_loader
python -m pip install --upgrade -e ".[dev,prettyjson]"
python -m pytest

Release dry run

From the repository root, build the source distribution and wheel, then check their PyPI metadata without uploading anything:

python -m build
python -m twine check dist/*

The pypi_publish.sh helper runs these same two steps with python3. Activate the intended development or release environment before running it. It does not delete existing artifacts or upload to PyPI or TestPyPI.