added coord trafo interface (#129)

Following the suggestion made here:
QEDjl-project/QEDcore.jl#45 (comment)

---------

Co-authored-by: Uwe Hernandez Acosta <u.hernandez@hzdr.de>
Co-authored-by: Anton Reinhard <anton.reinhard@proton.me>

Project.toml

@@ -1,12 +1,6 @@
 name = "QEDbase"
 uuid = "10e22c08-3ccb-4172-bfcf-7d7aa3d04d93"
-authors = [
-    "Uwe Hernandez Acosta <u.hernandez@hzdr.de>",
-    "Simeon Ehrig",
-    "Klaus Steiniger",
-    "Tom Jungnickel",
-    "Anton Reinhard",
-]
+authors = ["Uwe Hernandez Acosta <u.hernandez@hzdr.de>", "Simeon Ehrig", "Klaus Steiniger", "Tom Jungnickel", "Anton Reinhard"]
 version = "0.2.2"
 
 [deps]
@@ -25,6 +19,7 @@ ArgCheck = "2.3.0"
 ConstructionBase = "1"
 DocStringExtensions = "0.8.5, 0.9"
 PhysicalConstants = "0.2.1"
+QEDcore = "0.1.1"
 SimpleTraits = "0.9.4"
 StaticArrays = "1.2.13"
 julia = "1.10"

docs/make.jl

@@ -7,10 +7,12 @@ project_path = Base.Filesystem.joinpath(Base.Filesystem.dirname(Base.source_path
 Pkg.develop(; path=project_path)
 
 using Documenter
-using QEDbase
-
 using DocumenterCitations
 
+using QEDbase
+using QEDcore
+using QEDprocesses
+
 bib = CitationBibliography(joinpath(@__DIR__, "Bibliography.bib"))
 
 pages = [

src/QEDbase.jl

@@ -75,6 +75,9 @@ export particle_direction, particle_species, momentum
 export process, model, phase_space_definition, momenta
 export AbstractInPhaseSpacePoint, AbstractOutPhaseSpacePoint
 
+# Abstract coordinate transformation interface
+export AbstractCoordinateTransformation
+
 # errors
 export InvalidInputError, RegistryError, OnshellError, SpinorConstructionError
 
@@ -112,6 +115,8 @@ include("interfaces/particle_stateful.jl")
 include("interfaces/process.jl")
 include("interfaces/phase_space_point.jl")
 
+include("interfaces/coordinate_transformation.jl")
+
 include("implementations/process/momenta.jl")
 include("implementations/process/particles.jl")
 include("implementations/process/spin_pols.jl")

src/interfaces/coordinate_transformation.jl

@@ -0,0 +1,153 @@
+#######
+# General coordinate transformations
+#######
+
+"""
+    AbstractCoordinateTransformation
+
+Abstract base type for coordinate transformations supposed to be acting on four-momenta.
+Every subtype of `trafo::AbstractCoordinateTransformation` should implement the following interface functions:
+
+* `QEDbase._transform(trafo,p)`: transforms `p`
+* `Base.inv(trafo)`: returns the inverted transform
+
+## Example
+
+Implementing the interface by defining the interface functions:
+
+```jldoctest trafo_interface
+julia> using QEDbase
+
+julia> using QEDcore
+
+julia> struct TestTrafo{T} <: AbstractCoordinateTransformation
+           a::T
+       end
+
+julia> QEDbase._transform(trafo::TestTrafo,p) = trafo.a*p
+
+julia> Base.inv(trafo::TestTrafo) = TestTrafo(inv(trafo.a))
+
+```
+
+The `TestTrafo` can then be used to transform four-momenta:
+
+```jldoctest trafo_interface
+julia> trafo = TestTrafo(2.0)
+TestTrafo{Float64}(2.0)
+
+julia> p = SFourMomentum(4,3,2,1)
+4-element SFourMomentum with indices SOneTo(4):
+ 4.0
+ 3.0
+ 2.0
+ 1.0
+
+julia> trafo(p) # multiply every component with 2.0
+4-element SFourMomentum with indices SOneTo(4):
+ 8.0
+ 6.0
+ 4.0
+ 2.0
+
+julia> inv(trafo)(p) # divide every component by 2.0
+4-element SFourMomentum with indices SOneTo(4):
+ 2.0
+ 1.5
+ 1.0
+ 0.5
+```
+"""
+abstract type AbstractCoordinateTransformation end
+Base.broadcastable(trafo::AbstractCoordinateTransformation) = Ref(trafo)
+
+"""
+    _transform(trafo::AbstractCoordinateTransformation,p::AbstractFourMomentum)
+
+Interface function for the application of the transformation to the four-momentum `p`.
+Must return a four-momentum of the same type as `p`.
+"""
+function _transform end
+
+# make the transform callable
+@inline function (trafo::AbstractCoordinateTransformation)(p::AbstractFourMomentum)
+    return _transform(trafo, p)
+end
+
+@inline function (trafo::AbstractCoordinateTransformation)(
+    psf::PSF
+) where {PSF<:AbstractParticleStateful}
+    p_prime = _transform(trafo, momentum(psf))
+    return PSF(p_prime)
+end
+
+@inline function (trafo::AbstractCoordinateTransformation)(
+    psp::PSP
+) where {PSP<:AbstractPhaseSpacePoint}
+    in_moms = momenta(psp, Incoming())
+    out_moms = momenta(psp, Outgoing())
+    in_moms_prime = _transform.(trafo, in_moms)
+    out_moms_prime = _transform.(trafo, out_moms)
+
+    proc = process(psp)
+    mod = model(psp)
+    ps_def = phase_space_definition(psp)
+    return constructorof(PSP)(proc, mod, ps_def, in_moms_prime, out_moms_prime)
+end
+
+#########
+# Abstract Lorentz Boosts
+#########
+
+"""
+
+    AbstractLorentzTransformation <: AbstractCoordinateTransformation
+
+An abstract base type representing Lorentz transformations, which are coordinate
+transformations between inertial and reference frames in special relativity.
+
+`AbstractLorentzTransformation` extends `AbstractCoordinateTransformation` and provides
+the foundational framework for all types of Lorentz transformations, including boosts.
+These transformations preserve the Minkowski product of two four-vectors and are fundamental to
+the description of relativistic physics, ensuring the laws of physics are the same in all
+inertial frames.
+
+"""
+abstract type AbstractLorentzTransformation <: AbstractCoordinateTransformation end
+
+"""
+
+    AbstractLorentzBoost <: AbstractLorentzTransformation
+
+An abstract base type representing Lorentz boosts, a specific type of Lorentz transformation
+associated with relative motion between inertial frames along one or more spatial directions.
+
+`AbstractLorentzBoost` extends `AbstractLorentzTransformation` and serves as the foundation
+for all types of boost transformations in special relativity. Lorentz boosts describe how
+four-vectors change when transitioning between two reference frames moving at constant velocities (in units of the speed of light) relative to each other.
+"""
+abstract type AbstractLorentzBoost <: AbstractLorentzTransformation end
+
+"""
+
+    AbstractBoostParameter
+
+An abstract base type representing boost parameters used in Lorentz transformations, which
+describe the relative motion between two inertial frames in special relativity.
+
+`AbstractBoostParameter` serves as the foundation for defining specific boost parameters
+that control Lorentz boosts in different spatial directions. Boost parameters typically
+represent the velocity of one reference frame relative to another, expressed as a fraction
+of the speed of light (`\\beta`), and are essential for performing Lorentz transformations
+on four-vectors.
+
+## Overview
+
+In the context of special relativity, a Lorentz boost is a transformation that changes the
+time and spatial components of a four-vector based on the relative motion between two
+inertial reference frames. For example, the boost parameter ``\\beta`` is dimensionless and represents
+this velocity as a fraction of the speed of light. Depending on the frame's relative velocity,
+different forms of boost parameters exist, such as those associated with a single axis or
+a vector describing boosts in multiple spatial dimensions.
+"""
+abstract type AbstractBoostParameter end

test/interfaces/coordinate_transforms.jl

@@ -0,0 +1,52 @@
+using Random
+using QEDbase
+using QEDcore
+
+RNG = MersenneTwister(137137)
+ATOL = 0.0
+RTOL = sqrt(eps())
+
+include("../test_implementation/TestImplementation.jl")
+TESTMODEL = TestImplementation.TestModel()
+TESTPSDEF = TestImplementation.TestPhasespaceDef()
+
+TESTTRAFO = TestImplementation.TestCoordTrafo()
+
+@testset "broadcast" begin
+    test_func(trafo) = trafo
+    @test test_func.(TESTTRAFO) == TESTTRAFO
+end
+
+@testset "single momenta" begin
+    test_mom = rand(RNG, SFourMomentum)
+
+    test_mom_prime = @inferred TESTTRAFO(test_mom)
+
+    @test isapprox(test_mom_prime, TestImplementation._groundtruth_coord_trafo(test_mom))
+end
+@testset "set of momenta" begin
+    test_moms = rand(RNG, SFourMomentum, 3)
+    test_moms_prime = TESTTRAFO.(test_moms)
+
+    @test isapprox(test_moms_prime, TestImplementation._groundtruth_coord_trafo.(test_moms))
+end
+
+@testset "phase space points" begin
+    @testset "($N_INCOMING,$N_OUTGOING)" for (N_INCOMING, N_OUTGOING) in Iterators.product(
+        (1, rand(RNG, 2:8)), (1, rand(RNG, 2:8))
+    )
+        INCOMING_PARTICLES = Tuple(rand(RNG, TestImplementation.PARTICLE_SET, N_INCOMING))
+        OUTGOING_PARTICLES = Tuple(rand(RNG, TestImplementation.PARTICLE_SET, N_OUTGOING))
+
+        TESTPROC = TestImplementation.TestProcess(INCOMING_PARTICLES, OUTGOING_PARTICLES)
+
+        p_in_phys = TestImplementation._rand_momenta(RNG, N_INCOMING)
+        p_out_phys = TestImplementation._rand_momenta(RNG, N_OUTGOING)
+
+        PS_POINT = PhaseSpacePoint(TESTPROC, TESTMODEL, TESTPSDEF, p_in_phys, p_out_phys)
+
+        test_psp_prime = @inferred TESTTRAFO(PS_POINT)
+
+        @test test_psp_prime == TestImplementation._groundtruth_coord_trafo(PS_POINT)
+    end
+end

test/runtests.jl

@@ -3,6 +3,10 @@ using SafeTestsets
 
 begin
     # Interfaces
+    @time @safetestset "coordinate transforms" begin
+        include("interfaces/coordinate_transforms.jl")
+    end
+
     @time @safetestset "model interface" begin
         include("interfaces/model.jl")
     end

test/test_implementation/TestImplementation.jl

@@ -1,6 +1,6 @@
 """
-This module provides a full implementation of the model and process interface. Its purpose is only for testing and it does not reflect any 
-real-world physics. 
+This module provides a full implementation of the model and process interface. Its purpose is only for testing and it does not reflect any
+real-world physics.
 
 The module exports:
 
@@ -11,8 +11,8 @@ TestParticle3
 TestParticle4
 TestModel                   # dummy compute model
 TestModel_FAIL              # failing compute model
-TestProcess                 # dummy scattering process 
-TestProcess_FAIL            # failing scattering process 
+TestProcess                 # dummy scattering process
+TestProcess_FAIL            # failing scattering process
 TestPhasespaceDef           # dummy phase space definition
 TestPhasespaceDef_FAIL      # failing phase space definition
 ```
@@ -24,6 +24,7 @@ export TestParticle1, TestParticle2, TestParticle3, TestParticle4, PARTICLE_SET
 export TestModel, TestModel_FAIL
 export TestProcess, TestProcess_FAIL
 export TestPhasespaceDef, TestPhasespaceDef_FAIL
+export TestCoordTrafo
 
 using Random
 using QEDbase
@@ -33,6 +34,7 @@ using StaticArrays
 include("groundtruths.jl")
 include("test_model.jl")
 include("test_process.jl")
+include("test_coord_trafo.jl")
 include("random_momenta.jl")
 include("utils.jl")
 

test/test_implementation/groundtruths.jl

@@ -8,7 +8,7 @@ Test implementation of the incident flux. Return the Minkowski square of the sum
 I = \\left(\\sum p_i\\right)^2,
 \\end{align}
 ```
-where \$p_i\\in\\mathrm{ps_in}\$. 
+where \$p_i\\in\\mathrm{ps_in}\$.
 """
 function _groundtruth_incident_flux(in_ps)
     s = sum(in_ps)
@@ -18,7 +18,7 @@ end
 """
     _groundtruth_matrix_element(in_ps, out_ps)
 
-Test implementation for a matrix elements. Returns a list of three complex numbers without any physical meaning. 
+Test implementation for a matrix elements. Returns a list of three complex numbers without any physical meaning.
 """
 function _groundtruth_matrix_element(in_ps, out_ps)
     s_in = sum(in_ps)
@@ -156,7 +156,7 @@ end
 """
     _groundtruth_unsafe_diffCS(proc, in_ps, out_ps)
 
-Test implementation of the unsafe differential cross section. Uses the test implementations of `_groundtruth_incident_flux` and `_groundtruth_unsafe_probability`. 
+Test implementation of the unsafe differential cross section. Uses the test implementations of `_groundtruth_incident_flux` and `_groundtruth_unsafe_probability`.
 """
 function _groundtruth_unsafe_diffCS(proc, in_ps, out_ps)
     init_flux = _groundtruth_incident_flux(in_ps)
@@ -194,7 +194,7 @@ end
 """
     _groundtruth_safe_diffCS(proc, in_ps, out_ps)
 
-Test implementation of the safe differential cross section. Uses the test implementations of `_groundtruth_is_in_phasespace` and `_groundtruth_unsafe_diffCS`. 
+Test implementation of the safe differential cross section. Uses the test implementations of `_groundtruth_is_in_phasespace` and `_groundtruth_unsafe_diffCS`.
 """
 function _groundtruth_safe_diffCS(proc, in_ps, out_ps)
     if !_groundtruth_is_in_phasespace(in_ps, out_ps)
@@ -261,3 +261,19 @@ function _groundtruth_total_cross_section(
 ) where {N,T<:AbstractFourMomentum}
     return _groundtruth_total_cross_section.(in_psps)
 end
+
+### Coordinate trafos
+
+_groundtruth_coord_trafo(p::AbstractFourMomentum) = 2 * p
+
+# coord trafo applied to every momentum in psp
+function _groundtruth_coord_trafo(psp::PhaseSpacePoint)
+    in_moms = momenta(psp, Incoming())
+    out_moms = momenta(psp, Outgoing())
+    in_moms_prime = _groundtruth_coord_trafo.(in_moms)
+    out_moms_prime = _groundtruth_coord_trafo.(out_moms)
+
+    return PhaseSpacePoint(
+        process(psp), model(psp), phase_space_definition(psp), in_moms_prime, out_moms_prime
+    )
+end

test/test_implementation/test_coord_trafo.jl

@@ -0,0 +1,3 @@
+
+struct TestCoordTrafo <: AbstractCoordinateTransformation end
+QEDbase._transform(::TestCoordTrafo, p) = _groundtruth_coord_trafo(p)