UGFT Core Library

UGFT is a compact, sign‑locked collection of algebraic building blocks for field theory experiments. The library fixes every Chapter‑0 operating convention up front—metric signature, Levi–Civita normalization, Fourier/Laplace phases, Wick map, and integer ledgers—so you can assemble scalar, gauge, spinor, and axial‑torsion toy models without re‑deciding basic rules. Geometry helpers, projector stacks, harmonics, and diagnostic pipelines share the same locks to keep all algebra compatible.

All calculations use hat units (c = ħ = 1) and keep gauge couplings explicit. The codebase is intentionally algebraic rather than numerical: tensors are plain NumPy arrays, with helpers for locked duals, projectors, and stress–energy bookkeeping.

---

Installation

pip install -r requirements.txt

The package has no compiled extensions. Tests require pytest (already listed in requirements.txt).

---

Core operating conventions (Chapter 0)

These sentinels live in ugft.oslocks and are hashed to prevent drift:

• Signature & orientation: Minkowski (-,+,+,+) with ε_{0123}=+√|g| and ε^{0123}=-1/√|g|; contraction identity ε^{μνρσ} ε_{ανρσ} = -3! δ^μ_α.
• Hodge star: In Lorentzian, *^2 = (-1)^{p(4-p)+1}; Euclidean map uses e_E^0 = i e^0 and (*_E)^2 = (-1)^p.
• Gauge traces and couplings: Tr(T^A T^B) = δ^{AB}; field strength and covariant derivative keep g explicit; Wilson loops normalized by 1/ dim R with ledger hooks.
• Fourier/Laplace/Wick: Phase exp(i(ω t − k·x)), retarded continuation ω → ω + i0^+, Plancherel identities in spectral windows, and Wick map S_E = -i S_L|_{t→-iτ} with Euclidean epsilon and tetrad flips preserved.
• Gravity/torsion scaffolding: ADM delta with lapse N, extrinsic curvature sign locked, Einstein–Hilbert + GHY boundary orientation, metric‑affine constraint helper, and axial torsion policy (S_μ only) with irreducible decomposition checks.
• Integer ledgers: (c₁, ν_G, ν_R, k, z_γ) are tracked, frozen across Wick rotation, and stored with boundary/topological metadata for audits.

Helpers such as epsilon_tensor, epsilon_contraction, hodge_square_sign, and the immutable OS_LOCKS table are available at ugft package scope.

---

Package layout

• ugft/oslocks.py: Chapter‑0 sentinels, epsilon tensors, Hodge sign helper, and lock hash.
• ugft/units.py: Hat‑unit helpers, dimensional consistency checks, and safe rescaling.
• ugft/algebra/forms.py: Wedge products, Hodge duals, inner products, and constant‑form exterior calculus on flat Minkowski space with a selectable baseline/optimized path for wedge/Hodge/d/δ operations.
• ugft/geometry.py: ADM measure/delta, extrinsic curvature and ghy_boundary_term, Cartan torsion/curvature 2‑forms, metricity guard, NewtonConstant, and Einstein tensor helpers wired to the lock hash.
• ugft/harmonics.py: Scalar, vector, and tensor spherical harmonics on S² with epsilon normalization, spherical delta kernel/guardrail, and baseline vs cached modes toggled via ugft.harmonics.set_harmonics_mode.
• ugft/projectors/: Helmholtz vector projectors and Barnes–Rivers spin‑2 projectors.
• ugft/transforms/: Miller kernels with baseline/FFT implementations toggled by set_miller_mode, spectral windows, Fourier/Laplace transforms with Plancherel drift checks, retarded/static kernels, Hadamard curved kernel, kernel catalog (incl. spherical delta audit), and Wick rotation helpers with ledger immutability checks.
• ugft/fields/: Algebraic toy sectors:
  • scalar.py: Klein–Gordon Lagrangian density, equations of motion, stress tensor, and scalar energy‑density positivity checks.
  • gauge.py: Non‑Abelian field strength, Yang–Mills Lagrangian/Hamiltonian, stress tensor, Wilson loop/CS level calculators, Skyrme current, gauge current, BRST gauge fixing (flat/curved, Abelian/non‑Abelian) with ghost operators, and static/retarded kernels.
  • spinor.py: Dirac/curved gamma matrices, Clifford checks, axial current and torsion coupling, tetrad metric helper, Dirac EOM with torsion, four‑fermion effective contact, and stress tensor.
  • torsion.py: Axial Proca‐style S_μ, irreducible torsion decomposition, axial‑only sentinel, energy/Hamiltonian density, EOM residuals, metricity/Bianchi checks, Stückelberg split/UV diagnostics, spin–spin Yukawa and spin‑stiff density helpers.
  • total.py: Aggregates per‑sector stress–energy, bulk_lagrangian_density, and einstein_equation_residual for the gravity sector.
