GIP-DB: Unified Repository for GPD Phenomenology

• GIP-DB is an open, YAML-based repository designed to store and access generalized parton distribution data from experimental and lattice-QCD analyses.
• It streamlines data ingestion, enhances reproducibility, and supports benchmarking with a unified schema and multi-language Python and C++ interfaces.
• The database effectively manages complex uncertainty propagation using replica arrays and integrated correlation matrices for reliable GPD phenomenology.

Searching arXiv for the specified paper to ground the article in the source text. GIP-DB is an open database proposed for the exploration of generalized parton distributions (GPDs), designed as a lightweight repository for GPD phenomenology that stores both experimental and lattice-QCD data in a common YAML-based format and exposes them through Python and C++ interfaces (Burkert et al., 23 Mar 2025). Its rationale follows from the structure of GPDs themselves: they are 3-variable objects, $F(x,\xi,t)$, combining features of PDFs and form factors, and their empirical or numerical constraint requires multiple processes such as DVCS, DVMP, and TCS, different beam and target polarizations, and fine binning in $(x_B,Q^2,t)$. Within that setting, GIP-DB is intended to reduce repeated data-ingest effort across phenomenology groups, improve reproducibility and open-science practices, and support benchmarking of GPD-related developments such as GPD models.

1. Motivation and design objectives

The database is motivated by a recurring workflow problem in GPD analyses: up to now each phenomenology group re-coded data ingest from scratch. The proposed remedy is a common, version-controlled repository that, in the source description, saves months of boilerplate, improves reproducibility and open-science, and eases benchmarking of new GPD models (Burkert et al., 23 Mar 2025).

Its design goals are explicitly lightweight, extensible, self-documenting, and multi-language. “Lightweight” means text files in YAML, with total size below 10 MB and no heavy SQL server required. “Extensible” means that the same format is used for experimental and lattice-QCD “final” results. “Self-documenting” refers to human-readable keys, built-in type checking, and GitHub+Jekyll hosting/documentation. “Multi-language” denotes a single Python library accompanied by a thin C++ wrapper.

A common misconception about centralized scientific databases is that they necessarily impose a heavy backend or a rigid separation between data classes. In GIP-DB, the design is the opposite on both counts: storage is plain-text YAML, and experiment and lattice-QCD content are represented within the same schema. This suggests that the project is aimed at lowering integration friction rather than introducing an additional infrastructure layer.

2. Repository structure and YAML data model

All data files live under a single GitHub repository. Each YAML file contains up to four top-level sections: uuid, general_info, data, and an optional correlation block (Burkert et al., 23 Mar 2025).

Top-level section	Required	Role
uuid	Yes	Short unique identifier
general_info	Yes	Metadata and conditions
data	Yes	One or more data_set blocks
correlation	No	Named correlation matrices

