A C program for hadron spectra, S-wave scattering lengths, meson parameter fits, and
GEMSTORE solves quark-model meson and baryon spectra with the Gaussian expansion method (GEM), MIT bag masses from mesons through hexaquarks, those bags in symmetric nuclear matter, and two- and three-body hadronic molecules. A separate task fits built-in Godfrey–Isgur meson datasets with Minuit2. Two further tasks, outside the GEM eigenvalue problem, return an S-wave scattering length and a single-oscillator
Strings in the JSON input are case-sensitive. Masses in spectrum files are in GeV. Lengths printed as fm are femtometres.
- What this version computes
- Requirements and build
- How to run
- Input file
- Parameter files
- Output
- Solvers
- Test suite
- Source layout
- Optional agent skill
- License and citation
| Task | System | Model | Basis | Result |
|---|---|---|---|---|
SPECTRA |
MESON |
GISCREEN, GISTRING, NRSTRING, NRSCREEN
|
GEM or SHO
|
Masses, RMS radii, eigenvectors |
SPECTRA |
BARYON |
GISCREEN, GISTRING
|
GEM |
Masses, three pair radii, eigenvectors |
SPECTRA |
BAG |
BAGMIT, QMCSTAD, QMCMOD
|
NONE or CMI
|
Bag masses, radius, color–spin mixing; QMC also writes the nuclear-matter fields |
SPECTRA |
MOLECUL2 |
OBESTAT, YUKAWA, EFTCONT, HALQCD
|
GEM |
Two-body mass, binding, RMS |
SPECTRA |
MOLECUL3 |
HYBRID of three pair models |
GEM |
Three-body mass, binding, pair RMS |
FITTING |
chosen by fit.target
|
pinned GISCREEN set |
GEM or SHO
|
Minuit2 |
SCATTER |
MOLECUL2 |
OBESTAT, YUKAWA, EFTCONT, HALQCD
|
none | S-wave scattering length and effective range |
3P0DECAY |
MESON |
QPC3P0 |
none | Partial width of one parent into two daughters |
NRSTRING and NRSCREEN are non-relativistic Cornell Hamiltonians. They check the meson radial solver. Baryon spectra in this version are Godfrey–Isgur only. SHO is accepted for mesons and for meson fits. Bag and molecular spectra use the bases in the table.
The following problems are outside this version: non-relativistic baryon spectra, coupled channels, folded potentials,
- Linux or another Unix with GNU make
- GCC or Clang with C99 and a matching C++ compiler (
gccandg++in the Makefile) - CMake, used only to build the bundled Minuit2
- POSIX threads and
libm
Clone with the Minuit2 submodule and build:
git clone --recursive https://github.com/serialcore/gemstore.git
cd gemstore
make
./gemstore --help
./gemstore --versionIf lib/Minuit2 is empty, run git submodule update --init --recursive and then make again. make install copies the binary to ~/.local/bin. make uninstall removes that copy. make clean deletes obj/, the binary, and the Minuit2 build directory.
The executable links libm, libpthread, and the static Minuit2 libraries. It does not link LAPACK or OpenBLAS. Python is not required to run the program. The helper app/gemstore-assistant/scripts/generate_meson_inputs.py needs Python 3.
gemstore [--compute FILE] [--debug UNIT]
gemstore --help
gemstore --version
--compute reads one JSON file and dispatches on task. Output is written in the process working directory, under the project name. A relative model.file is opened from that directory, so run the program from the directory that holds the parameter files:
./gemstore --compute test/Spectra-Quarkonium/charmonium_1S0.json
cd test/Spectra-Molecule2
../../gemstore --compute dstar_xi_I0.json--debug runs an internal check. The unit names are su3_product, soc_operator, casimir_operator, color_wfn, spin_wfn, isospin_wfn, orbit_wfn, eigen_system, and eigen_system_complex.
Every file has a string project and a string task. The other objects depend on the task.
| Task | Required objects | Omit |
|---|---|---|
SPECTRA |
model, system, basis, print |
fit |
FITTING |
basis, fit |
model, system, print |
SCATTER |
model, system |
basis, print, fit |
3P0DECAY |
model, system |
basis, print, fit |
print.pot and print.wfn are the strings "true" or "false". Any other string turns that dump off. SPECTRA still requires the print object.
Flavors are 1 = 2 = 3 = 4 =
{
"project": "charmonium_1S0",
"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": 20, "rmax": 30.0, "rmin": 0.1 },
"print": { "pot": "false", "wfn": "false" }
}S, L, and J are the spin, orbital angular momentum, and total angular momentum of the test/Spectra-Quarkonium/, test/Spectra-SHO/, test/Spectra-NRmodel/, test/Spectra-CustomParameter/.
"system": {
"type": "BARYON",
"f1": 1, "f2": 1, "f3": 3,
"J": 0.5, "P": 1, "sym12": -1, "Lmax": 0
}P is sym12 is the flavor symmetry of quarks 1 and 2. The exchange phase is sym12 times Lmax keeps channels with jl. The basis is every GISTRING_BARYON for the smeared linear set. GISTRING_MESON is a different fit. Inputs: test/Spectra-Baryon/.
nn, ns, nc, and nb are the flavor counts. For CMI, f1–f6 give the quark order and must match those counts. NONE does not need f1–f6.
"system": { "type": "BAG", "nn": 2, "ns": 0, "nc": 2, "nb": 0,
"f1": 3, "f2": 3, "f3": 1, "f4": 1 },
"basis": {
"type": "CMI",
"color": ["tetra11", "tetra88"],
"spin": [ {"s12": 1, "s34": 1, "st": 2, "st3": 2} ]
}Color names: meson, baryon, tetra11, tetra33, tetra66, tetra88, penta688, penta388, penta11, hexa1010, hexa6868, hexa6838, hexa3868, hexa3838, hexa11. A basis has 1–8 colors and 1–20 spin channels. Unused couplings in a spin object stay 0. Channels with different total spin st are diagonalized separately. For five and six quarks the program keeps the Pauli-allowed color$\otimes$spin products. Inputs: test/Spectra-Bag/.
QMCSTAD and QMCMOD use the same BAG system and add rho_b (fm$^{-3}$) and temp (GeV). Both are required and must be BAGMIT does not read them. Inputs: test/Spectra-QMC/.
"model": { "type": "OBESTAT", "param": "OBESTAT_CUSTOM", "file": "param_OBESTAT_dstarxi.json" },
"system": {
"type": "MOLECUL2",
"type1": "VECTOR", "type2": "DIRAC",
"m1": 2.010, "m2": 1.318,
"t1": 0.5, "t2": 0.5, "I": 0,
"S": 0.5, "L": 0, "J": 0.5
},
"basis": { "type": "GEM", "nmax": 20, "rmax": 30.0, "rmin": 0.1 }type1 and type2 are DIRAC (spin-1/2 baryon), VECTOR (PSEUDOSCALAR (elastic m1 and m2 are the physical masses in GeV. t1, t2, and the total isospin I are required. Two identical t1 and t2 to 0.
L is the lowest partial wave. Tensor mixing of S and D, together with every total spin that couples to J, sets the channel list. The JSON value of S does not choose that list. For example,
The same system block is used with YUKAWA, EFTCONT, and HALQCD. Those models do not read the OBE factors cc and eta. YUKAWA_MT13 has no parameter file. For the Malfliet–Tjon samples, the nucleon mass is 0.938942 GeV so that
SCATTER uses this system with L equal to 0 and with no basis or print. S and J select the partial wave.
model.type is HYBRID. model1, model2, and model3 are the pair interactions on legs 12, 13, and 23. Each pair is OBESTAT, YUKAWA, EFTCONT, or HALQCD, with the same param keys as the two-body model.
"system": {
"type": "MOLECUL3",
"type1": "PSEUDOSCALAR", "type2": "PSEUDOSCALAR", "type3": "VECTOR",
"m1": 1.867, "m2": 0.494, "m3": 0.892,
"t1": 0.5, "t2": 0.5, "t3": 0.5,
"J": 1.0, "P": -1, "I": 0.5, "Lmax": 2
}Intrinsic parity is I is the total isospin. Pair isospin is recoupled to I. Identical legs follow from equal type and mass. DIRAC is a fermion; VECTOR and PSEUDOSCALAR are bosons. An identical sym12 is not read for this filter.
nmax is the number of Gaussian widths on each Jacobi axis. The dimension is
basis.type |
Fields | Where |
|---|---|---|
GEM |
nmax, rmin, rmax (fm) |
Meson, baryon, molecule, meson fit |
SHO |
nmax, beta (GeV) |
Meson spectrum and meson fit |
CMI |
color, spin |
Bag |
NONE |
none | Bag energy without color–magnetic mixing |
GEM functions are rmin to rmax. A single-beta SHO basis does not grow with excitation the way that GEM ladder does. Near-threshold molecular states with RMS close to rmax are box states of that basis.
{
"project": "fit_csbar",
"task": "FITTING",
"fit": { "target": "GISCREEN_CSBAR" },
"basis": { "type": "GEM", "nmax": 20, "rmax": 30.0, "rmin": 0.1 }
}fit.target is one of GISCREEN_MESON, GISCREEN_BBBAR, GISCREEN_BCBAR, GISCREEN_BSBAR, GISCREEN_CCBAR, GISCREEN_CSBAR. The target selects the model and the experimental list. Starting values, steps, bounds, and which parameters are fixed live in src/param/f*.c.
{
"project": "rho_pipi",
"task": "3P0DECAY",
"model": { "type": "QPC3P0", "param": "QPC3P0_CUSTOM", "file": "param_qpc3p0_rho.json" },
"system": {
"type": "MESON",
"F": 1, "fl1": 0.7071067811865476, "fl2": -0.7071067811865476,
"initial": { "f1": 1, "f2": 1, "n": 1, "S": 1, "L": 0, "J": 1, "mass": 0.77, "beta": 0.397 },
"final": [
{ "f1": 1, "f2": 1, "n": 1, "S": 0, "L": 0, "J": 0, "mass": 0.138, "beta": 0.397 },
{ "f1": 1, "f2": 1, "n": 1, "S": 0, "L": 0, "J": 0, "mass": 0.138, "beta": 0.397 }
]
}
}Each meson is one SHO. n starts at 1 and is the radial quantum number of that oscillator, not a GEM index. beta is the SHO scale in GeV. mass is the hadron mass in GeV. fl1 and fl2 are the signed flavor weights of the two quark-line diagrams. F multiplies the width and counts charge states that share the same model.file is required. Run from the directory that contains that file. Inputs: test/Decay-3P0/.
A preset named *_CUSTOM needs model.file. The file is a JSON object with one param object. Built-in presets that need no file are the GISCREEN_* and GISTRING_* names other than *_CUSTOM, NRSTRING_MESON, NRSCREEN_MESON, BAGMIT_DEFAULT, QMCSTAD_DEFAULT, and YUKAWA_MT13.
Godfrey–Isgur (GISTRING_CUSTOM, GISCREEN_CUSTOM), all required except mu:
| Field | Meaning |
|---|---|
mn, ms, mc, mb |
Quark masses (GeV) |
b, c |
String tension and constant |
mu |
Screening mass. Missing means 0. Used by the screened set |
sigma_0, s |
Gaussian smearing |
epsilon_cont, epsilon_sov, epsilon_sos, epsilon_tens |
Contact, spin–orbit, Thomas, and tensor strengths |
Cornell (NRSTRING_CUSTOM, NRSCREEN_CUSTOM): mn, ms, mc, mb, b, c, alpha_s, sigma. NRSCREEN also requires mu (GeV). NRSTRING ignores mu and keeps a linear confinement.
MIT bag (BAGMIT_CUSTOM): mn, ms, mc, mb (GeV; the built-in B (GeV$^4$), Z, and the pair bindings Bcs, Bbs, Bcc, Bbc, Bbb (GeV).
Standard QMC (QMCSTAD_CUSTOM): the vacuum masses, B, Z, m_sigma, m_omega, m_rho, g_sigma, g_omega, g_rho. lambda3 is optional and defaults to 0. A file that contains g_sigma_B or delta is rejected. QMCSTAD_DEFAULT copies the vacuum bag,
Modified QMC (QMCMOD_CUSTOM): the QMCSTAD fields plus g_sigma_B delta QMCMOD cannot use QMCSTAD_DEFAULT.
Static OBE (OBESTAT_CUSTOM). Legs, masses, and I stay in the system file.
| Field | Meaning |
|---|---|
lambda |
Common monopole cutoff (GeV) |
tensor_mass1, tensor_mass2
|
Mass |
g_pi1, g_pi2
|
Pion couplings. The vertex conversion is internal |
g_sigma1, g_sigma2
|
Scalar couplings |
g_rho1, g_rho2, f_rho1, f_rho2
|
Vector |
g_omega1, g_omega2, f_omega1, f_omega2
|
The same for |
cc1, cc2
|
Meson charge conjugation. Write 0 when unused. A nonzero value on a meson leg flips cc is ignored |
eta |
Meson–meson C-parity. Write |
Yukawa (YUKAWA_CUSTOM): param.terms, an array of { "V", "mu", "wigner", "bartlett" }. V is in MeV·fm and mu in fm$^{-1}$. wigner defaults to 1 and bartlett to 0. YUKAWA_MT13 is the Malfliet–Tjon I/III potential and takes no file.
EFT contact (EFTCONT_CUSTOM): Ca (MeV) and Rc (fm),
The Gaussian that replaces
HAL QCD (HALQCD_CUSTOM): param.V0, param.Vsig, and param.VT. Each present key is an array of { "r", "V" } with r in fm and V in MeV. r is non-negative and strictly increasing, at most 256 points. A missing array is zero, and at least one array is required. The kernel interpolates linearly. "0", "1", "0.5", or "1.5". Each recoupled
QPC3P0_CUSTOM): gamma, mq1, mq2, mq3, all masses in GeV and positive. mq1 is the parent quark, mq2 the parent antiquark, and mq3 the created quark.
All result files are written in the working directory.
| File | Task | Contents |
|---|---|---|
<project>.state.json |
SPECTRA |
states, and the extra root fields listed below |
<project>.fit.json |
FITTING |
chi2, valid, edm, parameters, and per-state masses in MeV |
<project>.scatter.json |
SCATTER |
mu (GeV), a0 (fm), r0 (fm) |
<project>.decay.json |
3P0DECAY |
open, p, EB, EC (GeV), width (MeV), and waves with L, S, M
|
<project>.pot.dat |
SPECTRA with print.pot
|
Radial potential. Bag and QMC runs do not write it |
<project>.wfn.N.dat |
SPECTRA with print.wfn
|
State |
<project>.basis.dat |
baryon or three-body SPECTRA with print.wfn
|
Quantum numbers of each basis function |
A spectrum file does not copy the input back. Meson and two-body states have index, mass (GeV), rms_radius (fm), and eigenvector. The meson vector has length nmax. The two-body vector has length mass, rms_r12, rms_r13, rms_r23, and eigenvector. Three-body files add a root field threshold (GeV) and, on each state, ebind together with the three pair radii and the eigenvector. A fresh three-body file includes that eigenvector. Some copies under test/Spectra-Molecule3/ omit it, because the full vector makes the file tens to hundreds of megabytes.
Bag files may carry a root string configuration. Each state has st, mass, variational R (GeV$^{-1}$), an array x of four frequencies, and an eigenvector of objects {color, s12, s34, s123, s45, s456, st, st3, c}. NONE stores {c} only. A QMC file adds, on the root, sigma, omega, B, mn_star, m_free, m_nucleon, R_nucleon, rho_s, mu, eps, press, and ebind. ebind is m_nucleon is the three-light-quark source. It equals a spectrum mass only for an nnn bag with basis NONE.
Potential columns, from 0.01 fm to 10 fm:
- Meson:
r,V - Static OBE, Yukawa, and EFT:
r,Vc,Vss,Vt,V - HAL QCD:
r,V0,Vsig,VT, and$V(^1S_0)=V_0-3V_\sigma$ , in GeV
A meson .wfn.N.dat runs from 0.01 fm to r, rmax, so that upper limit stays 10 fm. A two-body molecule file uses the same grid and writes one radial column for each partial wave. A baryon or three-body .wfn.N.dat is the list of expansion coefficients, one line per basis function, and <project>.basis.dat names those functions. The baryon and three-body terminal tables print the first 20 states and leave the rest in .state.json.
The fit terminal prints call N chi2 = ... on every evaluation, then chi2, valid, and edm. The scatter terminal repeats mu, a0, and r0. Below a decay threshold, open is 0 and width is 0.
GISCREEN and GISTRING are the Godfrey–Isgur Hamiltonian: relativistic kinematics, linear or screened confinement, a running Coulomb term, and smeared contact, spin–orbit, and tensor interactions. NRSTRING and NRSCREEN replace that with a non-relativistic Cornell potential and a constant
The radial problem is the generalized eigenproblem src/math/eigen.c.
A baryon uses three Jacobi charts and the same GI operator on each pair. Three identical quarks are reduced to one chart. That reduction is not a full
At a cavity radius
CMI,
The color and spin factor matrices are built once. st block. NONE varies
QMCSTAD and QMCMOD call the same bag routine after a mean-field solve. The source is always a color-free bag of three light quarks, not the spectrum requested in the input. Only those quarks couple to
QMCSTAD keeps QMCMOD uses the free source mass
A root with g_rho does not shift the spectrum. Temperature enters only the nucleon Fermi–Dirac sea, with degeneracy 4. It does not heat the cavity. Net density uses
The spectrum is then the bag at
The two-body static one-boson-exchange Hamiltonian is
with rmax.
A Yukawa term is
The three-body Hamiltonian is
A fit minimizes
with Minuit2 MIGRAD. The masses in the datasets and in <project>.fit.json are in MeV. Each
SCATTER integrates the
for ten momenta from 0.05 to 0.50 MeV.
The decay width is
Momenta and energies are in GeV. The factor 1000 converts beta and n given in the input. A GEM eigenvector is not summed into
Each directory is a complete input, and the matching result file is already in the tree. Run --compute from a directory whose relative model.file names resolve.
| Directory | What it checks |
|---|---|
test/Spectra-Quarkonium/ |
Built-in GISCREEN_CCBAR and GISCREEN_BBBAR
|
test/Spectra-CustomParameter/ |
GISCREEN_CUSTOM and GISTRING_CUSTOM
|
test/Spectra-SHO/ |
Meson SHO basis |
test/Spectra-NRmodel/ |
Cornell GEM and SHO |
test/Spectra-PrintPotWfn/ |
Meson .pot.dat and .wfn.N.dat (diamond.json) |
test/Spectra-Baryon/ |
GI baryons on GEM |
test/Spectra-Bag/ |
MIT bag, NONE and CMI, through hexaquarks |
test/Spectra-QMC/ |
QMCSTAD and QMCMOD, including a warm run and a CMI nucleon |
test/Spectra-Molecule2/ |
Two-body static OBE |
test/Spectra-Molecule3/ |
Three-body HYBRID
|
test/Spectra-Yukawa/ |
Malfliet–Tjon deuteron and triton |
test/Spectra-EFT/ |
Yuan–Liu contact, two- and three-body |
test/Spectra-HALQCD/ |
Table reader, including an isospin-keyed three-body file |
test/ScatterTask/ |
S-wave effective range |
test/Decay-3P0/ |
|
test/FittingTask/ |
GISCREEN_CSBAR input. The ScreenFitting-* logs are earlier fit records |
Shipped checks, in program units:
-
test/Decay-3P0/rho_pipi.decay.jsonrecords a width of 79.429 MeV. -
test/ScatterTask/dd_scatter.scatter.jsonrecords$a_0=-0.250006$ fm.lclc_scatter.scatter.jsonrecords$a_0=-0.210000$ fm. -
test/Spectra-Yukawa/nn_yukawa.state.jsonis the MT-I/III deuteron, binding about$-2.231$ MeV. -
test/Spectra-QMC/nucleon_qmc.jsonisQMCSTAD_DEFAULTat$0.16,\mathrm{fm}^{-3}$ and$T=0$ . With every medium coupling equal to 0,$\sigma=0$ and$E/A$ is the Fermi kinetic energy of the free bag.
The HAL QCD sample param_HAL_V0.json stores the same Gaussian as the
gemstore/
├── Makefile
├── include/gemstore/ public headers
├── src/ parse.c, write.c, print.c, entry.c
│ ├── basis/ GEM, SHO, color, spin, CMI
│ ├── math/ quadrature, matrices, eigenproblems
│ ├── model/ spectra, QMC, OBE, Yukawa, EFT, HAL QCD, scatter, 3P0
│ └── param/ built-in parameters, fit datasets, Minuit2 glue
├── lib/Minuit2/ CERN Minuit2, LGPL-2.1
├── app/gemstore-assistant/
└── test/
src/parse.c reads the run file. src/param/argset.c loads the coefficient set. src/model/compute.c dispatches the task. src/write.c writes the JSON and text dumps. src/print.c writes the terminal tables.
app/gemstore-assistant/ is an optional agent skill: SKILL.md, JSON templates, and scripts/generate_meson_inputs.py. It prepares a parser file, runs gemstore --compute, and reads the result JSON. The solver does not call it, and a calculation does not need an agent. The skill text is distributed under the MIT license. The program itself remains under GPL-3.0-or-later.
GEMSTORE is free software under the GNU General Public License, version 3 or any later version. See LICENSE. Copyright © 2026 Wen-Xuan Zhang. The bundled Minuit2 library is under the GNU Lesser General Public License, version 2.1. See lib/Minuit2/LICENSE.
The Computer Physics Communications citation will replace this software record once a DOI is assigned:
@software{gemstore2026,
author = {Zhang, Wen-Xuan},
title = {GEMSTORE: Hadron Spectroscopy Simulation Tools},
year = {2026},
url = {https://github.com/serialcore/gemstore},
license = {GPL-3.0-or-later}
}Author: Wen-Xuan Zhang, [email protected].
