Refactoring of differential cross section functionality

[szabo137]

Problem statement

The current implementation only allows implementing differential_cross_section directly for given processes. Furthermore, the interface does not allow the implementation of different phase-space coordinate systems, e.g. to model $d\sigma/dE$ and $d\sigma/d\cos\theta$ for the same process.

Suggested solution

Advanced process interface

I suggest to disassemble the differential cross-sections interface into a more flexible interface:

flowchart TD
  _differential_cross_section --> _differential_probability
  _differential_cross_section --> _incident_flux*
  _differential_probability --> _avg_matrix_element_square
  _differential_probability --> _phase_space_factor*
  _differential_probability -.-> _is_in_phasespace*
  _avg_matrix_element_square --> _matrix_element*
  _avg_matrix_element_square --> _avg_normalization*

where the functions with the asterisk give the new interface for the calculation of differential cross-sections:

• _matrix_element: the matrix element of the process
• _phase_space_factor: the value of the pre-differential factor of the phase-space measure
• _is_in_phasespace: checks if a given input is physical, see below
• _incident_flux: the incident particle flux, used to normalize the probability
• _avg_normalization: normalization for averaging of squared matrix elements

The underscore of those functions implies, that they are not exported, and no input validation check is performed. For the functions _differential_cross_section and _differential_probability there are versions differential_cross_section and differential_probability, where input validation is performed.

Phase space definition

To attack the original problem using different coordinate systems for the same process, this PR adds a simple system for coordinate systems and frames of reference. Those are propagated through a composite type:

PhasespaceDefinition{
    CS<:AbstractCoordinateSystem,
    F<: AbstractFrameOfReference
}

Currently, the given example implementations are very limited, but this deserves an interface in the future. A dedicated issue will be opened during the review process of this PR (see todos below).

Phase space check

Not included in the input validation is the check if given incoming and outgoing phase-spaces are physical, i.e. if all momenta are on-shell and fulfill some sort of energy-momentum conservation. Therefore, I suggest to add another interface function

_is_in_phasespace(
    in_ps_def::AbstractPhasespaceDefinition,
    in_ps::AbstractVector{T},
    out_ps_def::AbstractPhasespaceDefinition,
    out_ps::AbstractVector{T},
) where {T<:QEDbase.AbstractFourMomentum}

which returns true if the input is physical, and false otherwise. Consequently, there are unsafe versions of cross-sections and probabilities, which don't perform the check given by the function above, and safe versions, which return null if the condition given by _is_in_phasespace is not met.

Final remarks

To conclude, the different versions of cross-section and probability functions, derived from the interface above, are

_unsafe_differential_cross_section # without input validation, without phase-space check
_differential_cross_section        # without input validation, with phase-space check
unsafe_differential_cross_section  # with input validation, without phase-space check
differential_cross_section         # with input validation, with phase-space check

_unsafe_differential_probability   # without input validation, without phase-space check
_differential_probability          # without input validation, with phase-space check
unsafe_differential_probability    # with input validation, without phase-space check
differential_probability           # with input validation, with phase-space check

where only the functions without an underscore are exported, for all of those functions, there are implementations for all combinations of vectors and matrices for the incoming and outgoing phase space.

Todos:

• [x] write tests for (_(unsafe_))probability
• [x] make total cross-section an interface function
• [x] make energy-momentum check for safe implementations an interface function
• [ ] Write a gist about the broadcasted implementations
• [x] rename _[unsafe_]probability to _[unsafe]differential_probability
• [x] cleanup in Project.toml
• [ ] open issue on PhasespaceDefinition

[AntonReinhard]

Another thought: We should probably add an @inline to all of the functions that just delegate by broadcast or some check.

[szabo137]

@steindev Thanks for reviewing, I hopefully addressed all comments. Ready for revisiting!

[steindev]

@tjungni would you please approve in case all your comments are resolved?

[szabo137]

@tjungni I addressed all of your comments and appreciate your approval.