Update process interface interface (QEDjl-project#59)

With this, we update the process and cross-section interface to adopt
the new phase space points. This solved QEDjl-project#57.

# TODOs

- [x] update tests for process interface
- [x] update test implementation for processes
- [x] update process interface description
- [x] update tests for cross-section and probability
- [x] update building of cross sections and probabilities
- [x] update perturbative compton
- [x] old interface (incl. versions for vectors of inputs)
- [x] cleanup

---------

Co-authored-by: Uwe Hernandez Acosta <[email protected]>
Co-authored-by: Anton Reinhard <[email protected]>

src/QEDprocesses.jl

@@ -58,8 +58,12 @@ include("interfaces/setup_interface.jl")
 include("phase_spaces.jl")
 include("momentum_generation.jl")
 include("propagators.jl")
-include("probabilities.jl")
-include("cross_sections.jl")
+
+include("cross_section/diff_probability.jl")
+include("cross_section/diff_cross_section.jl")
+include("cross_section/total_probability.jl")
+include("cross_section/total_cross_section.jl")
+include("cross_section/internal.jl")
 
 include("models/models.jl")
 include("processes/one_photon_compton/one_photon_compton.jl")

src/cross_section/diff_cross_section.jl

@@ -0,0 +1,34 @@
+########################
+# differential and total cross sections.
+#
+# This file contains default implementations for differential 
+# cross sections based on the scattering process interface
+########################
+
+function _incident_flux(psp::PhaseSpacePoint)
+    return _incident_flux(psp.proc, psp.model, momentum.(psp.in_particles))
+end
+
+"""
+    unsafe_differential_cross_section(phase_space_point::PhaseSpacePoint)
+
+Return the differential cross section evaluated on a phase space point without checking if the given phase space is physical.
+"""
+function unsafe_differential_cross_section(phase_space_point::PhaseSpacePoint)
+    I = 1 / (4 * _incident_flux(phase_space_point))
+
+    return I * unsafe_differential_probability(phase_space_point)
+end
+
+"""
+    differential_cross_section(phase_space_point::PhaseSpacePoint)
+
+If the given phase spaces are physical, return differential cross section evaluated on a phase space point. Zero otherwise.
+"""
+function differential_cross_section(phase_space_point::PhaseSpacePoint)
+    if !_is_in_phasespace(phase_space_point)
+        return zero(eltype(momentum(phase_space_point, Incoming(), 1)))
+    end
+
+    return unsafe_differential_cross_section(phase_space_point)
+end

src/cross_section/diff_probability.jl

@@ -0,0 +1,42 @@
+############
+# scattering probabilities
+#
+# This file contains implementations of the scattering probability based on the
+# process interface with and without input validation and/or phase space
+# constraint.
+############
+
+# convenience function
+# can be overloaded if an analytical version is known
+function _matrix_element_square(psp::PhaseSpacePoint)
+    mat_el = _matrix_element(psp)
+    return abs2.(mat_el)
+end
+
+"""
+    unsafe_differential_probability(phase_space_point::PhaseSpacePoint)
+
+Return differential probability evaluated on a phase space point without checking if the given phase space(s) are physical.
+"""
+function unsafe_differential_probability(psp::PhaseSpacePoint)
+    matrix_elements_sq = _matrix_element_square(psp)
+
+    normalization = _averaging_norm(psp.proc)
+
+    ps_fac = _phase_space_factor(psp)
+
+    return normalization * sum(matrix_elements_sq) * ps_fac
+end
+
+"""
+    differential_probability(phase_space_point::PhaseSpacePoint)
+
+If the given phase spaces are physical, return differential probability evaluated on a phase space point. Zero otherwise.
+"""
+function differential_probability(phase_space_point::PhaseSpacePoint)
+    if !_is_in_phasespace(phase_space_point)
+        return zero(eltype(momentum(phase_space_point, Incoming(), 1)))
+    end
+
+    return unsafe_differential_probability(phase_space_point)
+end

src/cross_section/internal.jl

@@ -0,0 +1,139 @@
+
+# convenience function for internal use only
+# differential probability without energy momentum conservation check
+# single in phase space points/ single out phase space point
+# based on four-momenta
+function _unsafe_differential_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    psp = generate_phase_space(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return unsafe_differential_probability(psp)
+end
+
+# convenience function for internal use only 
+# differential probability without energy momentum conservation check
+# based on coordinates
+function _unsafe_differential_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:Real}
+    in_momenta, out_momenta = _generate_momenta(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return _unsafe_differential_probability(
+        proc, model, phase_space_def, in_momenta, out_momenta
+    )
+end
+
+# convenience function for internal use only 
+# differential probability with energy momentum conservation check
+# one in phase space point/ one out phase space point
+# based on four-momenta
+function _differential_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    psp = generate_phase_space(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return differential_probability(psp)
+end
+
+# convenience function for internal use only 
+# differential probability with energy momentum conservation check
+# one in phase space point/ one out phase space point
+# based on coordinates
+function _differential_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:Real}
+    in_momenta, out_momenta = _generate_momenta(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return _differential_probability(proc, model, phase_space_def, in_momenta, out_momenta)
+end
+
+# convenience function for internal use only 
+# differential cross sections without energy momentum conservation check
+# single in phase space point/ single out phase space point
+# based on four-momenta
+function _unsafe_differential_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    psp = generate_phase_space(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return unsafe_differential_cross_section(psp)
+end
+
+# convenience function for internal use only 
+# differential cross sections without energy momentum conservation check
+# single in phase space point/ single out phase space point
+# based on coordinates
+function _unsafe_differential_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:Real}
+    in_momenta, out_momenta = _generate_momenta(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return _unsafe_differential_cross_section(
+        proc, model, phase_space_def, in_momenta, out_momenta
+    )
+end
+
+# convenience function for internal use only 
+# differential cross sections with energy momentum conservation check
+# single in phase space point/ single out phase space point
+function _differential_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    psp = generate_phase_space(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return differential_cross_section(psp)
+end
+
+# convenience function for internal use only 
+# differential cross sections with energy momentum conservation check
+# single in phase space point/ several out phase space points
+function _differential_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+    out_phase_space::AbstractVector{T},
+)::Float64 where {T<:Real}
+    in_momenta, out_momenta = _generate_momenta(
+        proc, model, phase_space_def, in_phase_space, out_phase_space
+    )
+    return _differential_cross_section(
+        proc, model, phase_space_def, in_momenta, out_momenta
+    )
+end

src/cross_section/total_cross_section.jl

@@ -0,0 +1,87 @@
+
+############
+# Total cross sections
+############
+
+# total cross section on single phase space point
+# based on four-momenta
+function _total_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    I = 1 / (4 * _incident_flux(proc, model, in_phase_space))
+
+    return I * _total_probability(proc, model, phase_space_def, in_phase_space)
+end
+
+# total cross section on single phase space point
+# based on coordinates
+function _total_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+) where {T<:Real}
+    in_momenta = _generate_incoming_momenta(proc, model, phase_space_def, in_phase_space)
+    return _total_cross_section(proc, model, phase_space_def, in_momenta)
+end
+
+# total cross section on several phase space points
+function _total_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    in_phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractMatrix{T},
+) where {T<:AbstractPhasespaceElement}
+    res = Vector{eltype(T)}(undef, size(in_phase_space, 2))
+    for i in 1:size(in_phase_space, 2)
+        res[i] = _total_cross_section(
+            proc, model, in_phase_space_def, view(in_phase_space, :, i)
+        )
+    end
+    return res
+end
+
+"""
+    total_cross_section(
+        proc::AbstractProcessDefinition,
+        model::AbstractModelDefinition,
+        in_phase_space_def::AbstractPhasespaceDefinition,
+        in_phase_space::AbstractVecOrMat{T},
+    ) where {T<:QEDbase.AbstractFourMomentum}
+
+Return the total cross section for a given combination of scattering process and compute model, evaluated at the particle momenta.
+"""
+function total_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    in_phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVecOrMat{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    _check_in_phase_space_dimension(proc, model, in_phase_space)
+
+    return _total_cross_section(proc, model, in_phase_space_def, in_phase_space)
+end
+
+"""
+    total_cross_section(
+        proc::AbstractProcessDefinition,
+        model::AbstractModelDefinition,
+        in_phase_space_def::AbstractPhasespaceDefinition,
+        in_phase_space::AbstractVecOrMat{T},
+    ) where {T<:Real}
+
+Return the total cross section for a given combination of scattering process and compute model, evaluated at the coordinates.
+"""
+function total_cross_section(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    in_phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVecOrMat{T},
+) where {T<:Real}
+    _check_in_phase_space_dimension(proc, model, in_phase_space)
+
+    return _total_cross_section(proc, model, in_phase_space_def, in_phase_space)
+end

src/cross_section/total_probability.jl

@@ -0,0 +1,74 @@
+
+###########
+# Total probability
+###########
+
+# total probability on a phase space point
+# based on coordinates
+function _total_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVector{T},
+) where {T<:Real}
+    in_momenta = _generate_incoming_momenta(proc, model, phase_space_def, in_phase_space)
+    return _total_probability(proc, model, phase_space_def, in_momenta)
+end
+
+# total probability on several phase space points
+function _total_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractMatrix{T},
+) where {T<:AbstractPhasespaceElement}
+    res = Vector{eltype(T)}(undef, size(in_phase_space, 2))
+    for i in 1:size(in_phase_space, 2)
+        res[i] = _total_probability(
+            proc, model, phase_space_def, view(in_phase_space, :, i)
+        )
+    end
+    return res
+end
+
+"""
+    total_probability(
+        proc::AbstractProcessDefinition,
+        model::AbstractModelDefinition,
+        phase_space_def::AbstractPhasespaceDefinition,
+        in_phase_space::AbstractMatrix{T},
+    ) where {T<:QEDbase.AbstractFourMomentum}
+
+Return the total probability of a given model and process combination, evaluated at the particle momenta.
+"""
+function total_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVecOrMat{T},
+) where {T<:QEDbase.AbstractFourMomentum}
+    _check_in_phase_space_dimension(proc, model, in_phase_space)
+
+    return _total_probability(proc, model, phase_space_def, in_phase_space)
+end
+
+"""
+    total_probability(
+        proc::AbstractProcessDefinition,
+        model::AbstractModelDefinition,
+        phase_space_def::AbstractPhasespaceDefinition,
+        in_phase_space::AbstractMatrix{T},
+    ) where {T<:Real}
+
+Return the total probability of a given model and process combination, evaluated at the coordinates.
+"""
+function total_probability(
+    proc::AbstractProcessDefinition,
+    model::AbstractModelDefinition,
+    phase_space_def::AbstractPhasespaceDefinition,
+    in_phase_space::AbstractVecOrMat{T},
+) where {T<:Real}
+    _check_in_phase_space_dimension(proc, model, in_phase_space)
+
+    return _total_probability(proc, model, phase_space_def, in_phase_space)
+end