GEMSTORE: Hadron Spectroscopy Simulation Tools

GEMSTORE is a specialized scientific software suite for hadron spectroscopy calculations using advanced quark models. It combines the computational efficiency of the Gaussian Expanding Method with the physics-rich screen-modified Godfrey-Isgur (GI) model to predict meson, baryon, and exotic hadron properties.

• 🎯 Multiple Quark Models: GI-Screen, GI-String
• 📊 Spectral Calculations: Masses, RMS radii, eigenvector analysis
• 🔧 Flexible Quantum Numbers: Full support for arbitrary L, S, J combinations
• 🤖 AI-Assisted Workflows: Integrated OpenCode assistant for intelligent task automation
• 📈 Advanced Data Analysis: Eigenvector analysis, normalization validation, statistical summaries
• ⚡ High Performance: Optimized C implementation with Minuit2 numerical library
• 🔬 Parameter Fitting: Gradient-based optimization with Minuit2

1. Features
2. System Requirements
3. Installation
4. Quick Start
5. Core Algorithms
6. AI Integration
7. Main Functions
8. Usage Examples
9. Project Structure
10. Contributing
11. License

• SPECTRA: Calculate complete hadron mass spectra with eigenvectors
• RADIUS: Compute RMS radii and spatial distributions

• MESON: Quark-antiquark bound states (qq̄)
• BARYON: Three-quark states (qqq)

• GEM (Generalized Exponential Morse): Efficient Gaussian basis with exponential envelope

• OS: Linux/Unix (macOS with GNU tools)
• Compiler: GCC 7.0+ or Clang 5.0+
• Build Tool: GNU Make 4.0+
• Memory: 512 MB RAM
• Storage: 100 MB installation + 1 GB for calculations

• LAPACK/OpenBLAS: For accelerated linear algebra
• Python 3.7+: For input file generation scripts
• OpenCode: For AI-assisted workflow integration

git clone --recursive https://github.com/serialcore/gemstore.git
cd gemstore

# Standard build
make clean && make

# With LAPACK acceleration
make clean && make USE_LAPACKE=1

# Install to system (requires sudo)
make install

# Uninstall from system
make uninstall

./gemstore --help
./gemstore --version

# Run a meson spectroscopy calculation with JSON input
./gemstore --compute amethyst.json

# Run with predefined parameters
./gemstore --compute diamond.json

# Fit a built-in GISCREEN dataset
./gemstore --compute test/FittingTask/giscreen_csbar.json

GEMSTORE uses JSON for configuration. Create my_meson.json:

{
  "project": "my_project",
  "task": "SPECTRA",
  "model": {
    "type": "GISCREEN",
    "param": "GISCREEN_CCBAR"
  },
  "system": {
    "type": "MESON",
    "f1": 3,
    "f2": 3,
    "S": 1,
    "L": 0,
    "J": 1
  },
  "basis": {
    "type": "GEM",
    "nmax": 16,
    "rmax": 30.0,
    "rmin": 0.1
  },
  "print": {
    "pot": "false",
    "wfn": "false"
  }
}

Run it:

./gemstore --compute my_meson.json

"model": {
  "type": "GISCREEN", "GISTRING", "NRSTRING", or "NRSCREEN",
  "param": "GISCREEN_CCBAR", "GISTRING_CUSTOM", "NRSTRING_MESON", or "NRSCREEN_CUSTOM",
  "file": "param_file.json"  // Only for CUSTOM params
}

model.type:

• GISTRING — relativistic GI model, linear confinement
• GISCREEN — relativistic GI model, screened confinement
• NRSTRING — non-relativistic Cornell model, linear confinement
• NRSCREEN — non-relativistic Cornell model, screened confinement

Predefined Parameter Sets:

• GISCREEN_CCBAR - Charm-anticharm with GI-Screen model
• GISCREEN_BBBAR - Bottom-antibottom with GI-Screen model
• GISTRING_MESON - General mesons with GI-String model
• GISTRING_BARYON - Smeared linear GI parameters
• GISCREEN_CUSTOM - Custom parameters from file (requires "file" field)
• GISTRING_CUSTOM - Custom GI-String parameters from file
• NRSTRING_MESON - Built-in meson parameters for NR-String
• NRSCREEN_MESON - Built-in meson parameters for NR-Screen
• NRSTRING_CUSTOM - Custom NR-String parameters from file (requires "file")
• NRSCREEN_CUSTOM - Custom NR-Screen parameters from file (requires "file")

