Skip to content

Commit afdd8f7

Browse files
ecavan95ecavan95
committed
v0.1.3 hotfix: ship QGRAF model files in wheel
1 parent e8cc13b commit afdd8f7

16 files changed

Lines changed: 1435 additions & 414 deletions

‎.github/workflows/tests.yml‎

Lines changed: 0 additions & 38 deletions
This file was deleted.

‎.zenodo.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"title": "FeynmanEngine",
3-
"version": "0.1.2",
3+
"version": "0.1.3",
44
"upload_type": "software",
55
"access_right": "open",
66
"license": "gpl-3.0-only",

‎CITATION.cff‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
cff-version: 1.2.0
22
message: "If you use this software, please cite it as below."
33
title: "FeynmanEngine"
4-
version: "0.1.2"
4+
version: "0.1.3"
55
type: software
66
license: "GPL-3.0-only"
77
abstract: "A Feynman diagram generator and amplitude calculator for particle physics with a Python API, browser UI, and packaged FastAPI service. Supports tree- and one-loop amplitudes, LO/NLO cross-sections (analytic K-factors, tabulated LHC ratios, Catani-Seymour subtraction, OpenLoops virtuals, EW Sudakov LL+NLL), differential observables, and PDF-convolved hadronic predictions."

‎INSTALLATION.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Installation Guide
2+
3+
Three install paths — pick what fits your use case.
4+
5+
| Path | Time | What you get | When to choose |
6+
|---|---|---|---|
7+
| **Docker** | 1 min | Everything bundled, no build | Easiest. Trying it out, demos. |
8+
| **Full pip** | 10–20 min | All native HEP tools built locally | Most users; you'll get every feature. |
9+
| **Lightweight pip** | 3 min | QGRAF + FORM + LoopTools only | Teaching, CI without `gfortran`, fastest install. |
10+
11+
---
12+
13+
## Docker (easiest)
14+
15+
```bash
16+
docker run -p 8000:8000 ecavan/feynman-api:latest
17+
# Open http://localhost:8000
18+
```
19+
20+
The image bundles QGRAF, FORM, LoopTools, LHAPDF (with CT18LO), OpenLoops 2 (with the `ppllj` process library), and the LaTeX/SVG rendering stack.
21+
22+
No system prerequisites needed beyond Docker itself. **Recommended on Windows** — saves you Windows-specific build issues with Fortran toolchains.
23+
24+
---
25+
26+
## Full pip install (recommended for native users)
27+
28+
### 1. System prerequisites
29+
30+
You need a Fortran + C/C++ toolchain, plus optional LaTeX for SVG diagram rendering.
31+
32+
#### macOS
33+
34+
```bash
35+
# Build toolchain (required)
36+
brew install gcc make # gcc package gives you gfortran
37+
38+
# LaTeX + SVG rendering (optional but recommended for diagrams)
39+
brew install basictex pdf2svg
40+
sudo tlmgr update --self
41+
sudo tlmgr install tikz-feynman standalone
42+
```
43+
44+
#### Debian / Ubuntu / WSL
45+
46+
```bash
47+
sudo apt-get update
48+
sudo apt-get install -y gfortran g++ make python3-dev
49+
50+
# LaTeX + SVG rendering (optional)
51+
sudo apt-get install -y texlive-luatex texlive-pictures texlive-science pdf2svg
52+
```
53+
54+
#### Windows (native)
55+
56+
Native Windows is **not officially supported** for the local-build path because QGRAF + FORM + LoopTools + LHAPDF + OpenLoops are all Fortran/C/C++ projects with Unix-style build systems. Two options:
57+
58+
- **Use Docker** (recommended): see the Docker section above.
59+
- **Use WSL2** (Windows Subsystem for Linux): install Ubuntu via WSL, then follow the Debian/Ubuntu section above.
60+
61+
### 2. Install + build
62+
63+
```bash
64+
pip install feynman-engine
65+
feynman setup # ~10–20 min, one-time. Builds QGRAF + FORM + LoopTools + LHAPDF + OpenLoops 2
66+
feynman doctor # verify all 5 native deps are 'ok'
67+
feynman serve # http://localhost:8000
68+
```
69+
70+
`feynman setup` will:
71+
1. Compile QGRAF (Fortran, ~30 s)
72+
2. Compile FORM (C, ~1 min)
73+
3. Compile LoopTools (Fortran + C, ~2 min)
74+
4. Compile LHAPDF (C++, ~3-5 min) and download the CT18LO PDF set (~10 MB)
75+
5. Compile OpenLoops 2 via SCons (Fortran, ~5-10 min) and download the `ppllj` process library
76+
77+
If any step fails, the recommended `feynman doctor` output points you at the specific install command to retry.
78+
79+
---
80+
81+
## Lightweight pip install
82+
83+
Skip the slowest dependencies for a 3-minute install:
84+
85+
```bash
86+
pip install feynman-engine
87+
feynman setup --skip-lhapdf --skip-openloops
88+
```
89+
90+
You still get:
91+
- All Feynman diagram generation (QGRAF + FORM)
92+
- All tree-level amplitudes for QED, QCD, EW, BSM
93+
- LO cross-sections via scipy/MC
94+
- Loop amplitudes via the LoopTools backend
95+
- Tabulated NLO K-factors for major LHC channels (DY, tt̄, ggH, WW, ZZ, ZH, VBF)
96+
- Universal QED NLO + EW Sudakov NLO closed-form K-factors
97+
- The browser UI
98+
99+
What you lose:
100+
- **LHAPDF**: hadronic cross-sections fall back to a built-in LO PDF (factor-of-2-3 accuracy instead of percent-level)
101+
- **OpenLoops**: NLO σ for unregistered QCD processes returns `HTTP 422` with a workaround
102+
103+
You can add these later:
104+
```bash
105+
feynman install-lhapdf
106+
feynman install-pdf-set CT18LO
107+
feynman install-openloops
108+
feynman install-process ppllj
109+
```
110+
111+
---
112+
113+
## Verifying the install
114+
115+
```bash
116+
feynman doctor
117+
```
118+
119+
Should report each component as `ok` or `missing`. Example healthy output:
120+
121+
```
122+
FeynmanEngine doctor
123+
Backend: qgraf (/path/to/bin/qgraf)
124+
QGRAF: ok | binary=...
125+
FORM: ok | binary=...
126+
LoopTools: ok | library=...
127+
LHAPDF: ok | version=6.5.5 | sets=['CT18LO']
128+
OpenLoops: ok | prefix=... | processes=['ppllj']
129+
Rendering: lualatex=ok, pdf2svg=ok
130+
Toolchain: gfortran=..., make=..., cc=..., c++=...
131+
Recommendation: native dependencies look ready.
132+
```
133+
134+
If anything is `missing`, the `Recommendation:` line tells you the exact command to fix it.
135+
136+
---
137+
138+
## Troubleshooting
139+
140+
### `gfortran: command not found`
141+
- macOS: `brew install gcc` (the Homebrew `gcc` package includes `gfortran`)
142+
- Debian/Ubuntu: `sudo apt-get install gfortran`
143+
144+
### `feynman setup` hangs on OpenLoops download
145+
The OpenLoops `ppllj` process library is downloaded from openloops.hepforge.org during setup. If it hangs:
146+
- Check internet access
147+
- Re-run with `feynman install-openloops --no-process` to skip the download
148+
- Manually install later: `feynman install-process ppllj`
149+
150+
### `feynman doctor` reports `LoopTools: missing` but `gfortran` is installed
151+
LoopTools requires `gfortran` and a working `make`. On macOS the Apple `gcc` is actually clang (no Fortran). Install Homebrew's gcc package: `brew install gcc`.
152+
153+
### `lualatex: command not found` (SVG rendering missing)
154+
SVG diagram rendering requires `lualatex` + `pdf2svg`. The engine still works without these — you just don't get rendered diagrams (the TikZ source is always returned).
155+
156+
### Anything else
157+
File an issue at https://github.com/ecavan/FeynmanAPI/issues with the output of `feynman doctor` attached.
158+
159+
---
160+
161+
## Upgrading
162+
163+
```bash
164+
pip install --upgrade feynman-engine
165+
# Native binaries built by `feynman setup` are NOT recompiled on package upgrade.
166+
# If a major version bumps a bundled tool (QGRAF, FORM, LoopTools, LHAPDF,
167+
# OpenLoops), re-run:
168+
feynman setup --force
169+
```

