Metadata-Version: 2.3
Name: gammaloop
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: pyyaml >=6.0.1
Requires-Dist: pymupdf >=1.23.4
Requires-Dist: pydot >=3.0.1
License-File: LICENSE.md
License-File: LICENSE.md
Summary: Gammaloop computes differential cross-sections using Local Unitarity
Keywords: physics,collider,cross-section,perturbative,loop
Author: Valentin Hirschi <valentin.hirschi@gmail.com>
Author-email: Valentin Hirschi <valentin.hirschi@gmail.com>, Mathijs Fraaije <mathijsfraaije@gmail.com>, Lucien Huber <mail@lcnbr.ch>
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: homepage, https://alphaloop.ch
Project-URL: repository, https://github.com/alphal00p/gammaloop

# gammaLoop
![tests status](https://github.com/alphal00p/gammaloop/actions/workflows/gamma_loop_tests.yml/badge.svg?event=push)

*Computation of differential cross-sections using Local Unitarity.*

See [www.alphaloop.ch](www.alphaloop.ch) for details on the theoretical framework and related literature.

See the [wiki](https://wiki.alphaloop.ch/) for more information on the project.

## TL;DR: I want to be running γLoop already!

We salute the eagerness of our users.

If you want to jump right in, run the following to immediately start integrating the scalar three-loop mercedes diagram,

```bash
git clone https://github.com/alphal00p/gammaloop.git && cd gammaloop
./bin/compile.sh
./bin/gammaloop example/cards/scalar_mercedes.gL
```

or a one-loop hexagon diagram from the scattering process $\gamma \gamma \rightarrow \gamma \gamma \gamma \gamma$ (through a top-quark loop) with:

```bash
./bin/gammaloop examples/cards/physical_1L_AA_AAAA.gL
```

You can also generate diagrams for the computation of cross-sections or amplitudes with:
```bash
./bin/gammaloop -c "import_model sm; generate_amplitude d d~ > d d~ e+ e- | u d g ghg e- a QED=2 [{2} QCD=2]"
[...]
INFO    : A total of 2214 graphs have been generated in 00:00:49.142.
```

Process generation syntax is detailed on γLoop's [wiki](https://wiki.alphaloop.ch/en/gammaLoop/ProcessGeneration).

## Installation

### > Requirements

The installation may be successful with older versions than the ones indicated below, but it was not tested. 

* `Rust`: v1.81+ You can easily install Rust with this [one-liner](https://www.rust-lang.org/tools/install)

* `Python3`: v3.12+ (equipped with `pip`, and the `python-devel` dependency)

* `GNU gcc`: v14+

* `git`

Windows users are encouraged to use [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/).

### > Installation using `pip`
```bash
pip install gammaloop
gammaloop --build_dependencies
```

### > Installation from sources
```bash
git clone https://github.com/alphal00p/gammaloop.git
cd gammaloop
./bin/compile.sh --release
```
The relevant binaries will then be in `./bin/` and the gammaloop python module is located at `./python/gammaloop`.

*Note:* Alternatively, the dependencies can be built within a python virtual environment as follows:

```bash
./bin/build_dependencies.sh clean
./bin/build_dependencies.sh with_venv
# From within a `bash` shell, use the command below
source `./bin/gammaloop -venv`
# From within a `fish` shell, use the command below
. (./bin/gammaloop -venv).fish
```

## Tests

### > Testing an installation from `pip`

From within the installation directory of the gammaloop module, which you can `cd` into with e.g.:
```bash
bash -c 'cd `python -c "import os; import gammaloop; print(os.path.dirname(gammaloop.__file__))"`; pwd'
```

You can test your `gammaLoop` installation by running (incl. only tests with a maximum runtime of 15 seconds):
```bash
python -m pytest --max-runtime 15.0
```

### > Testing an installation from sources

From within the installation directory, run:
```bash
/bin/run_tests.sh python
/bin/run_tests.sh rust
```

## Usage

There are three entry points to the `GammaLoop` functionalities:

1. Preferred method is through the Python command-line interface `gammaloop`.

2. Alternatively, the same functionalities can be accessed programmatically, e.g. in a Jupyter notebook, through the Python API, by importing the `gammaloop` library.

3. Finally, expert users may also find it useful to steer some of functionalities directly from the rust binary `gammaloop_rust_cli`.

Both executables `gammaloop` and `gammaloop_rust_cli` are made available as scripts in the `bin` directory.
The `gammaloop` Python module is also exposed after installation and ready to be imported by custom Python scripts.

### 1. Usage from the Python command-line interface: ./gammaloop

`GammaLoop` is typically used through the python command-line interface `gammaloop`.
Place your list of commands in a file named e.g. `cmd.gL`, for instance:

```bash
# Content of file 'cmd.gL'
import_model sm --format ufo
export_model ./sm.yaml --format yaml
```
and run it with:
```bash
./bin/gammaloop cmd.gL
```
You can find more information on the syntax of the available commands in the [wiki](https://wiki.alphaloop.ch/) and by running:
```bash
./bin/gammaloop --help
```
to get an overview of available commands and:
```bash
./bin/gammaloop -c "help import_model"
```
to get help on any specific command.

You can find example of command files in the `<MODULE_PATH>/data/run_cards/` directory.

### 2. Usage from within a Jupyter notebook: the Python API

Follow the example jupyter notebook given in example to get started with the Python API.
```
cd <GAMMALOOP_INSTALLATION_DIRECTORY>/examples/jupyter
jupyter notebook steer_gammaloop.ipynb
``` 

### 3. Usage from the rust binary executable: ./gammaloop_rust_cli

All typical usecases of `GammaLoop` are available through the Python command-line interface mentioned earlier.
However, expert users might want to steer the Monte-Carlo integration directly using the `gammaloop_rust_cli` binary.
This is possible throught the `gammaloop_rust_cli` binary, which can be used as follows:
```bash
./bin/gammaloop_rust_cli --config <MODULE_PATH>/gammaloop/data/run_cards/rust_run_config.yaml
```
*Note*: You have to manually define your desired external momenta in this default `rust_run_config.yaml` file.

You will find more information on the content of the run configuration file and steering options in the [wiki](https://wiki.alphaloop.ch/) and by running:
```bash
./bin/gammaloop_rust_cli --help
```