"system": {
  "type": "MESON",
  "f1": <flavor_index>,
  "f2": <flavor_index>,
  "S": <spin>,
  "L": <orbital>,
  "J": <total_angular_momentum>
}

Quark Flavors (indices):

Quantum Numbers:

• S: Spin (0 = singlet, 1 = triplet)
• L: Orbital angular momentum (0, 1, 2, ...)
• J: Total angular momentum J = L + S or |L - S|

Baryon ("type": "BARYON").

"system": {
  "type": "BARYON",
  "f1": 1, "f2": 1, "f3": 3,
  "J": 0.5, "P": 1, "sym12": -1, "Lmax": 0
}

P is parity. sym12 is the sign under (1\leftrightarrow 2). Lmax keeps (l_\rho+l_\lambda\le L_{\max}) on three Jacobi charts. Optional jl switches to the chart: (c=1), (l_\rho=0), (l_\lambda=L_{\max}). Pair with GISTRING_BARYON. <project>.state.json stores mass, rms_r12, rms_r13, rms_r23. Inputs: test/Spectra-Baryon/.

GEM (Generalized Exponential Morse):

"basis": {
  "type": "GEM",
  "nmax": 16,
  "rmax": 30.0,
  "rmin": 0.1
}

SHO (Spherical Harmonic Oscillator):

"basis": {
  "type": "SHO",
  "nmax": 16,
  "beta": 0.8
}

Controls output of potential and wavefunction files:

"print": {
  "pot": "true",
  "wfn": "true"
}

• "true" → enabled (1)
• "false" → disabled (0)

When enabled:

• Potential: <project>.pot.dat (r, V)
• Wavefunction: <project>.wfn.N.dat (one file per state, r, φ(r))

Generated by write_meson_spectra() in src/print.c (lines 234-379), GEMSTORE automatically creates <project>.out.json:

{
  "generated": "2026-04-25 18:33:25",
  "project": "amethyst",
  "task": "SPECTRA",
  "model": { ... },
  "system": { ... },
  "basis": { ... },
  "states": [
    {
      "index": 1,
      "mass": 3.101986299943893,
      "rms_radius": 0.324597538486162,
      "eigenvector": [0.43147459..., 0.56587312..., ...]
    },
    ...
  ]
}

Output Fields:

When "print":{"pot":"true"} or "print":{"wfn":"true"} is set:

• Potential: <project>.pot.dat — two-column file (r, V(r))
• Wavefunction: <project>.wfn.N.dat — one file per state (r, φ(r))

Both files contain exactly 990 lines with r from 0.01 fm to 10.0 fm (Δr = 0.01 fm), matching the format used by Origin and similar plotting tools.

Example output line:

0.01000000    -0.12345678e+00

| project | string | Project name (from input) | | task | string | Calculation type (from input) | | model | object | Model configuration (echoed from input) | | system | object | System configuration (echoed from input) | | basis | object | Basis configuration (echoed from input) | | states | array | Array of eigenstate results |

Per-State Data:

Custom parameters can be supplied via external JSON file:

param_custom.json:

{
  "param": {
    "mn": 0.220,
    "ms": 0.419,
    "mc": 1.628,
    "mb": 4.977,
    "b": 0.18,
    "c": -0.253,
    "sigma_0": 1.8,
    "s": 1.55,
    "epsilon_cont": -0.168,
    "epsilon_sov": -0.035,
    "epsilon_sos": 0.055,
    "epsilon_tens": 0.025
  }
}

Reference to custom parameters:

{
  ...
  "model": {
    "type": "GISTRING",
    "param": "GISTRING_CUSTOM",
    "file": "param_custom.json"
  },
  ...
}

Parameter Definitions:

The GI fields above apply to GISTRING and GISCREEN. NRSTRING and NRSCREEN use a different param object. NRSTRING does not read mu.

NRSTRING / NRSCREEN parameter fields:

The radial wavefunction is expanded in Gaussian basis functions:

ψ(r) = Σ cₙ φₙ(r)

where each basis function is:

φₙ(r) = r^ℓ exp(-αₙ r²)

Advantages:

• All integrals solvable in closed form
• Exponential convergence with basis size
• Efficient matrix computations

Implementation: src/basis/orbit.c, src/math/integral.c

The GI potential combines three components:

A. Confinement Potential

V_conf(r) = b₁ · r + b₂ + const

B. Coulomb Interaction

V_coul(r) = -αₛ(r) · Cᶠ / r