‎MANIFEST.in‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
include qgraf-3.6.10.tgz
22
recursive-include feynman_engine/resources/qgraf *.tgz
3+
recursive-include feynman_engine/resources/qgraf/models *.mod
4+
recursive-include feynman_engine/resources/qgraf/styles *.sty
35
recursive-include feynman_engine/resources/looptools *.tar
46
recursive-include feynman_engine/resources/form *.tar.gz
57
recursive-include feynman_engine/resources/lhapdf *.tar.gz

‎README.md‎

Lines changed: 6 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -91,35 +91,19 @@ FeynmanEngine takes a process string and produces, end-to-end:
9191

9292
## Installation
9393

94-
### Docker (recommended — everything bundled)
94+
Three install paths — Docker (1 min), full pip (~10–20 min), or lightweight pip (~3 min). Quick start:
9595

9696
```bash
97+
# Easiest — everything bundled
9798
docker run -p 8000:8000 ecavan/feynman-api:latest
98-
# Open http://localhost:8000
99-
```
100-
101-
The image includes QGRAF, FORM, LoopTools, LHAPDF (with CT18LO), OpenLoops 2 (with the ppllj process library), and the LaTeX/SVG rendering stack.
102-
103-
### PyPI
10499

105-
```bash
100+
# Or via PyPI
106101
pip install feynman-engine
107-
feynman setup # builds QGRAF + FORM + LoopTools + LHAPDF + OpenLoops 2 (~10-15 min, one-time)
108-
feynman doctor # verify everything is in place
109-
feynman serve # launch the API + UI on http://localhost:8000
110-
```
111-
112-
The full `feynman setup` is the recommended path — it gives you generic NLO QCD virtuals (via OpenLoops 2) and percent-level hadronic-σ accuracy (via LHAPDF + CT18LO) out of the box.
113-
114-
For a faster, lighter install (e.g. teaching, CI without `gfortran`):
115-
116-
```bash
117-
feynman setup --skip-openloops --skip-lhapdf # ~3 min, drops generic-QCD-NLO + precision PDFs
102+
feynman setup # ~10–20 min, builds QGRAF + FORM + LoopTools + LHAPDF + OpenLoops 2
103+
feynman serve # http://localhost:8000
118104
```
119105

120-
In skip mode: tabulated NLO K-factors still cover the major LHC channels (DY, tt̄, ggH, WW, ZZ, ZH, VBF), and a built-in LO PDF gives factor-of-2-3 accurate hadronic σ. NLO requests for unregistered QCD processes return HTTP 422 with a hint to install OpenLoops.
121-
122-
Add more OpenLoops process libraries on demand: `feynman install-process pptt`, `feynman install-process pphjj`, etc.
106+
**See [INSTALLATION.md](INSTALLATION.md) for full instructions** — platform-specific prerequisites (macOS / Debian / WSL), the lightweight install path, doctor verification, and troubleshooting.
123107

124108
For SVG diagram rendering you also need `lualatex` + `pdf2svg` (`brew install basictex pdf2svg` on macOS; `apt-get install texlive-luatex texlive-pictures texlive-science pdf2svg` on Debian/Ubuntu).
125109

0 commit comments

Comments
 (0)