Within each data_set, two objects are central: kinematics and observable. The label field provides a unique short tag such as "Q2_dep". The kinematics block stores names of independent variables, their units, central values, optional bin definitions, and optional replica-by-replica values. The observable block stores measured quantities, their units, central values, uncertainties, and optional replicas. The minimal schema shown in the source uses examples such as name: [xB, Q2] and name: [ALU, [ALL](https://www.emergentmind.com/topics/cascading-annealed-language-learning-all)], with nested lists for values and replicas.

A notable feature is the separation of schema vocabulary from data instances. All enums, including data_type, name, unit, and particle, are defined in separate YAML “vocabulary” files. The stated purpose is to prevent typos and ensure consistent unit handling. Optional bin: entries store integration intervals, for example [[0.11,0.25],[1,2]], while correlated uncertainties can refer to a named matrix defined in the correlation section.

The resulting model is deliberately minimal but not sparse. It includes the information needed for modern analyses, including replica values, while preserving human readability. A plausible implication is that the format is intended to serve simultaneously as archival representation and as direct input to phenomenological code.

3. Unified treatment of experimental and lattice-QCD results

The coexistence of experimental and lattice-QCD content is implemented through the data_type enum and the required fields in general_info.conditions (Burkert et al., 23 Mar 2025). For experimental entries, examples of data_type include DVCS, TCS, and DVMP; required conditions include lepton_beam_type, lepton_beam_energy, hadron_beam_type, and hadron_beam_energy. The associated observables include cross sections, beam-spin asymmetries $A_{\rm LU}$, and target asymmetries.

For lattice-QCD entries, data_type is LATTICE_QCD, and the required conditions are hadron_type, pion_mass, and lattice_spacing. The observables may be moments or direct $x$-dependent GPD estimates via quasi- or pseudo-PDF methods. The source emphasizes that these entries use extensive replica arrays from gauge ensembles to propagate uncertainty.

The same data model is also used to encode specific GPD quantities. The source gives an explicit lattice-QCD example for the GPD $H(x,\xi,t)$ with collaboration "HadStruc" and reference "JHEP08(2024)162", where the observable H is stored at fixed $\xi=0$ and $t=-0.1\;\mathrm{GeV}^2$. On the experimental side, a DVCS beam-spin asymmetry example is given for the "CLAS" collaboration with fixed-target beam conditions and a phi_dep dataset containing ALU as a function of $\phi$ in degrees.

This unified representation addresses another common assumption in exclusive-process data management: that experiment-specific observables and lattice-derived GPD quantities require unrelated schemas. In GIP-DB, the distinction is semantic and metadata-driven rather than structural.

4. Replicas, uncertainties, and correlations

Uncertainty representation is a core part of the format rather than an auxiliary annotation. Replica arrays are stored as nested lists, with one sub-list per variable or observable and as many entries as replicas (Burkert et al., 23 Mar 2025). This applies both to kinematics and to observables, allowing analyses to work either with central values or with ensemble-level information.

Systematic and normalization uncertainties can be symmetric, asymmetric, or correlated. Correlated uncertainties are referenced through the optional correlation section, which defines named correlation matrices. In the minimal example, a systematic uncertainty entry may contain a string such as "corr_matrix1" together with numerical values, and the corresponding matrix is declared separately.

The metadata also include a pseudodata flag, which distinguishes Monte Carlo or pseudo-data from non-pseudodata entries. This is important for benchmarking workflows, because it makes the status of a dataset explicit within the same machine-readable representation.

For lattice-QCD content, the use of extensive replica arrays is specifically associated with uncertainty propagation from gauge ensembles. For phenomenological fits, the same machinery enables direct construction of central values and standard deviations from stored replicas. The source illustrates this by computing means and standard deviations from replica ensembles in Python.

5. Software interfaces and analysis workflow

GIP-DB provides a Python API through the package gpddatabase and a C++ API implemented as a thin wrapper around the same Python functions via Python.h (Burkert et al., 23 Mar 2025). In Python, the principal entry point is ExclusiveDatabase(), which exposes methods such as .get_uuids() and .get_data_object(uuid). The returned DataObject exposes get_general_info() and data accessors; DataSet and DataPoint then provide methods to retrieve labels, data-point counts, kinematics, observables, and replicas.

The C++ interface mirrors this structure in the namespace gpddb. The source describes ExclusiveDatabase db;, db.getUuids(), db.getDataObject(uuid), and analogous DataObject, DataSet, and DataPoint methods returning STL vectors. Typical build integration is expressed through CMake with find_package(gpddatabase REQUIRED) and linking against gpddatabase::gpddatabase.

The sample workflow in the source is a toy DVCS-asymmetry analysis. It consists of loading all beam-spin asymmetry data, filtering the resulting collection by $Q^2>2.0\,\mathrm{GeV}^2$, computing the average asymmetry and a $1$-$(x_B,Q^2,t)$0 band from replica ensembles, and plotting $(x_B,Q^2,t)$1 versus $(x_B,Q^2,t)$2. The same data can then be fed into a model fit by passing arrays of $(x_B,Q^2,t)$3 to a fitting routine such as MINUIT or TensorFlow in order to constrain the Compton form factors $(x_B,Q^2,t)$4 and $(x_B,Q^2,t)$5.

This workflow is significant because it treats the database as executable infrastructure rather than static curation. Data retrieval, uncertainty propagation, visualization, and fitting are all represented as contiguous operations on a shared data model.

6. Performance characteristics, infrastructure, and scope

The infrastructure is intentionally lean. Hosting and documentation are based on GitHub+Jekyll, and the entire YAML library is downloaded on first install with an approximate size of 5 MB (Burkert et al., 23 Mar 2025). Lookup complexity in Python and C++ is stated as $(x_B,Q^2,t)$6 per UUID. Replica arrays are kept in memory as NumPy arrays in Python or as std::vector<double> in C++, and operations on roughly $(x_B,Q^2,t)$7 replicas are reported to remain sub-second.

The source also notes a possible future expansion: adoption of an LHAPDF-style on-demand downloader to keep local footprint minimal. Because this is framed as a future possibility rather than a present feature, it is best understood as an anticipated optimization rather than part of the current architecture.

In the paper’s own summary, GIP-DB is a unified, open, YAML-based repository for all things GPD, with a clean, extensible schema for both experiment and lattice data, built-in uncertainty and correlation handling, ready-to-use Python and C++ APIs, and a lean GitHub+Jekyll infrastructure for community contribution and long-term maintenance. Taken together, these properties position it as a reproducibility-oriented data layer for global DVCS asymmetry fits, lattice comparisons for quantities such as $(x_B,Q^2,t)$8, and benchmarking of new GPD models.