QuarkModelTransitions API
Every exported name of GIModel.QuarkModelTransitions. Load it with using GIModel.QuarkModelTransitions; see Transitions and decays for how the pieces fit together.
States and channels
GIModel.QuarkModelTransitions.PhysicalState Type
PhysicalState(label, mass_GeV, components; provenance=(source=:manual,))
physical_state(spectrum, state_or_label)An eagerly resolved external meson state. Its physical mass, common J^P, pure-basis components, mixing coefficients, native radial waves, and provenance are independent of the Spectrum that produced it. Prefer physical_state to obtain these inputs from a GIModel calculation. The manual constructor also accepts assumed radial waves and supplied masses; constructing this object does not solve a Hamiltonian or certify those inputs.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = PhotonEmission(masses)
@assert initial.J == 1
@assert length(initial.components) == 1Related
matrix_element— evaluate an operator between states.physical_state— adapt a solved spectrum state.superpose— construct coherent combinations.PhotonEmission— infer and evaluate a photon transition.TwoMesonChannel— ordered surviving and emitted daughters.
GIModel.QuarkModelTransitions.physical_state Function
physical_state(spectrum, state_or_label)Resolve a solver state, BasisState, or label into a PhysicalState, retaining its mass in GeV, coherent components, radial waves, and provenance.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
basis = BasisState(1, "S", 3, 1; flavors=(:c, :c))
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels=[basis], solver=FiniteDifferenceSolver(ngrid=90, rmax=12.0, nlevels_per_channel=1))
state = physical_state(spectrum, basis)
@assert state.mass_GeV > 0Related
matrix_element— evaluate an operator between states.PhysicalState— resolved meson components and mass.
GIModel.QuarkModelTransitions.superpose Function
superpose(states, coefficients; mass_GeV, label="superposition", normalize=true)Form a coherent linear combination of PhysicalStates. Supply the physical mass explicitly: a superposition of states with different masses is not automatically a mass eigenstate. Normalization includes radial overlaps and interference, not just the sum of coefficient squares. Known isoscalar light channels are resolved into explicit uū/dd̄ components before combining.
Example
using GIModel, GIModel.QuarkModelTransitions
wave = OscillatorWave(0, 0.5, [1.0])
up = PhysicalState("uubar", 0.14, [(basis=BasisState(1,"S",1,0; flavors=(:u,:u)), coefficient=1.0, wave)])
down = PhysicalState("ddbar", 0.14, [(basis=BasisState(1,"S",1,0; flavors=(:d,:d)), coefficient=1.0, wave)])
pi0 = superpose([up, down], [1, -1]; label="pi0", mass_GeV=0.135)
@assert pi0.components[2].coefficient ≈ -1/sqrt(2)Related
PhysicalState, physical_state.
GIModel.QuarkModelTransitions.TwoMesonChannel Type
TwoMesonChannel(first, second)An ordered pair of daughter states. The constructor preserves the supplied order; it never sorts the daughters.
For PseudoscalarEmission, use TwoMesonChannel(surviving, emitted): second must be the emitted 0^- state. Reverse the arguments to choose the other assignment in a two-pseudoscalar channel. Identical-particle rules use state identity, not sorting.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
a1, vector, pion_basis = BasisState(1, "P", 3, 1), BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
charged = compute_spectrum(params, Meson(masses, :u, :d);
levels=[a1, vector, pion_basis], solver)
initial = physical_state(charged, a1)
rho = physical_state(charged, vector)
# Resolve pi0 = (u ubar - d dbar)/sqrt(2) in the isospin limit.
up = compute_spectrum(params, Meson(masses, :u, :u); levels=[pion_basis], solver)
down = compute_spectrum(params, Meson(masses, :d, :d); levels=[pion_basis], solver)
u, d = physical_state(up, pion_basis), physical_state(down, pion_basis)
pion = PhysicalState("pi0", (u.mass_GeV + d.mass_GeV)/2,
[(basis=c.basis, coefficient=sign*c.coefficient/sqrt(2), wave=c.wave)
for (state, sign) in ((u, 1), (d, -1)) for c in state.components];
provenance=(source=:isospin_combination,))
final = TwoMesonChannel(rho, pion)
g, h = 0.7, 0.3 # Illustrative GeV^-1 inputs, not fitted GI predictions.
operator = PseudoscalarEmission(g, h, masses)
@assert final.second.J == 0Related
matrix_element— evaluate an operator between states.
GIModel.QuarkModelTransitions.Vacuum Type
Vacuum final state for a reduced meson-current matrix element.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = LeptonicCurrent(:electromagnetic, masses)
@assert isfinite(matrix_element(Vacuum(), operator, initial).value)Related
sourceGIModel.QuarkModelTransitions.TwoPhotonChannel Type
Two real photons; the implemented result is GI's integrated width amplitude.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = TwoPhotonAnnihilation(masses, AnnihilationTerm((:c, :c), 4/9))
@assert decay_width(TwoPhotonChannel(), operator, final) > 0Related
sourceGIModel.QuarkModelTransitions.TwoGluonChannel Type
Two gluons in the published lowest-order integrated-rate prescription.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = GluonicAnnihilation(masses, 0.3) # Explicit fixed coupling.
@assert decay_width(TwoGluonChannel(), operator, final) > 0Related
sourceGIModel.QuarkModelTransitions.ThreeGluonChannel Type
Three gluons in the published lowest-order integrated-rate prescription.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = GluonicAnnihilation(masses, 0.3)
@assert decay_width(ThreeGluonChannel(), operator, initial) > 0Related
sourceGIModel.QuarkModelTransitions.LeptonNeutrinoChannel Type
Charged lepton plus massless neutrino; CKM is supplied explicitly.
Example
using GIModel, GIModel.QuarkModelTransitions
params, masses = load_parameters_and_quark_masses(default_parameters_path())
basis = BasisState(1, "S", 1, 0)
spectrum = compute_spectrum(params, Meson(masses, :u, :s); levels=[basis],
solver=FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1))
kaon = physical_state(spectrum, basis)
operator = LeptonicCurrent(:P_P, masses, AnnihilationTerm((:u, :s), 2sqrt(3)))
channel = LeptonNeutrinoChannel(0.10566; ckm=0.225)
@assert decay_width(channel, operator, kaon) > 0Related
sourceGIModel.QuarkModelTransitions.MasslessLeptonPair Type
Lepton pair in the massless approximation of GI Eq. D8.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = LeptonicCurrent(:electromagnetic, masses)
@assert decay_width(MasslessLeptonPair(), operator, initial) > 0Related
sourceOperators
GIModel.QuarkModelTransitions.PhotonEmission Type
PhotonEmission(quark_masses; recoil_order=0, ...)
PhotonEmission(multipole, quark_masses, emitters; recoil=false, ...)The Godfrey–Isgur photon-emission operator in the Appendix-D mock-meson prescription. The transition class and multipole are inferred from the final and initial states by photon_transition_class.
recoil_order=0 selects the class-specific leading expression. Order 2 adds the relative (qr)^2 correction where that correction is implemented; currently this is the published M1 E_2 term. Unsupported combinations fail explicitly rather than silently dropping a requested correction.
The explicit-current constructor accepts :M1, :E1, or :M2 and PhotonEmitter terms; the supplied multipole must match the states. Use mass_correction_factor for comparisons at another photon momentum.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = PhotonEmission(masses)
@assert operator.recoil_order == 0Related
AllowedE1— spin-conserving S–P classification.DirectM1— same-radial-level M1 classification.ELECTROMAGNETIC_DEFAULTS— phenomenological electromagnetic inputs.MultipolePhotonEmission— every multipole, exact in q, any orbital angular momentum and mixed states, without the 1985 m/E smearing.HinderedM1— different-radial-level M1 classification.PhotonTransitionClass— common photon classification type.RadiativeAmplitude— photon result and coherent terms.SpinFlipE1— triplet P1 to singlet S0 classification.SpinFlipM2— triplet P2 to singlet S0 classification.e1_transition_amplitude— assemble an E1 amplitude.m1_transition_moment— assemble a moment in nuclear magnetons.matrix_element— evaluate an operator between states.photon_momentum— two-body photon momentum in GeV.photon_transition_class— infer the kernel from spectroscopy.spin_flip_photon_amplitude— assemble a spin-flip photon amplitude.
GIModel.QuarkModelTransitions.MultipolePhotonEmission Type
MultipolePhotonEmission(quark_masses; electric_form = :siegert)Photon emission evaluated from the quark convection and magnetization currents, exact in the photon momentum and resolved into all multipoles (E1, M1, E2, M2, E3, ...). It applies to any pair of PhysicalStates with shared flavors, including D and F waves and mixed states. Unlike PhotonEmission, which evaluates the leading multipole in the 1985 mock-meson prescription with its (m/E) smearing, this operator has no fitted factors.
electric_form = :siegert (default) takes electric multipoles from the charge density through Siegert's theorem with omega = q, as GI and later GI-model papers do for E1; their leading E1 is reproduced exactly. The magnetization current's electric multipoles (the spin-flip E1, and the O(q/m) spin-orbit-like correction to allowed E1) are always in current form. electric_form = :current uses the convection current for every multipole; for relativized wavefunctions it differs from the Siegert form, which is a measure of the gauge ambiguity of the model.
matrix_element returns a result whose multipoles field lists (multipole, k, amplitude) with amplitudes in MeV^(1/2), so that decay_width is their sum of squares. Use multipole_fractions for the normalized amplitudes measured in charmonium.
Example
using GIModel, GIModel.QuarkModelTransitions
masses = QuarkMassTable("c" => 1.628)
state(L, S, J, wave, M) = PhysicalState("cc", M, [(
basis = BasisState(1, L, 2S + 1, J; flavors = (:c, :c)),
coefficient = 1.0, wave = wave,
)])
chi_c2 = state("P", 1, 2, OscillatorWave(1, 0.6, [1.0]), 3.556)
psi = state("S", 1, 1, OscillatorWave(0, 0.7, [1.0]), 3.097)
amplitude = matrix_element(psi, MultipolePhotonEmission(masses), chi_c2)
[m.multipole for m in amplitude.multipoles] # [:E1, :M2, :E3]
@assert decay_width(amplitude) > 0 # MeVRelated
multipole_fractions— normalized multipole amplitudes.PhotonEmission— leading multipole in the GI 1985 prescription.decay_width— width in MeV.matrix_element— evaluate an operator between states.
GIModel.QuarkModelTransitions.PseudoscalarEmission Type
PseudoscalarEmission(g, h, quark_masses)Godfrey–Isgur elementary pseudoscalar-emission operator of Eq. (19). g and h are the direct and recoil couplings in GeV^-1; the products g*q and h*p' in Eq. (19) are dimensionless. quark_masses is a QuarkMassTable and is copied into the operator so the constituent-coordinate momentum routing is explicit and reproducible.
Supply states obtained with physical_state to use GIModel's calculated masses and radial waves. The emitted pseudoscalar is elementary in this operator: its flavor components and mass enter, but its radial wave is not integrated.
The couplings are additional phenomenological inputs, not outputs of the GI spectrum. No fit is performed by this constructor. The example's g and h are illustrative; quantitative predictions require a stated calibration using the chosen waves and conventions. For fixed inputs the amplitude is linear in g and h, including their relative sign and interference.
This is distinct from the legacy fitted A/S0 Table-IV model. The relation A = (g + h/4) beta holds only for the paper's equal-mass, equal-beta, single-oscillator reduction.
For a fixed-wave comparison use mass_correction_factor with target_momentum in GeV and an explicit partial_wave. The factor multiplies that partial-wave amplitude; it excludes the width's separate phase-space factor.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
a1, vector, pion_basis = BasisState(1, "P", 3, 1), BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
charged = compute_spectrum(params, Meson(masses, :u, :d);
levels=[a1, vector, pion_basis], solver)
initial = physical_state(charged, a1)
rho = physical_state(charged, vector)
# Resolve pi0 = (u ubar - d dbar)/sqrt(2) in the isospin limit.
up = compute_spectrum(params, Meson(masses, :u, :u); levels=[pion_basis], solver)
down = compute_spectrum(params, Meson(masses, :d, :d); levels=[pion_basis], solver)
u, d = physical_state(up, pion_basis), physical_state(down, pion_basis)
pion = PhysicalState("pi0", (u.mass_GeV + d.mass_GeV)/2,
[(basis=c.basis, coefficient=sign*c.coefficient/sqrt(2), wave=c.wave)
for (state, sign) in ((u, 1), (d, -1)) for c in state.components];
provenance=(source=:isospin_combination,))
final = TwoMesonChannel(rho, pion)
g, h = 0.7, 0.3 # Illustrative GeV^-1 inputs, not fitted GI predictions.
operator = PseudoscalarEmission(g, h, masses)
@assert decay_width(final, operator, initial) > 0Related
matrix_element— evaluate an operator between states.TwoMesonChannel— ordered surviving and emitted daughters.partial_waves— inspect the available angular components.
GIModel.QuarkModelTransitions.LeptonicCurrent Type
LeptonicCurrent(kind, masses, terms): GI reduced current, including flavor factors. Kinds are 😛_P, :V_V, :Vp_V, :Pp_A1. Returns a dimensionless current factor, not a physical width; in particular the pseudoscalar convention is f_P/M_P.
LeptonicCurrent(:electromagnetic, masses) infers V or V′ from each component's ³S₁ or ³D₁ assignment and calculates its coefficient with vector_current_prefactor. Supply explicit uū/dd̄ components for rho/omega; the mass-sector aliases q/n do not specify a charge or an isospin state. States obtained from an isoscalar spectrum carry that information explicitly; the electromagnetic current resolves their nonstrange channel as (uū+dd̄)/√2. Result terms expose prefactor (including state mixing) and kernel (V or V′), whose product is contribution. Different components can have different kernels; in general there is no single factorizable V for a mixed state.
Normalization: flavor-weighted dimensionless GI current factors of Appendix D. They contain mock-meson mass and relativistic weights, but no leptonic phase space. decay_width uses D7 for LeptonNeutrinoChannel (explicit CKM magnitude) or D8 for MasslessLeptonPair, returning MeV. Lepton masses are neglected in D8.
mass_correction_factor(Vacuum(), operator, initial; target_mass) requires a positive mass in GeV and multiplies result.value at fixed wavefunctions. It excludes the width's separate mass and leptonic phase-space factors.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = LeptonicCurrent(:electromagnetic, masses)
@assert decay_width(MasslessLeptonPair(), operator, initial) > 0Related
Vacuum, LeptonNeutrinoChannel, MasslessLeptonPair, AnnihilationTerm, vector_current_prefactor, mass_correction_factor, matrix_element, decay_width.
GIModel.QuarkModelTransitions.TwoPhotonAnnihilation Type
TwoPhotonAnnihilation(masses, terms): 1S0 or 3P2 annihilation. Coefficients are effective squared quark charges. No helicity decomposition is inferred from the published integrated formula.
Normalization: signed GI width amplitude a in sqrt(GeV), with Gamma[MeV] = GEV_TO_MEV * abs2(a). Integrated phase space, spin averaging, and identical-photon symmetry are already included; do not multiply by them again.
mass_correction_factor(TwoPhotonChannel(), operator, initial; target_mass) requires a positive mass in GeV and multiplies result.value at fixed waves. Its absolute square therefore also corrects the integrated two-photon width.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = TwoPhotonAnnihilation(masses, AnnihilationTerm((:c, :c), 4/9))
result = matrix_element(TwoPhotonChannel(), operator, final)
@assert decay_width(result) ≈ 1000abs2(result.value)Related
AnnihilationTerm, TwoPhotonChannel, AnnihilationAmplitude, mass_correction_factor, matrix_element, decay_width.
GIModel.QuarkModelTransitions.GluonicAnnihilation Type
GluonicAnnihilation(masses, alpha_s): integrated lowest-order gluonic width. alpha_s is either a fixed number or a callable alpha_s(mass_GeV), evaluated at the initial state's mass. mass_correction_factor requires target_mass in GeV and multiplies the width, reevaluating a callable coupling there. A fixed coupling stays fixed. Coherent mixed gluonic annihilation is not provided by this prescription; use a single pure component.
Normalization: decay_width returns MeV from the published integrated lowest-order rate, including phase space and spin/color/symmetry factors. No differential or helicity matrix element is exposed.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = GluonicAnnihilation(masses, M -> GIModel.alpha_s_q(M))
@assert decay_width(TwoGluonChannel(), operator, final) > 0Related
TwoGluonChannel, ThreeGluonChannel, mass_correction_factor, decay_width.
GIModel.QuarkModelTransitions.AnnihilationTerm Type
AnnihilationTerm(flavors, coefficient)
Charge/flavor coefficient for an ordered constituent sector. Mixing coefficients belong to the PhysicalState and must not be included here a second time.
For LeptonicCurrent(:P_P, ...), the coefficient 2sqrt(3) converts the Appendix-D pseudoscalar overlap P into f_P/M_P = 2sqrt(3) P. The sqrt(3) is the color-singlet current factor (three colors contracted with a normalized color state); the factor 2 belongs to this current/overlap normalization. It is not an electric charge or a CKM element. CKM belongs to LeptonNeutrinoChannel, and state flavor/mixing weights belong to the state. For electromagnetic vector annihilation the corresponding coefficient is 2sqrt(3) Q_f for S waves and additionally sqrt(2)/3 for D waves; LeptonicCurrent(:electromagnetic, masses) supplies these automatically. Other operator kinds use their own documented normalization; 2sqrt(3) is not a universal coefficient for arbitrary currents.
Example
using GIModel.QuarkModelTransitions
term = AnnihilationTerm((:c, :c), 4/9)
@assert term.coefficient == 4/9Related
LeptonicCurrent, TwoPhotonAnnihilation.
Amplitudes and widths
GIModel.QuarkModelTransitions.matrix_element Function
matrix_element(final, operator, initial; kwargs...)Evaluate a transition using the masses, wavefunctions, and coherent components of the supplied states. Obtain GIModel solutions with physical_state. The returned object records its normalization and contributions; use decay_width for the supported physical-width conversion in MeV.
Initial states
PhysicalState for native operators, ReferenceState for the qualified TableVReference compatibility backend.
Final states
PhysicalState for the daughter in photon emission, TwoMesonChannel for pseudoscalar emission, Vacuum for a meson-current matrix element, TwoPhotonChannel for two-photon annihilation. For pseudoscalar emission, order the daughters as (surviving, emitted); the second must be a resolved elementary 0^- state. Reference channels must match the labels of their supplied row.
Operators
PhotonEmission, PseudoscalarEmission, LeptonicCurrent, TwoPhotonAnnihilation, TableVReference (internal reference backend). GluonicAnnihilation supports only decay_width, not matrix_element.
PhotonEmission returns a RadiativeAmplitude: M1 values are moments in nuclear magnetons, E1/M2 values are integrated amplitudes in MeV^(1/2). The default constructor infers the multipole and flavor current from the states; verbose=true reports the selection.
PseudoscalarEmission returns a TransitionAmplitude with dimensionless Eq. (19) partial waves, compressed helicities, and coherent component terms. Its g,h couplings are additional phenomenological inputs supplied by the caller. TableVReference returns a TransitionAmplitude for one supplied paper-row partial wave in MeV^(1/2).
LeptonicCurrent and TwoPhotonAnnihilation return an AnnihilationAmplitude. Its .value is respectively a dimensionless GI reduced current or a signed two-photon width amplitude in GeV^(1/2). There is no universal invariant-amplitude normalization shared by these results.
Masses and comparisons
Emission momenta are calculated from the input-state masses. There is no public momentum override. Use mass_correction_factor separately to compare another mass or momentum while keeping waves, mixing, and operator parameters fixed. A closed reference emission channel has no amplitude correction ratio. Explicit flavor components are required where a current or isospin combination must be resolved; an averaged :q label alone does not specify that information.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = PhotonEmission(masses)
amplitude = matrix_element(final, operator, initial)
@assert decay_width(amplitude) > 0Related
Results: decay_width, mass_correction_factor, partial_waves, allowed_partial_waves, PartialWave, partial_wave_projection.
Internal conventions: RelativisticTwoBodyNormalization, GITableVNormalization, TransitionOperator, StrongDecayOperator.
Primitive observables: leptonic_decay_factor, gluonic_annihilation_width, two_photon_amplitude, charge_radius_squared.
GIModel.QuarkModelTransitions.decay_width Function
decay_width(final, operator, initial; kwargs...)
decay_width(amplitude)Return a numerical partial width in MeV. The conversion includes the operator's prescribed phase space, spin sums/averages, and symmetry factors. Do not apply those factors a second time. Masses and emission momenta come from the input states; a closed native emission channel returns zero.
Initial states
PhysicalState from physical_state, ReferenceState for qualified TableVReference compatibility calculations.
Final states
PhysicalState for photon emission, TwoMesonChannel for pseudoscalar emission or reference rows, LeptonNeutrinoChannel for pseudoscalar leptonic decay, MasslessLeptonPair for vector dilepton decay, TwoPhotonChannel for two photons, TwoGluonChannel, ThreeGluonChannel for integrated gluonic rates.
Operators
PhotonEmission, PseudoscalarEmission, LeptonicCurrent, TwoPhotonAnnihilation, GluonicAnnihilation, TableVReference (internal reference backend).
The final-state type must match the operator. LeptonicCurrent(:P_P, ...) requires a lepton-neutrino channel with an explicit CKM magnitude; vector currents use the massless-pair approximation. Axial tau decay remains available through the primitive axial_tau_width, in GeV.
Amplitude inputs
TransitionAmplitude, RadiativeAmplitude, AnnihilationAmplitude produced by TwoPhotonAnnihilation, StrongDecayAmplitude from the reference backend. For a leptonic current use the three-argument form to specify a physical final channel: its Vacuum() matrix element is a current, not a decay width.
Native strong widths use RelativisticTwoBodyNormalization; reference rows use GITableVNormalization. M1 moments are converted with photon phase space; E1/M2 amplitudes are squared. Two-photon amplitudes are squared and converted from GeV to MeV. Gluonic formulas expose integrated rates only.
Mass corrections
mass_correction_factor gives a fixed-wave comparison at another mass or momentum. Most factors multiply amplitudes or currents, so their squared modulus does not generally include the change in the width's remaining phase space. Gluonic correction factors multiply the width directly.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = LeptonicCurrent(:electromagnetic, masses)
current = matrix_element(Vacuum(), operator, initial)
width_MeV = decay_width(MasslessLeptonPair(), operator, initial)
@assert width_MeV > 0
@assert isfinite(current.value)Related
matrix_element, partial_waves, m1_radiative_width, leptonic_pseudoscalar_width, dilepton_vector_width, gluonic_annihilation_width, two_photon_amplitude, GEV_TO_MEV.
GIModel.QuarkModelTransitions.partial_waves Function
partial_waves(amplitude)Return the available PartialWave keys of a strong transition. Read each value with amplitude[wave]; photon results instead record a transition class and multipole.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
a1, vector, pion_basis = BasisState(1, "P", 3, 1), BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
charged = compute_spectrum(params, Meson(masses, :u, :d);
levels=[a1, vector, pion_basis], solver)
initial = physical_state(charged, a1)
rho = physical_state(charged, vector)
# Resolve pi0 = (u ubar - d dbar)/sqrt(2) in the isospin limit.
up = compute_spectrum(params, Meson(masses, :u, :u); levels=[pion_basis], solver)
down = compute_spectrum(params, Meson(masses, :d, :d); levels=[pion_basis], solver)
u, d = physical_state(up, pion_basis), physical_state(down, pion_basis)
pion = PhysicalState("pi0", (u.mass_GeV + d.mass_GeV)/2,
[(basis=c.basis, coefficient=sign*c.coefficient/sqrt(2), wave=c.wave)
for (state, sign) in ((u, 1), (d, -1)) for c in state.components];
provenance=(source=:isospin_combination,))
final = TwoMesonChannel(rho, pion)
g, h = 0.7, 0.3 # Illustrative GeV^-1 inputs, not fitted GI predictions.
operator = PseudoscalarEmission(g, h, masses)
amplitude = matrix_element(final, operator, initial)
waves = partial_waves(amplitude)
@assert waves == [PartialWave(0, 1), PartialWave(2, 1)]
@assert isfinite(amplitude[first(waves)])Related
matrix_element— evaluate an operator between states.PartialWave— orbital and coupled-spin labels.TransitionAmplitude— strong result and its decomposition.decay_width— convert a transition result to MeV.
GIModel.QuarkModelTransitions.multipole_fractions Function
multipole_fractions(amplitude)Normalized multipole amplitudes a_k = A_k / sqrt(sum A^2), keyed by multipole (:E1, :M2, ...), with the sign convention that the lowest multipole is positive. For a decay J_i -> J_f gamma this is the convention of Karl, Meshkov and Rosner and of the CLEO and BESIII analyses of chi_cJ -> J/psi gamma (a_2 is the M2 fraction). Their amplitudes b_k for psi(2S) -> gamma chi_cJ put chi_cJ, the final state, in the angular-momentum slot and equal (-1)^(k-1) times these.
Example
using GIModel, GIModel.QuarkModelTransitions
masses = QuarkMassTable("c" => 1.628)
state(L, S, J, wave, M) = PhysicalState("cc", M, [(
basis = BasisState(1, L, 2S + 1, J; flavors = (:c, :c)),
coefficient = 1.0, wave = wave,
)])
chi_c1 = state("P", 1, 1, OscillatorWave(1, 0.6, [1.0]), 3.511)
psi = state("S", 1, 1, OscillatorWave(0, 0.7, [1.0]), 3.097)
fractions = multipole_fractions(matrix_element(psi, MultipolePhotonEmission(masses), chi_c1))
fractions[:M2] # about -E_gamma/(4 m_c)
@assert fractions[:M2] < 0Related
MultipolePhotonEmission— the multipole-resolved photon operator.
GIModel.QuarkModelTransitions.PartialWave Type
Relative orbital angular momentum L and coupled daughter spin S.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
wave = PartialWave(1, 0)
@assert wave.relative_L == 1Related
matrix_element— evaluate an operator between states.
GIModel.QuarkModelTransitions.mass_correction_factor Function
mass_correction_factor(final, operator, initial; target_mass, kwargs...)
mass_correction_factor(final, operator, initial; target_momentum, kwargs...)Compare another external mass/momentum with the default input-state masses and momentum, holding wavefunctions, mixing, constituent masses and operator parameters fixed. This is not a new spectrum calculation. The operator's docstring specifies the required keyword; unsupported keywords are errors, not silently ignored.
| Operator | Required keyword | Multiplies |
|---|---|---|
LeptonicCurrent, TwoPhotonAnnihilation | target_mass (GeV) | Numerical current/amplitude |
PhotonEmission | target_momentum (GeV) | result.value |
PseudoscalarEmission | target_momentum (GeV), partial_wave | result[partial_wave] |
GluonicAnnihilation | target_mass (GeV) | Width, since no matrix element is defined |
Emission corrections may reevaluate momentum-dependent integrals. A ratio is undefined when the reference amplitude vanishes: those cases throw DomainError. Closed reference emission channels also throw; a factor cannot open a channel whose reference amplitude is unavailable. Factors can be signed or complex. Do not square a current/amplitude factor and assume it is a width correction: additional phase-space and mass factors may enter the width separately.
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
params, masses = load_parameters_and_quark_masses(default_parameters_path())
levels = [BasisState(1, "S", 3, 1), BasisState(1, "S", 1, 0)]
# A modest grid for this example; check convergence for quantitative widths.
solver = FiniteDifferenceSolver(ngrid=240, rmax=24.0, nlevels_per_channel=1)
spectrum = compute_spectrum(params, Meson(masses, :c, :c); levels, solver)
initial = physical_state(spectrum, levels[1])
final = physical_state(spectrum, levels[2])
operator = TwoPhotonAnnihilation(masses, AnnihilationTerm((:c, :c), 4/9))
amplitude = matrix_element(TwoPhotonChannel(), operator, final)
factor = mass_correction_factor(TwoPhotonChannel(), operator, final; target_mass=2.98)
comparison_amplitude = factor * amplitude.value
@assert factor ≈ (2.98/final.mass_GeV)^1.5Related
matrix_element, decay_width, PhysicalState, PartialWave.
GIModel.QuarkModelTransitions.charge_radius_squared Function
charge_radius_squared(radial, m1_GeV, e1, m2_GeV, e2; f=0.2, npoints=900)Mean-square charge radius r_E² (GeV⁻²) of a qq̄ meson, Table VII(d):
r_E² = Σᵢ eᵢ [ <rᵢ²> + (3/4mᵢ²) ∫d³p |φ(p)|² (mᵢ/Eᵢ)^{2f} ]rᵢ = (mⱼ/M)·r is quark i's position from the meson center of mass, so <rᵢ²> = (mⱼ/M)² <r²> with <r²> the position-space expectation over the radial (¹S₀) wave; the second term is the relativistic smearing of the quark-position operator, f the fit exponent (0.2, fitted to the π⁺). e1, e2 are the quark charges (e.g. +2/3, +1/3 for the u and d̄ of π⁺; −1/3, +1/3 for the d and s̄ of K⁰). Multiply by HBARC_FM2 for fm².
Example
using GIModel, GIModel.QuarkModelTransitions
import GIModel.QuarkModelTransitions as QMT
wave = OscillatorWave(0, 0.5, [1.0])
radius_GeV2 = charge_radius_squared(wave, 0.22, 2/3, 0.22, 1/3)
radius_fm2 = QMT.HBARC_FM2 * radius_GeV2
@assert radius_fm2 > 0Related
HBARC_FM2— convert GeV^-2 to fm².matrix_element— evaluate an operator between states.