Metadata-Version: 2.4
Name: ufo_model_loader
Version: 1.0.0
Summary: Tool for loading high-energy physics models in the UFO format and export them in flat JSON format.
Author-email: Valentin Hirschi <valentin.hirschi@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/alphal00p/ufo_model_loader
Project-URL: Issues, https://github.com/alphal00p/ufo_model_loader/issues
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: symbolica>=3.0.0
Provides-Extra: prettyjson
Requires-Dist: jsbeautifier; extra == "prettyjson"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# UFO Model Loader

**UFO Model Loader** is a Python CLI and library to work with High-Energy Physics models in the [UFO format](https://arxiv.org/pdf/2304.09883).  
It can:

- Load UFO models or pre-exported JSON models
- Apply restrictions from parameter cards
- Evaluate all dependent parameters from input parameters using [Symbolica](https://symbolica.io/)
- 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](https://symbolica.io/) 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:

```bash
pip install ufo-model-loader
```

From GitHub:

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

---

## Command Line Usage

```bash
ufo_model_loader --help
```

Example:

```bash
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:

```python
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:
```bash
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

```bash
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:

```bash
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:

```bash
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.