C. Hyperfine Interactions

• Spin-Spin: Contact term
• Spin-Orbit: L·S coupling
• Tensor: Tensor operator

Implementation: src/model/gimodel.c (20+ potential functions)

Converts the radial Schrödinger equation into a generalized eigenvalue problem:

H c = E S c

Algorithm:

1. Generate Gaussian basis set
2. Compute overlap matrix S (analytically)
3. Compute kinetic energy matrix T (analytically)
4. Compute potential energy matrix V (numerical integration)
5. Solve generalized eigenvalue problem
6. Extract masses and wavefunctions

Implementation: src/math/eigen.c, src/model/spectra.c

The RMS radius spectrum is analyzed for anomalies using quadratic interpolation:

1. Detect anomalies: Identify non-monotonic points
2. Interpolate: Use Lagrange quadratic/linear interpolation
3. Validate: Check normalization and consistency

Implementation: src/math/interplt.c (enhanced with debugging)

A fit is a --compute run with "task": "FITTING". fit.target names both the model and the built-in dataset, for example GISCREEN_CCBAR. The state list and the parameter starts, steps, bounds, and fixed flags are in src/param/f*.c.

Fit function:

χ² = Σᵢ (M_calc^i - M_exp^i)² / σᵢ²

Masses in the tables are in MeV. Minuit2 MIGRAD minimizes χ². Each evaluation prints call N chi2 = .... The minimum is written to <project>.fit.json.

Implementation: src/param/fitting.c, src/param/minuit.cc, src/param/f*.c

The app/gemstore-assistant/ subdirectory contains an OpenCode skill for intelligent task automation.

"Calculate charmonium 1P state with J=1"
         ↓
Parse quantum numbers, select model
         ↓
Generate input file automatically
         ↓
Execute gemstore calculation
         ↓
Parse results, format output
         ↓
"ψ(J^PC) = 1^-- with M = 3.686 GeV"

• Natural Language Understanding: Parse physics requests
• Automated Workflow: Generate inputs, execute, parse outputs
• Systematic Calculations: Run multiple L, S, J combinations
• Result Interpretation: Physics-meaningful explanations
• Parameter Fitting: Build a FITTING input for a named target such as GISCREEN_CCBAR and run it with --compute

app/gemstore-assistant/
├── SKILL.md                          # Main skill definition
├── scripts/generate_meson_inputs.py  # Auto-generate input files
├── templates/meson_spectra_template.md
└── templates/baryon_spectra_template.md

# Enable AI-assisted calculations
opencode "Calculate charmonium spectrum up to L=2"

# Fit a built-in dataset
opencode "Fit GISCREEN_CCBAR on a GEM basis with nmax 20"

For details: see app/gemstore-assistant/SKILL.md

The implementation includes 22 complete potential components:

Primary Interactions:

double GIVconf(double r, ...)     // Confinement (string or screened)
double GIVcoul(double r, ...)     // Coulomb (Gaussian screened)
double GIVcont(double r, ...)     // Contact term (delta-like)

Spin-Dependent Interactions:

double GIVsovi(double r, ...)     // Spin-orbit coupling (quark 1)
double GIVsovj(double r, ...)     // Spin-orbit coupling (quark 2)
double GIVsovij(double r, ...)    // Mixed spin-orbit coupling
double GIVsosi(double r, ...)     // Thomas precession (quark 1)
double GIVsosj(double r, ...)     // Thomas precession (quark 2)
double GIVtens(double r, ...)     // Tensor force

Smearing Parameters (9 functions): Gaussian smearing regularization for all potential components.

Input file (cc_ground.json):

{
  "project": "charmonium_ground",
  "task": "SPECTRA",
  "model": {
    "type": "GISCREEN",
    "param": "GISCREEN_CCBAR"
  },
  "system": {
    "type": "MESON",
    "f1": 3,
    "f2": 3,
    "S": 0,
    "L": 0,
    "J": 0
  },
  "basis": {
    "type": "GEM",
    "nmax": 16,
    "rmax": 30.0,
    "rmin": 0.1
  },
  "print": {
    "pot": "false",
    "wfn": "false"
  }
}

Run:

./gemstore --compute cc_ground.json

Output (charmonium_ground.out.json):

{
  "generated": "2026-04-25 18:33:25",
  "project": "charmonium_ground",
  "states": [
    {
      "index": 1,
      "mass": 3.096788,
      "rms_radius": 0.524365,
      "eigenvector": [0.43147..., 0.56587..., ...]
    },
    ...
  ]
}

