KCSS k-space formalism validation suite

This repository is the companion validation suite for a pure transverse-momentum-space implementation of CSS2 TMD factorization. It supports the formalism program:

$$\mathcal K_{\mathrm{CSS2}} \quad\text{is CSS2 represented directly in } k_T\text{ space.}$$

The repository validates the algebra and perturbative bookkeeping needed for a CSS2-equivalent pure-k-space prescription for high-accuracy TMD extractions. It does not claim that a completed numerical N³LL′ extraction has already been performed.

Here “CSS2” denotes the modern Collins organization of TMD factorization: gauge-invariant operator-defined TMDs, the soft-factor subtraction absorbed into the TMD definitions, process dependence isolated in the hard factor, and coupled renormalization and rapidity evolution in $(\mu,\zeta)$. The project does not modify those operator definitions. It constructs a direct momentum-space representation and extraction calculus for the same parent scheme.

Status at a glance

Layer	Status	Meaning
Formal pure-k-space prescription	Ready	Distribution algebra, convolution exponentials, ingredient manifest, and claim discipline are implemented.
Distributional profile-operator algebra	Passing	The cumulative profile definition, endpoint identities, profile derivatives, RG integrability, and correlated Drell-Yan rapidity profiles are checked by a dedicated validator.
Production profile integration	Blocked by design	A concrete leg-wise or process-level profile has not yet been integrated into the full production W kernel and validated through order αs³.
Numerical N³LL′ extraction	Blocked by design	Requires source-stamped physical NNLO and N³LO coefficient payloads, plus an order-αs³ expansion gate.
Numerical Fourier/Bessel transforms	Not used	The validation suite uses direct k-space distributions and transverse convolution algebra.
Nonperturbative model	Not fixed	DNNs are allowed later, but the perturbative validation is model agnostic.

Expected high-level result:

formal_suite_passed: True
checks: 13/13

Two gates should remain blocked in this formalism repository:

physical coefficient source gate: infrastructure_passed=True; physics_ready=False
N3LL-prime label certificate: formal_prescription_ready=True; implementation_claim_allowed=False

That is the correct outcome. It means the formal prescription and the profile-operator algebra are reproducible. The implementation-level N³LL′ claim remains disabled until the physical coefficient payloads, production profile integration, and order-α_s³ expansion gate are complete.

Quick start

Use Python 3.10 or newer.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run_all_checks.py --clean
cat outputs/latest/run_all_checks_report.txt

Useful repository sanity checks:

