FourVectors.jl is a small package for Cartesian four-momenta in high-energy physics.
The central type is FourVector, an immutable FieldVector{4} from StaticArrays with named components px, py, pz, and E.
Because FourVector subtypes FieldVector, it behaves like a normal Julia vector: you can index it (p[1], p[1:3]), iterate over it, broadcast, and pass it anywhere an AbstractVector is expected.
The spatial three-momentum is available as a slice, p[1:3], without extra wrappers.
The type implements the LorentzVectorBase.jl interface, so kinematic quantities such as invariant mass, transverse momentum, and pseudorapidity are computed through shared accessors. A subset of those accessors is re-exported from this module; see below.
Julia already has several Lorentz-vector libraries. Two that are often used in HEP workflows are:
- LorentzVectors.jl — lightweight, registered package with
LorentzVector/Vec4andSpatialVector/Vec3, Minkowski inner products, boosts, and related algebra. - LorentzVectorHEP.jl — HEP-oriented layer built on LorentzVectors.jl, adding cylindrical coordinates (
LorentzVectorCyl) and common analysis helpers (ΔR,mt, and similar).
The package is not registered yet. Install from GitHub:
julia> ] add https://github.com/JuliaHEP/FourVectors.jlFull API reference and tutorials are on the Documenter site.
Tutorials are plain Julia scripts in literate/tutorials/ and woven into the manual with Literate.jl when the docs build runs docs/make.jl.
using FourVectorsGive three-momentum (px, py, pz) and exactly one of energy E or invariant mass M:
p = FourVector(1.0, 2.0, 3.0; E = 4.0)
p = FourVector(1.0, 2.0, 3.0; M = sqrt(2))Named fields:
px = p.px
py = p.py
pz = p.pz
E = p.EInteger indexing follows (px, py, pz, E):
px = p[1]
py = p[2]
pz = p[3]
E = p[4]
momentum = p[1:3] # spatial part as a 3-vectorAfter using FourVectors, these LorentzVectorBase functions are exported:
| Name |
|---|
transverse_momentum, spatial_magnitude, mass, mass2 |
boost_beta, boost_gamma, rapidity, polar_angle |
cos_theta, cos_phi, sin_phi, azimuthal_angle, pseudorapidity |
Example:
m = mass(p)
pt = transverse_momentum(p)
eta_pr = pseudorapidity(p)
phi = azimuthal_angle(p)
θ = polar_angle(p)LorentzVectorBase also provides shorter aliases (pt, phi, eta, and others) and additional methods (light-cone components, transverse mass, and more).
Those are available as LorentzVectorBase.name(p) unless you import them yourself.
See the LorentzVectorBase documentation for the full interface.
This package additionally exports spherical_coordinates, which returns a named tuple (cosθ, ϕ) for the spatial direction.
Exported transforms: Rx, Ry, Rz, Bz, transform_to_cmf, rotate_to_plane.
Rotations are active rotations about the lab x, y, and z axes:
p_rx = Rx(p, α)
p_ry = Ry(p, θ)
p_rz = Rz(p, ϕ)Longitudinal boost along lab z with Lorentz factor γ (flip the sign of γ for the opposite direction):
p_bz = Bz(p, γ)Partial application works in pipelines, e.g. p |> Rx(ϕ).
Contributions are welcome — please open issues or pull requests on GitHub.
MIT License.