Skip to content

Commit d39c215

Browse files
author
Uwe Hernandez Acosta
committed
added tutorial for four vectors + formatting
1 parent 8c2cfa6 commit d39c215

File tree

7 files changed

+345
-73
lines changed

7 files changed

+345
-73
lines changed

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ using Pkg
1717
Pkg.add("LorentzVectorBase")
1818
```
1919

20+
Alternatively, in the Julia REPL, enter `pkg>` mode by typing `]`, then
21+
22+
```julia-repl
23+
add LorentzVectorBase
24+
```
25+
2026
## Usage
2127

2228
This package defines abstract interfaces for Lorentz vectors. To utilize concrete implementations, consider packages like [LorentzVectorHEP.jl](https://github.com/JuliaHEP/LorentzVectorHEP.jl) or [FourVectors.jl](https://github.com/mmikhasenko/FourVectors.jl).

‎docs/Project.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
[deps]
22
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
34
LorentzVectorBase = "592a752d-6533-4762-a71b-738712ea30ec"

‎docs/make.jl‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Pkg.develop(; path=project_path)
77

88
using LorentzVectorBase
99
using Documenter
10+
using Literate
1011

1112
DocMeta.setdocmeta!(
1213
LorentzVectorBase, :DocTestSetup, :(using LorentzVectorBase); recursive=true
@@ -29,11 +30,22 @@ open(readme_path, "r") do readme_in
2930
end
3031
end
3132

33+
# setup examples using Literate.jl
34+
literate_paths = [
35+
Base.Filesystem.joinpath(project_path, "docs/src/tutorial/20-new_four_vector.jl")
36+
]
37+
38+
tutorial_output_dir = joinpath(project_path, "docs/src/generated/")
39+
!ispath(tutorial_output_dir) && mkdir(tutorial_output_dir)
40+
@info "Literate: create temp dir at $tutorial_output_dir"
41+
42+
tutorial_output_dir_name = splitpath(tutorial_output_dir)[end]
43+
3244
pages = [
3345
"Home" => "index.md",
3446
"Interface" => "10-interface.md",
3547
"Tutorial" => [
36-
"New Four-Vector" => "tutorial/20-new_four_vector.md",
48+
"New Four-Vector" => joinpath(tutorial_output_dir_name, "20-new_four_vector.md"),
3749
"New Coordinate System" => "tutorial/21-new_coord_system.md",
3850
],
3951
"Contributors guide" => "90-contributing.md",
@@ -42,6 +54,11 @@ pages = [
4254
]
4355

4456
try
57+
58+
# generate markdown files with Literate.jl
59+
for file in literate_paths
60+
Literate.markdown(file, tutorial_output_dir; documenter=true)
61+
end
4562
makedocs(;
4663
modules=[LorentzVectorBase],
4764
authors="Uwe Hernandez Acosta <[email protected]>",
@@ -57,10 +74,12 @@ try
5774
pages=pages,
5875
)
5976

77+
deploydocs(; repo="github.com/JuliaHEP/LorentzVectorBase.jl", push_preview=true)
6078
finally
6179
# doing some garbage collection
6280
@info "GarbageCollection: remove generated landing page"
6381
rm(index_path)
64-
end
6582

66-
deploydocs(; repo="github.com/JuliaHEP/LorentzVectorBase.jl", push_preview=true)
83+
@info "GarbageCollection: remove generated tutorial files"
84+
rm(tutorial_output_dir; recursive=true)
85+
end

‎docs/src/10-interface.md‎

Lines changed: 132 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,156 @@
1-
# [Interface](@id interface)
1+
```@meta
2+
CurrentModule = LorentzVectorBase
3+
```
24

3-
The main purpose of `LorentzVectorBase` is to provide a general interface for _Julia
4-
objects with Lorentz vector informations_. This means one implements a minimal set of
5-
accessor functions, specified by a _coordinate system_, and `LorentzVectorBase` provides
6-
implementations for a whole suite of additional accessor functions.
5+
# `LorentzVectorBase` Interface
76

8-
## Definition
7+
The `LorentzVectorBase` package defines a **common interface for
8+
LorentzVectorBase-compliant types** in Julia. This interface allows developers to define
9+
their own custom four-vector types (e.g., for particles or kinematic configurations) and
10+
automatically gain access to a large suite of common kinematic computations.
911

10-
A type that adheres to the interface described in this section will be referred to as
11-
_`LorentzVectorBase`-compliant_. A package providing such a type will be called _the provider_.
12+
## Purpose
1213

13-
## Coordinate Systems
14+
The main goal is to provide a lightweight abstraction that enables:
1415

15-
The provider must define a preferred coordinate system for its _`KinematicInterface`-compliant_
16-
type and provide accessors for the components of this system using standardized methods
17-
(outlined below). If the object natively supports multiple coordinate systems, the provider
18-
should choose the one in which component access is the most efficient as the _preferred
19-
coordinate system_. This system must be one of the supported options.
16+
- Interoperability between different packages using Lorentz vectors
17+
- Automatic derivation of many derived quantities (e.g. $p_T$, $\eta$, $m$) from a minimal interface
18+
- Coordinate system flexibility while maintaining performance
2019

21-
The `LorentzVectorBase` package supplements these component accessors to cover all supported
22-
coordinate systems. It uses the components of the _preferred coordinate system_ to implement
23-
complementary accessors. Julia’s dispatch mechanism prioritizes the accessors provided by
24-
the object itself.
20+
## Defining a Lorentz-Vector-Like Type
2521

26-
!!! note
22+
To make your type compliant with `LorentzVectorBase`, you must:
2723

28-
A `KinematicInterface`-compliant type can store additional data beyond the four-vector. For instance,
29-
a type representing an elementary particle may comply while containing more information than
30-
just the particle’s four-momentum.
24+
1. **Assign a coordinate system** using:
3125

32-
## Implementation
26+
```julia
27+
LorentzVectorBase.coordinate_system(::Type{MyVector}) = XYZT()
28+
```
3329

34-
A type `MyLorentzVector` (which do not necessary need to be a vector) will comply with the `KinematicInterface` if it implements
35-
one of the following sets of methods:
30+
Coordinate systems are tagged using constructors like `XYZT()`, `PtEtaPhiE()`, etc. These indicate how the four components are interpreted.
3631

37-
### Option 1: Position with Cartesian Coordinates
32+
2. **Implement the four accessors required by the chosen coordinate system**.
33+
For example, with `XYZT()`:
3834

39-
| Required Methods | Brief Description |
40-
| --------------------------------------------------------------------------------------- | ----------------------------------------------- |
41-
| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface |
42-
| `LorentzVectorBase.coordinate_system(::Type{MyLorentzVector}) = LorentzVectorBase.XYZE` | Declare the preferred coordinate system |
43-
| `LorentzVectorBase.x(::MyLorentzVector)` | X Cartesian coordinate |
44-
| `LorentzVectorBase.y(::MyLorentzVector)` | Y Cartesian coordinate |
45-
| `LorentzVectorBase.z(::MyLorentzVector)` | Z Cartesian coordinate |
46-
| `LorentzVectorBase.t(::MyLorentzVector)` | Time coordinate (t) |
35+
```julia
36+
x(::MyVector)
37+
y(::MyVector)
38+
z(::MyVector)
39+
t(::MyVector)
40+
```
4741

48-
### Option 2: Four-Momentum with Cartesian Coordinates
42+
You can inspect the required accessors for a given coordinate system using:
4943

50-
| Required Methods | Brief Description |
51-
| --------------------------------------------------------------------------------------- | ----------------------------------------------- |
52-
| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface |
53-
| `LorentzVectorBase.coordinate_system(::Type{MyLorentzVector}) = LorentzVectorBase.XYZE` | Declare the preferred coordinate system |
54-
| `LorentzVectorBase.px(::MyLorentzVector)` | Momentum X-component |
55-
| `LorentzVectorBase.py(::MyLorentzVector)` | Momentum Y-component |
56-
| `LorentzVectorBase.pz(::MyLorentzVector)` | Momentum Z-component |
57-
| `LorentzVectorBase.energy(::MyLorentzVector)` | Energy |
44+
```julia
45+
coordinate_system(XYZT()) # returns (:x, :y, :z, :t)
46+
```
5847

59-
### Option 3: Four-Momentum with Cylindrical Coordinates
48+
This indicates which component accessors your type must implement to be compliant with that system.
6049

61-
| Required Methods | Brief Description |
62-
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
63-
| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface |
64-
| `LorentzVectorBase.coordinate_system(::Type{MyLorentzVector})` | Declare the preferred coordinate system, which must return `PtEtaPhiM`, `PtEtaPhiE`, `PtYPhiM`, or `PtYPhiE` (from `LorentzVectorBase`) |
65-
| `LorentzVectorBase.pt(::MyLorentzVector)` | Transverse momentum |
66-
| `LorentzVectorBase.phi(::MyLorentzVector)` | Azimuthal angle |
50+
That's it! Once those are defined, the `LorentzVectorBase` package will automatically
51+
provide implementations for a wide variety of additional kinematic functions and
52+
coordinate conversions.
6753

68-
Additionally, you must implement _one_ of the following:
54+
## What You Get Automatically
6955

70-
| Required Method | Description |
71-
| ----------------------------------------------- | ------------------------------------------- |
72-
| `LorentzVectorBase.eta(::MyLorentzVector)` | Pseudorapidity |
73-
| `LorentzVectorBase.rapidity(::MyLorentzVector)` | Rapidity relative to the beam axis (z-axis) |
56+
Once a minimal interface is implemented, the following functions become available (among others), categorized by topic:
7457

75-
And _one_ of:
58+
### Cartesian Components
7659

77-
| Required Method | Description |
78-
| --------------------------------------------- | -------------- |
79-
| `LorentzVectorBase.energy(::MyLorentzVector)` | Energy |
80-
| `LorentzVectorBase.mass(::MyLorentzVector)` | Invariant mass |
60+
- [`x`](@ref), [`y`](@ref), [`z`](@ref), [`t`](@ref)
61+
- [`px`](@ref), [`py`](@ref), [`pz`](@ref), [`E`](@ref)
8162

82-
The methods returning the coordinates of the preferred system (as specified by `coordinate_system()`) must be implemented.
63+
### Spherical and Cylindrical Coordinates
8364

84-
## Optional Methods
65+
- [`spatial_magnitude`](@ref), [`spatial_magnitude2`](@ref)
66+
- [`polar_angle`](@ref), [`cos_theta`](@ref)
67+
- [`phi`](@ref), [`cos_phi`](@ref), [`sin_phi`](@ref)
8568

86-
| Optional Method | Description |
87-
| -------------------------------------------- | -------------------------------------------- |
88-
| `LorentzVectorBase.mass2(::MyLorentzVector)` | Square of the mass |
89-
| `LorentzVectorBase.rho2(::MyLorentzVector)` | ρ² = \|**p**\|² (squared momentum magnitude) |
69+
### Mass and Invariant Quantities
9070

91-
Additionally, any method from another option (i.e., a method from Option Y when methods from Option X are provided) may also be implemented.
71+
- [`mass`](@ref), [`mass2`](@ref)
72+
- [`mt`](@ref), [`mt2`](@ref)
73+
- [`pt`](@ref), [`pt2`](@ref)
74+
75+
### Rapidity and Related Quantities
76+
77+
- [`eta`](@ref): pseudorapidity
78+
- [`rapidity`](@ref)
79+
80+
### Boost Parameters
81+
82+
- [`boost_beta`](@ref), [`boost_gamma`](@ref)
83+
84+
### Light-Cone Coordinates
85+
86+
- [`plus_component`](@ref), [`minus_component`](@ref)
87+
88+
### Accessor Aliases
89+
90+
To improve readability and interoperability, `LorentzVectorBase` provides a set of
91+
**aliases** for common physics terminology. These aliases map frequently used or
92+
alternative names to the canonical accessor functions.
93+
94+
For example, `energy` is an alias for `t`, and `invariant_mass` maps to `mass`.
95+
96+
```julia
97+
energy(lv) === t(lv)
98+
invariant_mass(lv) === mass(lv)
99+
transverse_momentum(lv) === pt(lv)
100+
```
101+
102+
This allows users to choose more descriptive or domain-specific terminology without losing compatibility.
103+
104+
### Available Aliases
105+
106+
| Alias | Canonical Function |
107+
| ---------------------- | ------------------ |
108+
| `energy` | `t` |
109+
| `invariant_mass` | `mass` |
110+
| `invariant_mass2` | `mass2` |
111+
| `transverse_momentum` | `pt` |
112+
| `transverse_momentum2` | `pt2` |
113+
| `perp` | `pt` |
114+
| `perp2` | `pt2` |
115+
| `transverse_mass` | `mt` |
116+
| `transverse_mass2` | `mt2` |
117+
| `azimuthal_angle` | `phi` |
118+
| `pseudorapidity` | `eta` |
119+
120+
## Coordinate System Tags
121+
122+
The following coordinate systems are supported via tags like `XYZT()`, `PtEtaPhiM()`, etc.:
123+
124+
- `XYZT`, `PxPyPzE` — position/time or cartesian four-momentum
125+
- `PtEtaPhiM` — common in collider physics
126+
127+
Each tag specifies which component names (`x`, `pt`, `eta`, etc.) you must implement.
128+
129+
## Example
130+
131+
```julia
132+
struct MyVector
133+
px::Float64
134+
py::Float64
135+
pz::Float64
136+
E::Float64
137+
end
138+
139+
LorentzVectorBase.coordinate_system(::Type{MyVector}) = XYZE()
140+
141+
LorentzVectorBase.px(v::MyVector) = v.px
142+
LorentzVectorBase.py(v::MyVector) = v.py
143+
LorentzVectorBase.pz(v::MyVector) = v.pz
144+
LorentzVectorBase.energy(v::MyVector) = v.E
145+
```
146+
147+
Now your type supports:
148+
149+
```julia
150+
mass(MyVector(...))
151+
eta(MyVector(...))
152+
pt(MyVector(...))
153+
phi(MyVector(...))
154+
```
155+
156+
without implementing them manually.

0 commit comments

Comments
 (0)