alpaca-ALPs 1.2.0rc2

The ALP Automatic Computing Algorithm

ALP-aca

Welcome to the ALP Automated Computed Algorithm (ALP-aca)!

ALP-aca is an open-source Python library for the phenomenology of Axion-Like Particles (ALPs) with masses in the ranges of $m_a \sim 0.01 - 10,\mathrm{GeV}$, mainly in processes involving mesons.

ALP-aca integrates the full analysis with an easy-to-use syntax:

• Matching of selected UV-complete models (DFSZ-like, KSVZ-like, flaxions, etc.) to the ALP-EFT.
• Numerical running and matching of the ALP-EFT coefficients down to the physical relevant scales, including ALP-$\chi!$ PT.
• Calulation of decay rates for processes involving ALPs:
  • ALP production in rare meson decays $M_1\to M_2 a$, quarkonia decays $V\to \gamma a$ and non-resonant production $e^+e^- \to \gamma a$,
  • ALP decays into photons, leptons and mesons,
  • Processes mediated by on-shell ALPs in the Narrow Width Approximation,
  • Leptonic and radiative meson decays, and meson mixing, with off-shell ALPs.
• Calculation of ALP decay lengths and probability of decaying outside the detector, with a displaced vertex or in the prompt region.
• $\chi^2$ statistical analysis, with fine-grained control of the observables and experimental measurements included.
• Generation of publication-grade exclusion plots.
• Automatic management of the bibliographical references used in the analysis.

The ALP-aca team

• Jorge Alda: Università degli Studi di Padova & INFN Sezione di Padova & CAPA Zaragoza.
• Marta Fuentes Zamoro: Universidad Autónoma de Madrid & IFT Madrid.
• Luca Merlo: Universidad Autónoma de Madrid & IFT Madrid.
• Xavier Ponce Díaz: University of Basel.
• Stefano Rigolin: Università degli Studi di Padova & INFN Sezione di Padova.

ALP-aca in action

In this repositoy you can find examples, tutorials and applications of ALP-aca.

ALP-aca has been used in the following publications:

• J. Alda, M. Fuentes Zamoro, L. Merlo, X. Ponce Díaz, S. Rigolin: Comprehensive ALP searches in Meson Decays. arXiv:2507.19578

• M. Fuentes Zamoro, J. Alda, L. Merlo, X. Ponce Diaz, S. Rigolin: Tackling ALP searches in meson decays with ALPaca: a phenomenological approach. PoS(COSMICWISPers2025) (2026) 057

• J. Alda: Lecture notes on Machine Learning applications for global fits. arXiv:2604.07520

If you have used ALP-aca in your publication and want to be featured in this list, please contact us.

Installation

ALP-aca can be installed with pip:

pip3 install alpaca-ALPs

The plotting backends, matplotlib and plotly, are not included as depencencies of ALP-aca, but they can be installed as optional dependencies. To install with matplotlib

pip3 install alpaca-ALPs[matplotlib]

with plotly

pip3 install alpaca-ALPs[plotly]

and with both

pip3 install alpaca-ALPs[matplotlib,plotly]

It is strongly recommended to install ALP-aca inside a virtual environment (venv), in order to avoid clashes with conflicting versions of the dependencies. In order to create a venv, execute the following command

python3 -m venv pathToVenv

where pathToVenv is the location where the files of the venv will be stored. In order to activate the venv, for Linux or MacOS using bash or zsh

source pathToVenv/bin/activate

For Windows using cmd.exe

C:\> pathToVenv\Scripts\Activate.bat

And for Windows using PowerShell

PS C:\> path_to_venv\Scripts\Activate.ps1

Once the venv is activated, ALPaca can be normally installed and used.

Citing ALP-aca

If you use ALP-aca, please cite

@article{Alda:2025nsz,
    author = "Alda, Jorge and Fuentes Zamoro, Marta and Merlo, Luca and Ponce D{\'\i}az, Xavier and Rigolin, Stefano",
    title = "{ALPaca: The ALP Automatic Computing Algorithm}",
    eprint = "2508.08354",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    reportNumber = "IFT-UAM/CSIC-25-82",
    month = "8",
    year = "2025"
}

@software{alda_2025_16447036,
  author       = {Alda, Jorge and
                  Fuentes Zamoro, Marta and
                  Merlo, Luca and
                  Rigolin, Stefano and
                  Ponce Díaz, Xavier},
  title        = {ALPaca v1.0},
  month        = jul,
  year         = 2025,
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.16447036},
  url          = {https://doi.org/10.5281/zenodo.16447036},
}

Documentation

The ALPaca manual for v1.0.0 is available on arXiv. For newer versions, check the changelogs:

• v1.1.0 (31 October 2025)

You can also check the automatically-generated documentation.

Try also the AI-powered wiki and assistant:

Feedback

If you encounter bugs or want to propose a new feature, you can contact us using Gihub issues.