From e10831af496848f2888c74fd02eeaaec640d20ce Mon Sep 17 00:00:00 2001
From: Uwe Hernandez Acosta <u.hernandez@hzdr.de>
Date: Tue, 12 Nov 2024 14:54:22 +0100
Subject: [PATCH] added docstring for flat phase space layout, added RAMBO
 reference

---
 docs/Bibliography.bib                         | 10 ++++++
 docs/Project.toml                             |  1 +
 docs/make.jl                                  |  7 +++-
 docs/src/library/phase_space_layout.md        | 12 +++++++
 docs/src/refs.md                              |  5 +++
 .../out_channel/flat_phase_space.jl           | 32 +++++++++++++++++++
 6 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 docs/Bibliography.bib
 create mode 100644 docs/src/refs.md

diff --git a/docs/Bibliography.bib b/docs/Bibliography.bib
new file mode 100644
index 0000000..0df6d14
--- /dev/null
+++ b/docs/Bibliography.bib
@@ -0,0 +1,10 @@
+@article{Kleiss:1985gy,
+    author = "Kleiss, R. and Stirling, W. James and Ellis, S. D.",
+    title = "{A New Monte Carlo Treatment of Multiparticle Phase Space at High-energies}",
+    reportNumber = "CERN-TH-4299/85",
+    doi = "10.1016/0010-4655(86)90119-0",
+    journal = "Comput. Phys. Commun.",
+    volume = "40",
+    pages = "359",
+    year = "1986"
+}
diff --git a/docs/Project.toml b/docs/Project.toml
index 70df872..ab431bb 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,6 +1,7 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 QEDbase = "10e22c08-3ccb-4172-bfcf-7d7aa3d04d93"
diff --git a/docs/make.jl b/docs/make.jl
index dbbeab0..7c590ef 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -11,6 +11,7 @@ using QEDprocesses
 
 using Documenter
 using DocumenterInterLinks
+using DocumenterCitations
 using Literate
 
 # setup interlinks
@@ -21,6 +22,9 @@ links = InterLinks(
     "QEDprocesses" => "https://qedjl-project.github.io/QEDprocesses.jl/dev/",
 )
 
+# add Bibliography
+bib = CitationBibliography(joinpath(@__DIR__, "Bibliography.bib"))
+
 # some paths for links
 readme_path = joinpath(project_path, "README.md")
 index_path = joinpath(project_path, "docs/src/index.md")
@@ -70,6 +74,7 @@ pages = [
         "Lorentz Boosts" => "library/lorentzboosts.md",
         "Index" => "library/index.md",
     ],
+    "refs.md",
 ]
 
 try
@@ -91,7 +96,7 @@ try
             assets=String[],
         ),
         pages=pages,
-        plugins=[links],
+        plugins=[bib, links],
     )
 finally
     # doing some garbage collection
diff --git a/docs/src/library/phase_space_layout.md b/docs/src/library/phase_space_layout.md
index 1115d91..1dee80b 100644
--- a/docs/src/library/phase_space_layout.md
+++ b/docs/src/library/phase_space_layout.md
@@ -37,3 +37,15 @@ AbstractTwoBodyInPhaseSpaceLayout
 AbstractTwoBodyRestSystem
 TwoBodyRestSystem
 ```
+
+### Flat Phase Space Layout
+
+```@docs
+FlatPhaseSpaceLayout
+_massive_rambo_moms
+_find_scaling_factor
+_single_rambo_mom
+_tuple_partition_by_four
+_unconserved_momenta
+_massless_rambo_moms
+```
diff --git a/docs/src/refs.md b/docs/src/refs.md
new file mode 100644
index 0000000..a1d3637
--- /dev/null
+++ b/docs/src/refs.md
@@ -0,0 +1,5 @@
+# References
+
+```@bibliography
+
+```
diff --git a/src/phase_space_layouts/out_channel/flat_phase_space.jl b/src/phase_space_layouts/out_channel/flat_phase_space.jl
index f8968a2..43f84e7 100644
--- a/src/phase_space_layouts/out_channel/flat_phase_space.jl
+++ b/src/phase_space_layouts/out_channel/flat_phase_space.jl
@@ -1,5 +1,37 @@
 # here we implement RAMBO
 
+"""
+    FlatPhaseSpaceLayout{INPSL} <: QEDcore.AbstractOutPhaseSpaceLayout{INPSL}
+
+Defines a flat phase space layout for generating outgoing particle momenta. This layout assumes
+that outgoing particles are uniformly distributed in phase space, subject to constraints on
+momentum and energy conservation. This is accomplished by exploiting the RAMBO [Kleiss:1985gy](@cite) (Random Momenta Beautifully Organized)
+algorithm to generate the momenta, supporting both massless
+and massive particles.
+
+# Fields
+- `in_psl::INPSL`: Input phase space layout, which provides the initial state layout for the
+  process. This field links to the input configuration, making it accessible for consistency
+  across related calculations.
+
+# Usage
+`FlatPhaseSpaceLayout` is commonly used in high-energy physics to define phase space configurations
+for event generators and cross-section calculations. Key functions include:
+- `QEDcore.phase_space_dimension`: Calculates the phase space dimension based on the number of
+  outgoing particles.
+- `QEDcore._build_momenta`: Constructs the outgoing momenta using the provided phase space layout
+  and RAMBO-based algorithms, ensuring the momenta satisfy energy and momentum conservation laws.
+
+# Example
+```julia
+# Define input and process information, model, and input coordinates
+psl = FlatPhaseSpaceLayout(input_psl)
+build_momenta(process, model, incoming_momenta, psl, out_coords)
+```
+
+`FlatPhaseSpaceLayout` provides a robust setup for defining the final-state phase space in particle
+physics simulations, allowing for modularity and compatibility with `QEDcore` routines.
+"""
 struct FlatPhaseSpaceLayout{INPSL} <: QEDcore.AbstractOutPhaseSpaceLayout{INPSL}
     in_psl::INPSL
 end