Parameter file (my_params.json):

{
  "param": {
    "mn": 0.220,
    "ms": 0.419,
    "mc": 1.747603574365,
    "mb": 5.095838715,
    "b": 0.248247135518,
    "mu": 0.1333931469096,
    "c": -0.5334999044266,
    "sigma_0": 1.56552865791,
    "s": 1.285723132711,
    "epsilon_cont": -0.2864647624566,
    "epsilon_sov": -0.349573212139,
    "epsilon_sos": 0.7905135472165,
    "epsilon_tens": -0.487322874302
  }
}

Input file (cc_custom.json):

{
  "project": "charmonium_custom",
  "task": "SPECTRA",
  "model": {
    "type": "GISCREEN",
    "param": "GISCREEN_CUSTOM",
    "file": "my_params.json"
  },
  "system": {
    "type": "MESON",
    "f1": 3,
    "f2": 3,
    "S": 1,
    "L": 1,
    "J": 1
  },
  "basis": {
    "type": "GEM",
    "nmax": 16,
    "rmax": 30.0,
    "rmin": 0.1
  },
  "print": {
    "pot": "false",
    "wfn": "false"
  }
}

Run:

./gemstore --compute cc_custom.json

model gives the type only. system gives the type only. fit.target selects the dataset. These targets are meson fits, so system.type is MESON and model.type matches the model in the target name. Basis is GEM or SHO. The basis below is the one used with these datasets.

Input file (fit_ccbar.json):

{
  "project": "fit_ccbar",
  "task": "FITTING",
  "model": { "type": "GISCREEN" },
  "system": { "type": "MESON" },
  "basis": { "type": "GEM", "nmax": 20, "rmax": 30.0, "rmin": 0.1 },
  "print": { "pot": "false", "wfn": "false" },
  "fit": { "target": "GISCREEN_CCBAR" }
}

Targets: GISCREEN_MESON, GISCREEN_BBBAR, GISCREEN_BCBAR, GISCREEN_BSBAR, GISCREEN_CCBAR, GISCREEN_CSBAR.

Run:

./gemstore --compute fit_ccbar.json

The terminal prints one call N chi2 = ... line per evaluation, then the parameter table, chi2, valid, and edm. Results go to fit_ccbar.fit.json. A worked input is test/FittingTask/giscreen_csbar.json.

For light mesons (pions, kaons), GI-String model works better:

{
  "project": "light_mesons",
  "task": "SPECTRA",
  "model": {
    "type": "GISTRING",
    "param": "GISTRING_MESON"
  },
  "system": {
    "type": "MESON",
    "f1": 1,
    "f2": 1,
    "S": 0,
    "L": 0,
    "J": 0
  },
  "basis": {
    "type": "GEM",
    "nmax": 16,
    "rmax": 30.0,
    "rmin": 0.1
  }
}

Generated by write_meson_spectra() function in src/print.c:

When you run:

./gemstore --compute myfile.json

GEMSTORE automatically generates myfile.out.json with complete results in JSON format.

Output File Structure:

{
  "generated": "2026-04-25 18:33:25",
  "project": "myproject",
  "task": "SPECTRA",
  "model": {
    "type": "GISCREEN",
    "param": "GISCREEN_CCBAR"
  },
  "system": {
    "type": "MESON",
    "f1": 3,
    "f2": 3,
    "S": 1,
    "L": 0,
    "J": 1
  },
  "basis": {
    "type": "GEM",
    "nmax": 16,
    "rmax": 30,
    "rmin": 0.1
  },
  "states": [
    {
      "index": 1,
      "mass": 3.101986299943893,
      "rms_radius": 0.324597538486162,
      "eigenvector": [0.43147459135290689, 0.56587312869939621, 0.56203519231094468, ...]
    },
    {
      "index": 2,
      "mass": 3.6707285768604248,
      "rms_radius": 0.53640308338098519,
      "eigenvector": [-0.31500074209555717, -0.28193707412502728, 0.0019418306107957378, ...]
    },
    ...
  ]
}

Output Field Definitions:

Per-State Fields:

Example Files in test/:

• test/amethyst.out.json - Sample output with 16 states (GEM basis)
• test/diamond.out.json - Sample output with predefined parameters

Output Generation Details:

The write_meson_spectra() function (src/print.c:234-379):