• ugft/ledger.py: Bulk (jar) vs boundary/topological (rim) ledgers with integer invariants, BoundaryTopologicalBundle, immutability guards, and Wilson/CS/Nieh–Yan/Holst audit hooks.
• ugft/diagnostics/: Dispersion relation calculators (Proca principal symbols, GW observables, DC corridor), spin‑stiff energy report, and governance recipes/viability bars with scope guardrails.
• ugft/ghost.py: Ghost Control pipeline with curved ghost actions, Stückelberg UV checks, viability summaries, and governance integration.

Ghost Control (Chapter 1)

ugft.ghost implements the Chapter‑1 “Ghost Control Protocol” sentinels as algebraic checks on quadratic kernels (K, G, M2):

• C1.0 universal conventions: Signature, Hodge, trace, ADM measure, Wick map, and projector/Stückelberg policies must match the Chapter‑0 locks recorded on each kernel.
• Taxonomy & diagnostics (C1.1–C1.2f): Eigenvalue taxonomy (ghost/tachyon/gradient), mass/residue positivity, Dirac–Bergmann closure, and initial‑data compatibility.
• Projector/gauge stops (C1.3): Stückelberg strong‑coupling bounds and unitary vs covariant gauge cross‑checks, plus projector symmetry tests.
• Gauge‑fixing/BRST health (C1.4): FP/Gribov gap, Slavnov–Taylor preservation, and anomaly sourcing derived from kinetic/gradient commutators.
• Higher‑derivative & non‑local sentries (C1.5): Degeneracy/Ostrogradsky blocking, non‑local kernel positivity, and spectral positivity.
• Curved backgrounds & boundaries (C1.6): Hyperbolicity and subluminal principal symbol, boundary/edge/horizon ledgers, effective metric, and Planck‑mass positivity.
• Positivity/analyticity (C1.7): Forward‑limit positivity, sum rules, spectral matrix health, polynomial bounds, and thermal KMS sentinel.
• Radiative stability (C1.8): Wave‑function factors, running masses, Nielsen identity, regulator safety, and scheme‑sign preservation.
• Constructive patterns (C1.9): Auxiliary rehabilitation, EFT demarcation, forbidden cure ledgering, and constraint promotion tracking.
• Topological ledger (C1.10): Bundle consistency and integer characteristic integrals.

The default pipeline wires all stops—including the equivalence‑theorem (S‑ET) basis flip and the “S‑*” mechanical checks (DOF counts, symplectic positivity, zero‑mode, Schur, and projector symmetry tests)—into a single run_ghost_pipeline entry point that returns a GhostReport with per‑stop booleans, governance messages, and a fresh lock hash.

See tests/ for concrete usage patterns across all modules.

---

Gravitational Gauge Slice (Chapter 2)

Chapter‑2 adds the gravitational/torsion gauge slice plus Miller equivalence plumbing:

• Geometry & ledgers: ADM extrinsic curvature/ghy_boundary_term, Cartan torsion and curvature 2‑forms, metricity guard, NewtonConstant, Einstein tensor, and einstein_equation_residual. Boundary/topological ledgers capture GHY, Nieh–Yan, and Holst surface terms via BoundaryTopologicalBundle.
• Bulk/boundary actions: bulk_lagrangian_density assembles gravity, YM, axial Proca torsion, scalar, Dirac, and Skyrme pieces; ledger posts cover Pontryagin/CS and Nieh–Yan/Holst integers without touching bulk EOM.
• Fields & EOM: Skyrme/gauge currents, curved/flat gauge fixing with ghost operators, Dirac EOM with axial torsion, irreducible torsion decomposition, axial-only enforcement, Stückelberg split/UV accounting, spin–spin Yukawa, and spin-stiff density helpers.
• Kernels & diagnostics: Hadamard curved kernel, Proca principal symbols, GW observables, spherical delta kernel/guardrail, DC positivity corridor, recipes, viability bars VB1–VB6, and scope guardrails enforced in governance/ghost reports.

---

Quickstart

import numpy as np
from ugft import OS_LOCKS, epsilon_tensor, hodge_square_sign
from ugft.algebra.forms import set_forms_mode
from ugft.diagnostics.dispersion import proca_principal_symbol
from ugft.fields.gauge import brst_gauge_fix, field_strength
from ugft.fields.total import bulk_lagrangian_density, einstein_equation_residual
from ugft.fields.torsion import spin_spin_yukawa_potential, stueckelberg_split
from ugft.geometry import NewtonConstant, ghy_boundary_term
from ugft.ghost import QuadraticKernel, run_ghost_pipeline
from ugft.harmonics import scalar_harmonic, set_harmonics_mode, spherical_delta_kernel
from ugft.ledger import Ledger
from ugft.transforms.miller import mt_dft, set_miller_mode
from ugft.transforms.spectral import plancherel_assert

