added docstrings and doc tests to axis boosts

src/lorentz_boost/axis_boost.jl

@@ -5,7 +5,10 @@
 # - add convenient constructors: Boost(::RestFrame,::AbstractFourMomentum)
 
 """
-TBW
+
+    AbstractAxisBoostParameter{T}
+
+Abstract base type for boost parameter of type `T` associated to a certain axis in space.
 """
 abstract type AbstractAxisBoostParameter{T} <: AbstractBoostParameter end
 function convert(
@@ -28,7 +31,10 @@ end
 # Axis Beta
 ###########
 """
-TBW
+
+    AbstractAxisBeta{T} <: AbstractAxisBoostParameter{T}
+
+Abstact base type for boost beta parameter of type `T` associated to an axis in space.
 """
 abstract type AbstractAxisBeta{T} <: AbstractAxisBoostParameter{T} end
 
@@ -47,18 +53,77 @@ _inv(beta::B) where {B<:AbstractAxisBeta} = B(-beta.param)
 end
 
 """
-TBW
+
+    BetaX(beta::T) where {T<:Real}
+
+Beta parameter associated to the x-axis, commonly referred to as ``\\beta_x``. 
+The corresponding Lorentz boost reads
+
+```math
+\\begin{pmatrix}
+p_0\\\\
+p_1\\\\
+p_2\\\\
+p_3
+\\end{pmatrix} \\mapsto
+\\begin{pmatrix}
+\\gamma (p_0 - \\beta_x p_1)\\\\
+\\gamma (p_1 - \\beta_x p_0)\\\\
+p_2\\\\
+p_3
+\\end{pmatrix}
+```
+where the kinematic factor is given as ``\\gamma = 1/\\sqrt{1-\\beta_x^2}``)
+
+## Example
+
+```jldoctest
+julia> using QEDcore
+
+julia> using Random
+
+julia> RNG = MersenneTwister(1234)
+MersenneTwister(1234)
+
+julia> beta_x = BetaX(0.5)
+BetaX{Float64}(0.5)
+
+julia> boost = Boost(beta_x)
+Boost{BetaX{Float64}}(BetaX{Float64}(0.5))
+
+julia> p = SFourMomentum(4,3,2,1)
+4-element SFourMomentum with indices SOneTo(4):
+ 4.0
+ 3.0
+ 2.0
+ 1.0
+
+julia> p_prime = boost(p)
+4-element SFourMomentum with indices SOneTo(4):
+ 2.886751345948129
+ 1.1547005383792517
+ 2.0
+ 1.0
+
+julia> @assert isapprox(p*p,p_prime*p_prime) 
+```
+
+## External link
+
+* [Lorentz Boost on Wikipedia](https://en.wikipedia.org/wiki/Lorentz_transformation)
+* [Kinematics in PDG review](https://pdg.lbl.gov/2024/reviews/rpp2024-rev-kinematics.pdf)
+
 """
-struct BetaX{T} <: AbstractAxisBeta{T}
+struct BetaX{T<:Real} <: AbstractAxisBeta{T}
     param::T
-    function BetaX{T}(beta::T) where {T}
+    function BetaX{T}(beta::T) where {T<:Real}
         -one(beta) <= beta < one(beta) ||
             throw(InvalidInputError("beta parameter <$beta> must be between zero and one"))
         return new{T}(beta)
     end
 end
 
-BetaX(beta::T) where {T} = BetaX{T}(beta)
+BetaX(beta::T) where {T<:Real} = BetaX{T}(beta)
 
 function _transform(boost_param::BetaX, p::M) where {M<:AbstractFourMomentum}
     en = getE(p)
@@ -69,7 +134,66 @@ function _transform(boost_param::BetaX, p::M) where {M<:AbstractFourMomentum}
 end
 
 """
-TBW
+
+    BetaY(beta::T) where {T<:Real}
+
+Beta parameter associated to the y-axis, commonly referred to as ``\\beta_y``. 
+The corresponding Lorentz boost reads
+
+```math
+\\begin{pmatrix}
+p_0\\\\
+p_1\\\\
+p_2\\\\
+p_3
+\\end{pmatrix} \\mapsto
+\\begin{pmatrix}
+\\gamma (p_0 - \\beta_y p_2)\\\\
+p_1\\\\
+\\gamma (p_2 - \\beta_y p_0)\\\\
+p_3
+\\end{pmatrix}
+```
+where the kinematic factor is given as ``\\gamma = 1/\\sqrt{1-\\beta_y^2}``)
+
+## Example
+
+```jldoctest
+julia> using QEDcore
+
+julia> using Random
+
+julia> RNG = MersenneTwister(1234)
+MersenneTwister(1234)
+
+julia> beta_y = BetaY(0.5)
+BetaY{Float64}(0.5)
+
+julia> boost = Boost(beta_y)
+Boost{BetaY{Float64}}(BetaY{Float64}(0.5))
+
+julia> p = SFourMomentum(4,3,2,1)
+4-element SFourMomentum with indices SOneTo(4):
+ 4.0
+ 3.0
+ 2.0
+ 1.0
+
+julia> p_prime = boost(p)
+4-element SFourMomentum with indices SOneTo(4):
+ 3.4641016151377553
+ 3.0
+ 0.0
+ 1.0
+
+julia> @assert isapprox(p*p,p_prime*p_prime) 
+```
+
+## External link
+
+* [Lorentz Boost on Wikipedia](https://en.wikipedia.org/wiki/Lorentz_transformation)
+* [Kinematics in PDG review](https://pdg.lbl.gov/2024/reviews/rpp2024-rev-kinematics.pdf)
+
 """
 struct BetaY{T} <: AbstractAxisBeta{T}
     param::T
@@ -91,7 +215,67 @@ function _transform(boost_param::BetaY, p::M) where {M<:AbstractFourMomentum}
 end
 
 """
-TBW
+
+    BetaZ(beta::T) where {T<:Real}
+
+Beta parameter associated to the z-axis, commonly referred to as ``\\beta_z``. 
+The corresponding Lorentz boost reads
+
+```math
+\\begin{pmatrix}
+p_0\\\\
+p_1\\\\
+p_2\\\\
+p_3
+\\end{pmatrix} \\mapsto
+\\begin{pmatrix}
+\\gamma (p_0 - \\beta_z p_3)\\\\
+p_1\\\\
+p_2\\\\
+\\gamma (p_3 - \\beta_z p_0)\\\\
+\\end{pmatrix}
+```
+where the kinematic factor is given as ``\\gamma = 1/\\sqrt{1-\\beta_z^2}``)
+
+## Example
+
+```jldoctest
+julia> using QEDcore
+
+julia> using Random
+
+julia> RNG = MersenneTwister(1234)
+MersenneTwister(1234)
+
+julia> beta_z = BetaZ(0.5)
+BetaZ{Float64}(0.5)
+
+julia> boost = Boost(beta_z)
+Boost{BetaZ{Float64}}(BetaZ{Float64}(0.5))
+
+julia> p = SFourMomentum(4,3,2,1)
+4-element SFourMomentum with indices SOneTo(4):
+ 4.0
+ 3.0
+ 2.0
+ 1.0
+
+julia> p_prime = boost(p)
+4-element SFourMomentum with indices SOneTo(4):
+  4.041451884327381
+  3.0
+  2.0
+ -1.1547005383792517
+
+julia> @assert isapprox(p*p,p_prime*p_prime) 
+
+```
+
+## External link
+
+* [Lorentz Boost on Wikipedia](https://en.wikipedia.org/wiki/Lorentz_transformation)
+* [Kinematics in PDG review](https://pdg.lbl.gov/2024/reviews/rpp2024-rev-kinematics.pdf)
+
 """
 struct BetaZ{T} <: AbstractAxisBeta{T}
     param::T

src/lorentz_boost/types.jl

@@ -8,9 +8,53 @@
 Abstract base type for coordinate transformations supposed to be acting on four-momenta. 
 Every subtype of `trafo::AbstractCoordianteTransformation` should implement the following interface functions:
 
-* [`QEDcore._transform(trafo,p)`](@ref}: transfroms `p`
+* `QEDcore._transform(trafo,p)`: transfroms `p`
 * `Base.inv(trafo)`: returns the inverted transform
 
+## Example
+
+Implementing the interface by defining the interface functions: 
+
+```jldoctest trafo_interface
+julia> using QEDcore
+
+julia> struct TestTrafo{T} <: QEDcore.AbstractCoordinateTransformation   
+           a::T
+       end
+
+julia> QEDcore._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)
+4-element SFourMomentum with indices SOneTo(4):
+ 8.0
+ 6.0
+ 4.0
+ 2.0
+
+julia> inv(trafo)(p)
+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)