1. Echoes all input configuration for reproducibility
2. Records generation timestamp
3. Outputs all eigenvalues as masses
4. Computes and outputs RMS radii
5. Includes normalized eigenvectors (expansion coefficients)
6. Writes to <project>.out.json in the current directory

This ensures all calculations are fully reproducible and can be analyzed with standard JSON tools or parsed by other applications.

gemstore/
├── README.md                      # This file
├── LICENSE                        # GPLv3 license
├── Makefile                       # Build configuration
├── gemstore                       # Compiled executable
│
├── include/gemstore/              # Public API headers
│   ├── basis/                     # Wavefunction basis
│   ├── math/                      # Mathematics library
│   ├── model/                     # Physics models
│   ├── param/                     # Input parameters
│   └── entry.h, print.h           # Main interface
│
├── src/                           # Implementation (~5,000 LOC)
│   ├── main.c                     # Entry point
│   ├── entry.c                    # Task routing
│   ├── print.c                    # Output formatting (enhanced)
│   ├── basis/                     # Basis functions (~800 LOC)
│   ├── math/                      # Mathematics (~1200 LOC)
│   ├── model/                     # Physics models (~1800 LOC)
│   └── param/                     # Parameter fitting
│
├── lib/                           # External libraries
│   └── Minuit2/                   # Numerical optimization (CERN)
│
├── app/                           # AI Assistant for GEMSTORE
│   └── gemstore-assistant/        # OpenCode integration
│       ├── SKILL.md               # Skill definition
│       ├── scripts/               # Helper scripts
│       └── templates/             # Spectra and fitting templates
│
├── test/                          # Test cases & examples
│   ├── amethyst.json              # Example: GEM basis
│   ├── diamond.json               # Example: predefined params
│   ├── amethyst.out.json          # Sample output
│   ├── param_GISCREEN.json        # GI-Screen parameters
│   ├── param_GISTRING.json        # GI-String parameters
│   ├── FittingTask/               # FITTING input example
│   ├── ScreenFitting-*/           # Stored fit logs
│   └── Spectra-Baryon/            # Baryon GI-String examples

Total LOC: ~7,800 (C + C++ + Headers)

# Install LAPACK/OpenBLAS (Ubuntu/Debian)
sudo apt-get install liblapacke-dev libopenblas-dev

# Build with LAPACKE support
make clean && make USE_LAPACKE=1

1. Code Style: K&R style with 4-space indentation
2. Documentation: Add docstrings for all public functions
3. Testing: Include unit tests for new algorithms
4. Physics: Cite literature for new models
5. Performance: Profile before optimizing

# Create feature branch
git checkout -b feature/my-algorithm

# Make changes and test
make clean && make

# Commit with descriptive messages
git add -A
git commit -m "Add [feature]: description"

# Push and open pull request
git push origin feature/my-algorithm

If you use GEMSTORE in research, please cite:

@software{gemstore2026,
  author = {Zhang, Wen-Xuan},
  title = {GEMSTORE: Hadron Spectroscopy Simulation Tools},
  year = {2026},
  url = {https://github.com/serialcore/gemstore},
  version = {0.1.4},
  note = {Gaussian Expanding Method + Godfrey-Isgur Quark Models}
}

1. Godfrey, S., & Isgur, N. (1985). "Mesons in a quark model with chromomagnetic interactions." Physical Review D, 32(1), 189.

2. Bhatnagar, V., et al. (1995). "Towards a consistent quark model for baryons." International Journal of Modern Physics A, 10(03), 335-392.

3. Fulton, R., et al. (1990). "Gaussian wave packets in the Hilbert space formalism." Physical Review D.

GEMSTORE is licensed under the GNU General Public License v3.0 or later (GPLv3+).

• SPDX Identifier: GPL-3.0-or-later
• Full License: See LICENSE file
• Copyright: © 2026 Wen-Xuan Zhang

You are free to:

• ✓ Use for any purpose
• ✓ Modify and redistribute
• ✓ Include in research and commercial products

With the requirement that:

• ⚠ Derivative works must also be licensed under GPLv3+
• ⚠ Source code must be provided
• ⚠ License and copyright notice must be preserved

• Author: Wen-Xuan Zhang (@serialcore)
• Email: serialcore@outlook.com
• Issues: GitHub Issues tracker
• AI Assistant: See app/gemstore-assistant/SKILL.md

███████████████████████████████████████
████  GEMSTORE v0.1.4                ████
████  Hadron Spectroscopy Tools      ████
███████████████████████████████████████