make linebreak-check
python -m py_compile run_all_checks.py validators/*.py tools/check_line_breaks.py

Repository layout

.
├── README.md
├── run_all_checks.py
├── requirements.txt
├── pyproject.toml
├── Data_DY_test/
├── validators/
│   ├── kt_kcss_one_loop_validator.py
│   ├── kt_kcss_toypdf_xconv_validator.py
│   ├── kt_kcss_generator_convolution_validator.py
│   ├── kt_kcss_one_loop_evolution_validator.py
│   ├── kt_kcss_two_loop_ingredients_validator.py
│   ├── kt_kcss_running_coupling_evolution_validator.py
│   ├── kt_kcss_distributional_profile_validator.py
│   ├── kt_kcss_binned_wterm_prototype_validator.py
│   ├── kt_kcss_accuracy_ingredient_validator.py
│   ├── kt_kcss_n3lo_matching_import_validator.py
│   ├── kt_kcss_physical_coeff_import_validator.py
│   ├── kt_kcss_n3llprime_label_certificate_validator.py
│   └── kt_kcss_formalism_completion_validator.py
├── scripts/
│   └── stage_public_coefficients.sh
├── coefficient_sources/
│   └── README.md
├── tools/
│   └── check_line_breaks.py
├── docs/
│   ├── formalism_note_v1p3_consistent.pdf
│   ├── formalism_note_v1p3_consistent.tex
│   ├── prd_formalism_draft_v0p1.pdf
│   └── prd_formalism_draft_v0p1.tex
├── formalism_note_v1p3_consistent.pdf
├── formalism_note_v1p3_consistent.tex
└── outputs/
    ├── reference/
    └── latest/              # generated by run_all_checks.py

What is being validated?

The suite checks that the pure-k-space representation has the same perturbative bookkeeping as the parent CSS2 formalism, but with transverse-momentum convolutions replacing pointwise multiplication in impact-parameter space.

The parent-scheme definition is:

$$F^{[\mathcal K_{\mathrm{CSS2}}]}_{i/h} (x,\boldsymbol k;\mu,\zeta) = \mathcal F^{-1}_{b\to k} \left[ \widetilde F^{[\mathrm{CSS2}]}_{i/h} (x,\boldsymbol b;\mu,\zeta) \right].$$

After the analytic dictionary is fixed, the working objects are direct k-space distributions:

$$F_{i/h}(x,\boldsymbol k;\mu,\zeta), \qquad \mathcal C_{i\leftarrow j}(z,\boldsymbol k;\mu,\zeta), \qquad \mathcal D_i(\boldsymbol k;\mu).$$

The high-order matching import rule is:

$$L_b^0 \mapsto \delta^{(2)}(\boldsymbol k), \qquad L_b^m \mapsto \mathfrak L_{m-1}(\boldsymbol k;\mu) \quad (m\ge 1).$$

The generator algebra is:

$$\mathcal G_\eta \otimes_T \mathcal G_\xi = \mathcal G_{\eta+\xi}, \qquad \mathfrak L_m \otimes_T \mathfrak L_n = \mathfrak L_{m+n+1}.$$

This identity is the core reason a Sudakov factor can be represented as a convolution exponential in k space.

Validator map

Validator	What it checks	Role
kt_kcss_one_loop_validator.py	Bin-integrated two-dimensional plus distributions and the one-loop diagonal Drell-Yan singular kernel	Formal check
kt_kcss_toypdf_xconv_validator.py	Longitudinal x-space plus prescription and flavor-vector toy-PDF convolutions	Formal check
kt_kcss_generator_convolution_validator.py	Generator algebra and distribution-basis convolution tables	Formal check
kt_kcss_one_loop_evolution_validator.py	Fixed-coupling one-loop evolution Green function, path independence, and semigroup identity	Formal check
kt_kcss_two_loop_ingredients_validator.py	Two-loop Collins-Soper kernel projection and scalar NNLO logarithmic reconstruction checks	Formal check
kt_kcss_running_coupling_evolution_validator.py	Running-coupling endpoint evolution through order αs²	Formal check
kt_kcss_distributional_profile_validator.py	Cumulative distributional-profile density, constant/canonical limits, endpoint identities, bin additivity, profile-derivative term, coupled RG integrability, and correlated Drell-Yan rapidity profiles	Formal check
kt_kcss_binned_wterm_prototype_validator.py	First binned resummed-W prototype and one-loop profile-scale cancellation	Formal check
kt_kcss_accuracy_ingredient_validator.py	Ingredient manifest for NkLL′ bookkeeping	Formal check
kt_kcss_n3lo_matching_import_validator.py	Schema and projection map for N³LO matching imports using synthetic mock payloads	Formal check
kt_kcss_physical_coeff_import_validator.py	Whether source-stamped physical NNLO and N³LO coefficient files are present	Gate only
kt_kcss_n3llprime_label_certificate_validator.py	Formal-prescription readiness versus implementation-level claim allowance	Gate only
kt_kcss_formalism_completion_validator.py	Whether the formalism note contains the paper-ready closure sections	Formal check

N³LL′ ingredient manifest

The N³LL′ label is defined by ingredient equivalence to CSS2. A k-space implementation can claim N³LL′ only when it contains the same perturbative ingredients as the parent CSS2 calculation.

Ingredient	Required for N³LL′
Cusp anomalous dimension	4 loops
QCD beta function	4 loops
Non-cusp TMD anomalous dimension	3 loops
Collins-Soper kernel / rapidity anomalous dimension	3 loops
Hard function	through order αs³
TMD matching coefficients	through order αs³
DGLAP kernels	P⁽⁰⁾, P⁽¹⁾, P⁽²⁾
Fixed-order subtraction for full-spectrum matching	through the matching order being claimed

The prime in N³LL′ means that boundary functions are included through the same fixed order as the logarithmic accuracy requires. For this project, that means three-loop hard and TMD matching inputs.

Claim discipline

The repository enforces the following certificate:

$$\begin{aligned} \mathrm{ClaimAllowed}_{N^3\mathrm{LL}'} ={}& \mathrm{ParentScheme}_{\mathcal K_{\mathrm{CSS2}}} \wedge \mathrm{IngredientComplete}_{N^3\mathrm{LL}'} \wedge \mathrm{PhysicalPayload} \\\ &\wedge \mathrm{NoMockCoefficients} \wedge \mathrm{NoNumericalBTransform} \wedge \mathrm{RGConsistent} \\\ &\wedge \mathrm{DistributionalScalesConsistent} \wedge \mathrm{ExpandedTo}\{a_s^3\} \wedge \mathrm{NPSeparated}. \end{aligned}$$

The formalism paper may claim a generic pure-k-space N³LL′ prescription by ingredient equivalence to CSS2. A future extraction paper may claim a completed numerical N³LL′ extraction only after the physical coefficient files are imported, a declared leg-wise or process-level profile has been integrated into the production kernel and validated through the claimed order, and the order-α_s³ expansion gate passes.

Staging physical coefficient files

The repository does not bundle external ancillary coefficient files. To stage them in a networked environment, run:

bash scripts/stage_public_coefficients.sh
python validators/kt_kcss_physical_coeff_import_validator.py

The staging script records the intended public-source layout for the high-order TMD matching inputs. After staging, the next implementation work is to parse those files into the canonical coefficient schema used by kt_kcss_n3lo_matching_import_validator.py, compute hashes, and replace the mock payload with vetted physical coefficient data.

Outputs

outputs/reference/ contains reports generated during development. outputs/latest/ is regenerated by:

python run_all_checks.py --clean

The runner writes:

outputs/latest/run_all_checks_report.txt
outputs/latest/run_all_checks_summary.json

along with each validator's JSON, CSV, text report, and log file.

Reproducibility notes

• All formal validators are deterministic.
• The toy-PDF validator uses analytic toy PDFs and scipy.integrate.quad; tolerances are regression tolerances, not experimental uncertainties.
• The distributional-profile validator uses a smooth analytic test profile and deterministic quadrature. Its reported residual is a numerical regression residual, not a theory uncertainty.
• Symbolic checks use sympy.
• No validator evaluates a physical cross section or performs a data fit.
• The coefficient-import validators deliberately distinguish mock or synthetic payloads from source-stamped physical coefficient payloads.

Relationship to DNN extractions

This repository is model agnostic. A DNN may be used later as a nonperturbative module,

$$\mathcal M_{\mathrm{NP}},$$

but the perturbative accuracy label belongs to the operator

$$\mathcal K_{\mathrm{CSS2}}$$

and to the ingredient manifest, not to the DNN parametrization.

Repository maintenance

GitHub should render Markdown and source files with normal line breaks. To catch accidental newline stripping during uploads, run:

make linebreak-check

This check is separate from the physics/formalism validators. It only verifies that text files such as Markdown, Python, shell, TOML, and CFF files have not been collapsed into a few long lines.

Citing this repository

Use the metadata in CITATION.cff once the repository has a tagged release or archived DOI. For now, cite the repository URL and the associated formalism note or paper draft.