# Chapter 0 locks: signature/epsilon/Hodge sign are fixed
print(OS_LOCKS["metric_signature"])        # (-1, 1, 1, 1)
print(epsilon_tensor()[0, 1, 2, 3])        # +1
print(hodge_square_sign(1))                # +1 for a 1-form in Lorentzian

# Chapter 2 equivalence toggles for forms/harmonics/Miller
set_forms_mode("optimized")                # cached wedge/Hodge/d/δ path
set_harmonics_mode("optimized")            # cached spherical harmonics
set_miller_mode("optimized")               # FFT-backed Miller transform
plancherel_assert(np.eye(4))               # guard locked Fourier normalization
Y_00 = scalar_harmonic(0, 0, np.pi / 2, 0) # spherical harmonic (guardrail enforced)
spectrum = mt_dft(np.array([1, 0, 0, 0], dtype=complex))  # Miller transform sample
delta_r = spherical_delta_kernel(np.linspace(0.0, 1.0, 5)) # ∇²(1/r) = -4πδ³ audit

# Chapter 2 bulk/boundary assembly (gravity + YM + torsion + scalar)
metric = np.diag([-1, 1, 1, 1])
G = NewtonConstant(1.0)
A = np.zeros((1, 4))
f_abc = np.zeros((1, 1, 1))
F = field_strength(A, g=1.0, structure_constants=f_abc)
fields = {
    "gauge": {"F": F},
    "torsion": {"S": np.zeros(4), "H": np.zeros((4, 4)), "m_S": 1.5},
    "scalar": {"phi": np.array(0.0), "d_phi": np.zeros(4), "m": 1.0},
    "dirac_density": 0.0,  # placeholder slot for Dirac sector
    "skyrme_density": 0.0, # placeholder slot for Skyrme term
}
ledger = Ledger()
bulk_density, components = bulk_lagrangian_density(
    metric, fields, {"G": G, "g": 1.0}, return_components=True
)
residual, div = einstein_equation_residual(
    metric, fields, {"G": G}, check_divergence=True
)
ghy_term, _ = ghy_boundary_term(trace_K=0.0, sqrt_gamma=1.0, ledger=ledger) # boundary ledger
pi_split = stueckelberg_split(fields["torsion"]["S"], mass=fields["torsion"]["m_S"])
yukawa = spin_spin_yukawa_potential(
    distance=1.0, coupling=1.0, mass=fields["torsion"]["m_S"], spin_alignment=1.0
)
symbol = proca_principal_symbol(np.array([1.0, 0.0, 0.0, 0.0]))

# Gauge helpers and BRST fixing with ledgered diagnostics (Chapter 1/2)
gf_density = brst_gauge_fix(F_a=np.zeros(1), B=np.zeros(1), c=np.zeros(1), cbar=np.zeros(1)) # flat Abelian
# Curved/Non-Abelian variants available via curved_abelian_gauge_fix / curved_nonabelian_gauge_fix

# Ghost Control + viability/guardrails (Chapters 1–2)
K_kernel = np.eye(2)
G_kernel = np.eye(2)
M2 = 0.25 * np.eye(2)
constraints = {
    "signature": "(-,+,+,+)",
    "hodge": "lorentzian",
    "trace_convention": "deltaAB",
    "adm_measure": "N*sqrt_gamma",
    "wick_map": "t->-i tau",
    "projector_policy": "barnes-rivers",
    "constraint_algebra_closed": True,
    "initial_data_compatible": True,
    "stueckelberg_mass": 3.0,
    "stueckelberg_coupling": 0.1,
    "cutoff": 0.1,
    "higher_derivative_degenerate": True,
    "ostrogradsky_blocked": True,
    "nielsen_identity": True,
    "regulator_safe": True,
    "scheme_preserves_sign": True,
    "bundle_consistent": True,
    "characteristic_integrals": [1, 0],
    "field_type": "vector",
    "ghost_mass": 2.0,
}
kernel = QuadraticKernel(K=K_kernel, G=G_kernel, M2=M2, constraints=constraints)
report = run_ghost_pipeline(kernel, expected_dof=2)
print(report.stop_results)                # {'C1.0': True, 'S-H': True, ...}
print(report.messages)                    # governance/UV notes (e.g., Stückelberg tracking)

Run the full test suite to validate the OS locks and all primitives:

pytest

---

License

This project is released under the MIT License. See LICENSE for details.