|
🚀 Quick Start · ⚛️ Physics · 🔧 Tools · 📖 Examples · 📚 Citations
🏛️ Built on Lilith
⚠️ IMPORTANT: This project is a wrapper around Lilith-2, a powerful Python tool developed by Sabine Kraml and collaborators at LPSC Grenoble. All physics calculations are performed by Lilith — Pythia simply provides an MCP interface.
⭐ Star the Original Lilith Repository and cite the Lilith papers in your research!
🎯 What is Pythia?
🔬 The Challenge |
✅ Pythia Solution |
⚛️ Physics Background
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ THE 125 GeV HIGGS BOSON │
│ │
│ Discovery: July 4, 2012 at CERN's Large Hadron Collider │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Production Modes Decay Channels │ │
│ │ ──────────────── ────────────── │ │
│ │ • ggF (gluon fusion) • H → γγ (diphoton) │ │
│ │ • VBF (vector boson) • H → ZZ* → 4ℓ │ │
│ │ • WH, ZH (associated) • H → WW* → ℓνℓν │ │
│ │ • ttH (top associated) • H → bb̄, ττ, μμ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Signal Strength: μ = σ_observed / σ_SM_predicted │
│ │
│ μ = 1 → Standard Model ✓ │
│ μ ≠ 1 → New Physics! 🎉 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
📊 Reduced Couplings (κ-Framework)
| Coupling | SM Value | Description |
|---|---|---|
| C_V | 1.0 | Coupling to W and Z bosons |
| C_t | 1.0 | Coupling to top quark |
| C_b | 1.0 | Coupling to bottom quark |
| C_τ | 1.0 | Coupling to tau lepton |
| C_g | 1.0 | Effective coupling to gluons (loop) |
| C_γ | 1.0 | Effective coupling to photons (loop) |
🚀 Quick Start
📦 Installation
# Clone the repository
git clone https://github.com/consigcody94/pythia-mcp.git
cd pythia-mcp
# Install Node.js dependencies
npm install
# Build TypeScript
npm run build
# Ensure Python dependencies are installed
pip install numpy scipy
⚡ Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"pythia": {
"command": "node",
"args": ["/path/to/pythia-mcp/dist/index.js"],
"env": {
"LILITH_DIR": "/path/to/pythia-mcp/lilith",
"PYTHON_CMD": "python3"
}
}
}
}
✅ Verify Installation
cd lilith
python run_lilith.py userinput/example_couplings.xml
🔧 Available Tools
🔬 Core Analysis
| Tool | Description |
|---|---|
compute_likelihood | Calculate -2 log(L) for BSM scenarios |
compute_sm_likelihood | Get Standard Model reference |
compute_pvalue | Calculate p-value for model comparison |
scan_1d | 1D parameter scan with likelihood profile |
scan_2d | 2D scan for contour plots |
📊 Data Management
| Tool | Description |
|---|---|
list_experimental_data | List datasets in Lilith database |
search_hepdata | Search HEPData for new measurements |
fetch_hepdata_record | Download specific HEPData record |
get_latest_higgs_data | Fetch latest from all sources |
🧪 Physics Models
| Tool | Description |
|---|---|
analyze_2hdm | Two-Higgs-Doublet Model analysis |
analyze_singlet_extension | Higgs singlet extension |
get_sm_predictions | SM cross sections & branching ratios |
convert_to_signal_strength | Convert couplings to μ values |
📖 Usage Examples
Example 1: Standard Model Check
"Use Pythia to compute the Standard Model likelihood and tell me if the Higgs data is consistent with the SM."
Example 2: BSM Scenario
"Calculate the likelihood for a model where the Higgs coupling to top quarks is 0.9 and to vector bosons is 1.1"
{
"mode": "couplings",
"Ct": 0.9,
"CV": 1.1
}
Example 3: 2HDM Analysis
"Analyze a Type-II 2HDM with tan(β) = 2 and sin(β-α) = 0.99"
{
"type": "II",
"tanBeta": 2,
"sinBetaMinusAlpha": 0.99
}
Example 4: Parameter Scan
"Scan the CV-CF plane from 0.8 to 1.2 with 50 steps each"
{
"param1": {"name": "CV", "min": 0.8, "max": 1.2, "steps": 50},
"param2": {"name": "CF", "min": 0.8, "max": 1.2, "steps": 50}
}
📊 Data Sources
┌─────────────────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 🔬 LILITH DB │ │ 📚 HEPDATA │ │ 🌐 CERN OPEN │ │
│ │ ────────────── │ │ ────────────── │ │ ────────────── │ │
│ │ Run 1 (7+8TeV) │ │ Official HEP │ │ Real collision │ │
│ │ Run 2 (13TeV) │ │ data archive │ │ data & MC │ │
│ │ ATLAS + CMS │ │ CERN/Durham │ │ analysis code │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
🏗️ Architecture
pythia-mcp/
├── 📦 src/
│ ├── index.ts # MCP server entry point
│ └── tools/ # Tool implementations
│
├── 🔮 lilith/ # Lilith library (bundled)
│ ├── run_lilith.py # Main entry point
│ ├── userinput/ # XML input templates
│ └── data/ # Experimental database
│
├── 📦 dist/ # Compiled output
├── 📄 package.json
└── 📄 tsconfig.json
📚 Citations & Acknowledgments
📖 Required Citations
If you use Pythia for research, you MUST cite Lilith:
@article{Bernon:2015hsa,
author = "Bernon, Jérémy and Dumont, Béranger",
title = "{Lilith: A tool for constraining new physics from Higgs measurements}",
journal = "Eur. Phys. J. C",
volume = "75",
pages = "440",
year = "2015",
doi = "10.1140/epjc/s10052-015-3645-9",
eprint = "1502.04138",
archivePrefix = "arXiv"
}
@article{Kraml:2019sis,
author = "Kraml, Sabine and others",
title = "{Lilith-2: Improved precision constraints}",
year = "2019",
eprint = "1908.03952",
archivePrefix = "arXiv"
}
🙏 Special Thanks
| Sabine Kraml & Lilith Team | LPSC Grenoble |
| ATLAS & CMS Collaborations | Higgs measurements |
| HEPData Team | Durham/CERN |
| Anthropic | MCP Protocol |
🔗 References
| Resource | Link |
|---|---|
| Lilith-2 | github.com/sabinekraml/Lilith-2 |
| Lilith Paper | arXiv:1502.04138 |
| HEPData | hepdata.net |
| CERN Open Data | opendata.cern.ch |
| LHC Higgs XS WG | twiki.cern.ch |
📄 License
GNU General Public License v3.0
This project and Lilith are licensed under GPL v3 - see LICENSE for details.
🔮 Pythia — Seeking Truth in the Higgs Sector
"The Higgs boson is the key to understanding the origin of mass in the universe."
— Peter Higgs
Made with dedication to open science and particle physics research