From d61a4be884c34fcc801f9c886b7d7d423d4bb139 Mon Sep 17 00:00:00 2001 From: Rubydragon Date: Tue, 1 Oct 2024 17:55:53 +0200 Subject: [PATCH 1/9] Add the library reference and index manually in a proper structure --- README.md | 34 +++++++++++++- docs/Project.toml | 1 + docs/make.jl | 71 +++++++++++++++++++++++------ docs/src/index.md | 14 ------ docs/src/library/outline.md | 10 ++++ docs/src/library/particles.md | 25 ++++++++++ docs/src/library/phasespacedef.md | 22 +++++++++ docs/src/library/phasespacepoint.md | 14 ++++++ docs/src/library/vectors.md | 38 +++++++++++++++ 9 files changed, 200 insertions(+), 29 deletions(-) delete mode 100644 docs/src/index.md create mode 100644 docs/src/library/outline.md create mode 100644 docs/src/library/particles.md create mode 100644 docs/src/library/phasespacedef.md create mode 100644 docs/src/library/phasespacepoint.md create mode 100644 docs/src/library/vectors.md diff --git a/README.md b/README.md index 6f8ae43..07d7309 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# QEDcore +# QEDcore.jl [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://QEDjl-project.github.io/QEDcore.jl/stable/) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://QEDjl-project.github.io/QEDcore.jl/dev/) @@ -6,3 +6,35 @@ [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle) This package is part of the `QuantumElectrodynamics.jl` library. For the description of the interoperability with other packages of `QuantumElectrodynamics.jl` see [docs](https://qedjl-project.github.io/QuantumElectrodynamics.jl/dev/). + +## Contributing + +Contributions are welcome! If you'd like to report a bug, suggest an enhancement, or contribute +code, please feel free to open an issue or submit a pull request. + +To ensure consistency across the `QuantumElectrodynamics.jl` ecosystem, we encourage all contributors +to review the [QuantumElectrodynamics.jl contribution guide](https://qedjl-project.github.io/QuantumElectrodynamics.jl/stable/dev_guide/#Development-Guide). + +## Credits and contributors + +This work was partly funded by the Center for Advanced Systems Understanding (CASUS) that +is financed by Germany’s Federal Ministry of Education and Research (BMBF) and by the Saxon +Ministry for Science, Culture and Tourism (SMWK) with tax funds on the basis of the budget +approved by the Saxon State Parliament. + +The core code of the package `QEDcore.jl` is developed by a small team at the Center for +Advanced Systems Understanding ([CASUS](https://www.casus.science)), namely + +### Core Contributors + +- **Uwe Hernandez Acosta** (CASUS/HZDR, [u.hernandez@hzdr.de](mailto:u.hernandez@hzdr.de)) +- **Anton Reinhard** (CASUS/HZDR) +- **Simeon Ehrig** (CASUS/HZDR) + +### Former Contributors + +We extend our sincere thanks to all contributors who have supported this project. + +## License + +[MIT](LICENSE) © Uwe Hernandez Acosta diff --git a/docs/Project.toml b/docs/Project.toml index 5ba0196..6edf6ee 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,6 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656" QEDbase = "10e22c08-3ccb-4172-bfcf-7d7aa3d04d93" QEDcore = "35dc0263-cb5f-4c33-a114-1d7f54ab753e" QEDprocesses = "46de9c38-1bb3-4547-a1ec-da24d767fdad" diff --git a/docs/make.jl b/docs/make.jl index 91cc8b4..8702cc1 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -5,23 +5,66 @@ using Pkg project_path = Base.Filesystem.joinpath(Base.Filesystem.dirname(Base.source_path()), "..") Pkg.develop(; path=project_path) -Pkg.add(; url="https://github.com/QEDjl-project/QEDbase.jl/", rev="dev") - +using QEDbase using QEDcore +using QEDprocesses + using Documenter +using DocumenterInterLinks -# DocMeta.setdocmeta!(QEDcore, :DocTestSetup, :(using QEDcore); recursive=true) - -makedocs(; - modules=[QEDcore], - authors="Uwe Hernandez Acosta ", - sitename="QEDcore.jl", - format=Documenter.HTML(; - canonical="https://QEDjl-project.github.io/QEDcore.jl", - edit_link="main", - assets=String[], - ), - pages=["Home" => "index.md"], +# setup interlinks +links = InterLinks( + "QuantumElectrodynamics" => "https://qedjl-project.github.io/QuantumElectrodynamics.jl/dev/", + "QEDbase" => "https://qedjl-project.github.io/QEDbase.jl/dev/", + "QEDcore" => "https://qedjl-project.github.io/QEDcore.jl/dev/", + "QEDprocesses" => "https://qedjl-project.github.io/QEDprocesses.jl/dev/", ) +# some paths for links +readme_path = joinpath(project_path, "README.md") +index_path = joinpath(project_path, "docs/src/index.md") +license_path = "https://github.com/QEDjl-project/QEDcore.jl/blob/main/LICENSE" + +# Copy README.md from the project base folder and use it as the start page +open(readme_path, "r") do readme_in + readme_string = read(readme_in, String) + + # replace relative links in the README.md + readme_string = replace(readme_string, "[MIT](LICENSE)" => "[MIT]($(license_path))") + + open(index_path, "w") do readme_out + write(readme_out, readme_string) + end +end + +pages = [ + "Home" => "index.md", + "API reference" => [ + "Contents" => "library/outline.md", + "Particles" => "library/particles.md", + "Phase Space Definition" => "library/phasespacedef.md", + "Phase Space Points" => "library/phasespacepoint.md", + "Vector Types" => "library/vectors.md", + ], +] + +try + makedocs(; + modules=[QEDcore], + checkdocs=:exports, + authors="Uwe Hernandez Acosta", + repo=Documenter.Remotes.GitHub("QEDjl-project", "QEDcore.jl"), + sitename="QEDcore.jl", + format=Documenter.HTML(; + prettyurls=get(ENV, "CI", "false") == "true", + canonical="https://qedjl-project.gitlab.io/QEDcore.jl", + assets=String[], + ), + pages=pages, + ) +finally + @info "Garbage collection: remove landing page" + rm(index_path) +end + deploydocs(; repo="github.com/QEDjl-project/QEDcore.jl", push_preview=false) diff --git a/docs/src/index.md b/docs/src/index.md deleted file mode 100644 index da47691..0000000 --- a/docs/src/index.md +++ /dev/null @@ -1,14 +0,0 @@ -```@meta -CurrentModule = QEDcore -``` - -# QEDcore - -Documentation for [QEDcore](https://github.com/QEDjl-project/QEDcore.jl). - -```@index -``` - -```@autodocs -Modules = [QEDcore] -``` diff --git a/docs/src/library/outline.md b/docs/src/library/outline.md new file mode 100644 index 0000000..44e7d82 --- /dev/null +++ b/docs/src/library/outline.md @@ -0,0 +1,10 @@ +```@meta +CurrentModule = QEDcore +``` + +# QEDcore + +API index for [QEDcore](https://github.com/QEDjl-project/QEDcore.jl). + +```@index +``` diff --git a/docs/src/library/particles.md b/docs/src/library/particles.md new file mode 100644 index 0000000..57fc097 --- /dev/null +++ b/docs/src/library/particles.md @@ -0,0 +1,25 @@ +# Particles + +## Particle Types + +The following are subtypes of `QEDbase.AbstractParticleType`(@extref). + +For all these types the corresponding interface is implemented, including `QEDbase.base_state`(@extref) and `QEDbase.propagator`(@extref). + +```@meta +CurrentModule = QEDcore +``` + +```@docs +FermionLike +BosonLike +MajoranaFermion +MajoranaBoson +Fermion +Boson +AntiFermion +AntiBoson +Electron +Positron +Photon +``` diff --git a/docs/src/library/phasespacedef.md b/docs/src/library/phasespacedef.md new file mode 100644 index 0000000..af588b5 --- /dev/null +++ b/docs/src/library/phasespacedef.md @@ -0,0 +1,22 @@ +# Phase Space Definitions + +```@meta +CurrentModule = QEDcore +``` + +## Phase Space Definition Type +```@docs +PhasespaceDefinition +``` + +## Frames of Reference +```@docs +CenterOfMomentumFrame +ElectronRestFrame +``` + +## Coordinate Systems + +```@docs +SphericalCoordinateSystem +``` diff --git a/docs/src/library/phasespacepoint.md b/docs/src/library/phasespacepoint.md new file mode 100644 index 0000000..44565b7 --- /dev/null +++ b/docs/src/library/phasespacepoint.md @@ -0,0 +1,14 @@ +# Phase Space Points + +```@meta +CurrentModule = QEDcore +``` + +```@docs +ParticleStateful +PhaseSpacePoint +InPhaseSpacePoint +OutPhaseSpacePoint +getindex +_momentum_type +``` diff --git a/docs/src/library/vectors.md b/docs/src/library/vectors.md new file mode 100644 index 0000000..6c58fec --- /dev/null +++ b/docs/src/library/vectors.md @@ -0,0 +1,38 @@ +# Vector and Matrix Types + +```@meta +CurrentModule = QEDcore +``` + +## 4-Momenta +```@docs +SFourMomentum +MFourMomentum +``` + +## Spinors +```@docs +BiSpinor +AdjointBiSpinor +``` + +## Lorentz Vectors +```@docs +SLorentzVector +MLorentzVector +``` + +## Dirac Matrix +```@docs +DiracMatrix +``` + +## Multiplications +```@docs +_mul +``` + +## Deprecated +```@docs +AbstractParticleSpinor +``` From 680cc14abc08b3f79666afaff5c6f766c44f6071 Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Wed, 9 Oct 2024 12:39:28 +0200 Subject: [PATCH 2/9] Add small readme section --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 07d7309..48ff7b9 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ This package is part of the `QuantumElectrodynamics.jl` library. For the description of the interoperability with other packages of `QuantumElectrodynamics.jl` see [docs](https://qedjl-project.github.io/QuantumElectrodynamics.jl/dev/). +This package's main purpose is to provide implementations of the basic interfaces defined in [`QEDbase.jl`](https://github.com/QEDjl-project/QEDbase.jl), such as various particle types, `PhasespaceDefinition`, `PhaseSpacePoint`, and various vector and matrix types. These types are used across most of the QEDjl-project repositories. For detailed information on these types, please refer to the respective pages in the [docs](https://qedjl-project.github.io/QEDcore.jl/dev/). + ## Contributing Contributions are welcome! If you'd like to report a bug, suggest an enhancement, or contribute From 3aabb68811d63adf4730de2a7edbecb8016e8c97 Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Wed, 9 Oct 2024 12:41:03 +0200 Subject: [PATCH 3/9] Remove currently non-functional build status badge --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 48ff7b9..fefdef9 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://QEDjl-project.github.io/QEDcore.jl/stable/) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://QEDjl-project.github.io/QEDcore.jl/dev/) -[![Build Status](https://github.com/QEDjl-project/QEDcore.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/QEDjl-project/QEDcore.jl/actions/workflows/CI.yml?query=branch%3Amain) [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle) This package is part of the `QuantumElectrodynamics.jl` library. For the description of the interoperability with other packages of `QuantumElectrodynamics.jl` see [docs](https://qedjl-project.github.io/QuantumElectrodynamics.jl/dev/). From 03849f7516f0129595af8f3790cdc9cc7e4179dc Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Wed, 9 Oct 2024 19:01:08 +0200 Subject: [PATCH 4/9] Add literals.jl page --- .gitignore | 3 +++ docs/Project.toml | 1 + docs/make.jl | 18 ++++++++++++++++ docs/src/library/index.md | 10 +++++++++ docs/src/library/outline.md | 11 +++------- docs/src/library/phasespacepoint.md | 5 +++++ docs/src/particles_manual.jl | 32 +++++++++++++++++++++++++++++ 7 files changed, 72 insertions(+), 8 deletions(-) create mode 100644 docs/src/library/index.md create mode 100644 docs/src/particles_manual.jl diff --git a/.gitignore b/.gitignore index 493f309..ede1f09 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ *Manifest.toml docs/build/ + +docs/src/particles_manual.ipynb +docs/src/particles_manual.md diff --git a/docs/Project.toml b/docs/Project.toml index 6edf6ee..59bb9aa 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,6 +1,7 @@ [deps] Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656" +Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" QEDbase = "10e22c08-3ccb-4172-bfcf-7d7aa3d04d93" QEDcore = "35dc0263-cb5f-4c33-a114-1d7f54ab753e" QEDprocesses = "46de9c38-1bb3-4547-a1ec-da24d767fdad" diff --git a/docs/make.jl b/docs/make.jl index 8702cc1..b3d244e 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -37,14 +37,31 @@ open(readme_path, "r") do readme_in end end +# setup examples using Literate.jl +using Literate + +literate_paths = [ + ( + Base.Filesystem.joinpath(project_path, "docs/src/particles_manual.jl"), + Base.Filesystem.joinpath(project_path, "docs/src/"), + ), +] + +for (file, output_dir) in literate_paths + Literate.markdown(file, output_dir; documenter=true) + Literate.notebook(file, output_dir) +end + pages = [ "Home" => "index.md", + "Particles and Phase Space Points" => "particles_manual.md", "API reference" => [ "Contents" => "library/outline.md", "Particles" => "library/particles.md", "Phase Space Definition" => "library/phasespacedef.md", "Phase Space Points" => "library/phasespacepoint.md", "Vector Types" => "library/vectors.md", + "Index" => "library/index.md", ], ] @@ -61,6 +78,7 @@ try assets=String[], ), pages=pages, + plugins=[links], ) finally @info "Garbage collection: remove landing page" diff --git a/docs/src/library/index.md b/docs/src/library/index.md new file mode 100644 index 0000000..44e7d82 --- /dev/null +++ b/docs/src/library/index.md @@ -0,0 +1,10 @@ +```@meta +CurrentModule = QEDcore +``` + +# QEDcore + +API index for [QEDcore](https://github.com/QEDjl-project/QEDcore.jl). + +```@index +``` diff --git a/docs/src/library/outline.md b/docs/src/library/outline.md index 44e7d82..bbffee8 100644 --- a/docs/src/library/outline.md +++ b/docs/src/library/outline.md @@ -1,10 +1,5 @@ -```@meta -CurrentModule = QEDcore -``` - -# QEDcore - -API index for [QEDcore](https://github.com/QEDjl-project/QEDcore.jl). +## API Outline -```@index +```@contents +Pages = ["particles.md", "phasespacedef.md", "phasespacepoint.md", "vectors.md"] ``` diff --git a/docs/src/library/phasespacepoint.md b/docs/src/library/phasespacepoint.md index 44565b7..08b35ca 100644 --- a/docs/src/library/phasespacepoint.md +++ b/docs/src/library/phasespacepoint.md @@ -4,11 +4,16 @@ CurrentModule = QEDcore ``` +## Types and Aliases ```@docs ParticleStateful PhaseSpacePoint InPhaseSpacePoint OutPhaseSpacePoint +``` + +## Accessors +```@docs getindex _momentum_type ``` diff --git a/docs/src/particles_manual.jl b/docs/src/particles_manual.jl new file mode 100644 index 0000000..bda35aa --- /dev/null +++ b/docs/src/particles_manual.jl @@ -0,0 +1,32 @@ +# # Particles and Phase Space Points + +# There are three layers of abstraction from particles to phase space points in the QEDjl project: +# - [`AbstractParticleType`](@extref QEDbase.AbstractParticleType): Base type for singleton particle type definitions. We also call these *species*. +# - [`AbstractParticleStateful`](@extref QEDbase.AbstractParticleStateful): Base type for particles with a direction and carrying a momentum. +# - [`AbstractPhaseSpacePoint`](@extref QEDbase.AbstractPhaseSpacePoint): Representation of a point in the phase space for a combination of an [`AbstractProcessDefinition`](@extref QEDbase.AbstractProcessDefinition), [`AbstractModelDefinition`](@extref QEDbase.AbstractModelDefinition), and [`AbstractPhasespaceDefinition`](@extref QEDbase.AbstractPhasespaceDefinition). + +# This manual is intended to showcase the basic usage of these types and their implementations in QEDcore. + +using QEDcore + +# To use concrete process definitions and models, we also need to use [`QEDprocesses.jl`](https://github.com/QEDjl-project/QEDprocesses.jl) + +using QEDprocesses + +# ## Particle Types + +# QEDcore currently defines the three basic particle types of QED [`Electron`](@ref), [`Positron`](@ref), and [`Photon`](@ref), and a type hierarchy for them: + +@assert Photon <: MajoranaBoson +@assert Electron <: Fermion +@assert Positron <: AntiFermion + +# There are also convenience functions in Julia convention: + +@assert is_boson(Photon()) +@assert is_particle(Electron()) +@assert is_anti_particle(Positron()) + +# These functions are part of QEDbase.jl's [particle interface](@extref QEDbase particles). + + From 8a266c0b770bbb4b4de0ddf2cc46e13ac5a4f1ab Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Fri, 11 Oct 2024 13:53:47 +0200 Subject: [PATCH 5/9] Remove ParticleSpinors from docs --- docs/src/library/vectors.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/src/library/vectors.md b/docs/src/library/vectors.md index 6c58fec..6072899 100644 --- a/docs/src/library/vectors.md +++ b/docs/src/library/vectors.md @@ -31,8 +31,3 @@ DiracMatrix ```@docs _mul ``` - -## Deprecated -```@docs -AbstractParticleSpinor -``` From b66332946581d25849b8b534f46308f5e44f90ee Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Fri, 11 Oct 2024 16:49:51 +0200 Subject: [PATCH 6/9] Finish particle documentation --- docs/Project.toml | 1 + docs/make.jl | 31 +++--- docs/src/particles_manual.jl | 32 ------ docs/src/tutorial/particles.jl | 172 +++++++++++++++++++++++++++++++++ 4 files changed, 191 insertions(+), 45 deletions(-) delete mode 100644 docs/src/particles_manual.jl create mode 100644 docs/src/tutorial/particles.jl diff --git a/docs/Project.toml b/docs/Project.toml index 59bb9aa..70df872 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,4 +1,5 @@ [deps] +BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" diff --git a/docs/make.jl b/docs/make.jl index b3d244e..a8ef9be 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -11,6 +11,7 @@ using QEDprocesses using Documenter using DocumenterInterLinks +using Literate # setup interlinks links = InterLinks( @@ -38,23 +39,18 @@ open(readme_path, "r") do readme_in end # setup examples using Literate.jl -using Literate +literate_paths = [Base.Filesystem.joinpath(project_path, "docs/src/tutorial/particles.jl")] -literate_paths = [ - ( - Base.Filesystem.joinpath(project_path, "docs/src/particles_manual.jl"), - Base.Filesystem.joinpath(project_path, "docs/src/"), - ), -] +tutorial_output_dir = joinpath(project_path, "docs/src/generated/") +!ispath(tutorial_output_dir) && mkdir(tutorial_output_dir) +@info "Literate: create temp dir at $tutorial_output_dir" -for (file, output_dir) in literate_paths - Literate.markdown(file, output_dir; documenter=true) - Literate.notebook(file, output_dir) -end +tutorial_output_dir_name = splitpath(tutorial_output_dir)[end] pages = [ "Home" => "index.md", - "Particles and Phase Space Points" => "particles_manual.md", + "Particles and Phase Space Points" => + joinpath(tutorial_output_dir_name, "particles.md"), "API reference" => [ "Contents" => "library/outline.md", "Particles" => "library/particles.md", @@ -66,6 +62,12 @@ pages = [ ] try + # generate markdown files with Literate.jl + for file in literate_paths + Literate.markdown(file, tutorial_output_dir; documenter=true) + end + # geneate docs with Documenter.jl + makedocs(; modules=[QEDcore], checkdocs=:exports, @@ -81,8 +83,11 @@ try plugins=[links], ) finally - @info "Garbage collection: remove landing page" + # doing some garbage collection + @info "GarbageCollection: remove generated landing page" rm(index_path) + @info "GarbageCollection: remove generated tutorial files" + rm(tutorial_output_dir; recursive=true) end deploydocs(; repo="github.com/QEDjl-project/QEDcore.jl", push_preview=false) diff --git a/docs/src/particles_manual.jl b/docs/src/particles_manual.jl deleted file mode 100644 index bda35aa..0000000 --- a/docs/src/particles_manual.jl +++ /dev/null @@ -1,32 +0,0 @@ -# # Particles and Phase Space Points - -# There are three layers of abstraction from particles to phase space points in the QEDjl project: -# - [`AbstractParticleType`](@extref QEDbase.AbstractParticleType): Base type for singleton particle type definitions. We also call these *species*. -# - [`AbstractParticleStateful`](@extref QEDbase.AbstractParticleStateful): Base type for particles with a direction and carrying a momentum. -# - [`AbstractPhaseSpacePoint`](@extref QEDbase.AbstractPhaseSpacePoint): Representation of a point in the phase space for a combination of an [`AbstractProcessDefinition`](@extref QEDbase.AbstractProcessDefinition), [`AbstractModelDefinition`](@extref QEDbase.AbstractModelDefinition), and [`AbstractPhasespaceDefinition`](@extref QEDbase.AbstractPhasespaceDefinition). - -# This manual is intended to showcase the basic usage of these types and their implementations in QEDcore. - -using QEDcore - -# To use concrete process definitions and models, we also need to use [`QEDprocesses.jl`](https://github.com/QEDjl-project/QEDprocesses.jl) - -using QEDprocesses - -# ## Particle Types - -# QEDcore currently defines the three basic particle types of QED [`Electron`](@ref), [`Positron`](@ref), and [`Photon`](@ref), and a type hierarchy for them: - -@assert Photon <: MajoranaBoson -@assert Electron <: Fermion -@assert Positron <: AntiFermion - -# There are also convenience functions in Julia convention: - -@assert is_boson(Photon()) -@assert is_particle(Electron()) -@assert is_anti_particle(Positron()) - -# These functions are part of QEDbase.jl's [particle interface](@extref QEDbase particles). - - diff --git a/docs/src/tutorial/particles.jl b/docs/src/tutorial/particles.jl new file mode 100644 index 0000000..ee55e96 --- /dev/null +++ b/docs/src/tutorial/particles.jl @@ -0,0 +1,172 @@ +# # Particles and Phase Space Points + +# There are three layers of abstraction from particles to phase space points in the QEDjl project: +# - [`AbstractParticleType`](@extref QEDbase.AbstractParticleType): Base type for singleton particle type definitions. We also call these *species*. +# - [`AbstractParticleStateful`](@extref QEDbase.AbstractParticleStateful): Base type for particles with a direction and carrying a momentum. +# - [`AbstractPhaseSpacePoint`](@extref QEDbase.AbstractPhaseSpacePoint): Representation of a point in the phase space for a combination of an [`AbstractProcessDefinition`](@extref QEDbase.AbstractProcessDefinition), [`AbstractModelDefinition`](@extref QEDbase.AbstractModelDefinition), and [`AbstractPhasespaceDefinition`](@extref QEDbase.AbstractPhasespaceDefinition). + +# This manual is intended to showcase the basic usage of these types and their implementations in QEDcore. + +using QEDcore + +# To use concrete process definitions and models, we also need to use [`QEDprocesses.jl`](https://github.com/QEDjl-project/QEDprocesses.jl) + +using QEDprocesses + +# ## Particle Types + +# QEDcore currently defines the three basic particle types of QED, [`Electron`](@ref), [`Positron`](@ref), and [`Photon`](@ref), and a type hierarchy for them: + +@assert Photon <: MajoranaBoson +@assert Electron <: Fermion +@assert Positron <: AntiFermion + +# All of these are subtypes of [`AbstractParticleType`](@extref QEDbase.AbstractParticleType). +# There are also convenience functions in Julia convention: + +@assert is_boson(Photon()) +@assert is_particle(Electron()) +@assert is_anti_particle(Positron()) + +@assert !is_boson(Electron()) +@assert !is_anti_particle(Electron()) +@assert !is_fermion(Photon()) + +# These functions are part of QEDbase.jl's (TODO: enable link once QEDbase docs are up)`[particle interface](@extref QEDbase particles)`. + +# ## ParticleStateful + +# [`ParticleStateful`](@ref) is the implementation of QEDbase's [`AbstractParticleStateful`](@extref QEDbase.AbstractParticleStateful) interface. It represents a particle with a [`direction`](@extref QEDbase.ParticleDirection) (as used in the context of scattering processes, [`Incoming`](@extref QEDbase.Incoming), [`Outgoing`](@extref QEDbase.Outgoing), or [`UnknownDirection`](@extref QEDbase.UnknownDirection)), a particle species ([`Electron`](@ref), [`Positron`](@ref), [`Photon`](@ref), ...), and a 4-momentum Vector. + +ps = ParticleStateful(Incoming(), Electron(), rand(SFourMomentum)) + +# The relevant accessor functions for the interface are implemented: + +particle_direction(ps) +# +particle_species(ps) +# +momentum(ps) +# + +# ## Phase Space Points + +# A [`PhaseSpacePoint`](@ref) is the combination of incoming and outgoing [`ParticleStateful`](@ref)s. It also contains information about the [scattering process](@extref QEDbase.AbstractProcessDefinition), [model](@extref QEDbase.AbstractModelDefinition), and [phase space](@extref QEDbase.AbstractPhasespaceDefinition) that it is created for. + +# ### Constructors + +psp = PhaseSpacePoint( + Compton(), # scattering process + PerturbativeQED(), # physics model + PhasespaceDefinition( # phase space definition + SphericalCoordinateSystem(),# coordinate system + ElectronRestFrame(), # frame of reference + ), + ( # momenta of the incoming particles + rand(SFourMomentum), + rand(SFourMomentum), + ), + ( # momenta of the outgoing particles + rand(SFourMomentum), + rand(SFourMomentum), + ), +) + +# This version of the constructor automatically creates [`ParticleStateful`](@ref) obejcts from the momenta, matching the particles of the process. In the case of [`Compton`](@extref QEDprocesses.Compton), this is means an incoming electron and photon, and outgoing electron and photon. + +# Automatic checks make sure that the number of 4-momenta given matches the necessary number of 4-momenta for the process (this adds 0 overhead at runtime because it is inferred from type information alone). + +try # hide + PhaseSpacePoint( + Compton(), + PerturbativeQED(), + PhasespaceDefinition(SphericalCoordinateSystem(), ElectronRestFrame()), + (rand(SFourMomentum),), # incorrect number of incoming momenta, should be 2 + (rand(SFourMomentum), rand(SFourMomentum)), + ) +catch e # hide + @error e # hide +end # hide + +# Alternatively, a [`PhaseSpacePoint`](@ref) can also be constructed from already existing [`ParticleStateful`](@ref) objects. + +psp = PhaseSpacePoint( + Compton(), # scattering process + PerturbativeQED(), # physics model + PhasespaceDefinition( # phase space definition + SphericalCoordinateSystem(),# coordinate system + ElectronRestFrame(), # frame of reference + ), + ( # incoming particles + ParticleStateful(Incoming(), Electron(), rand(SFourMomentum)), + ParticleStateful(Incoming(), Photon(), rand(SFourMomentum)), + ), + ( # outgoing particles + ParticleStateful(Outgoing(), Electron(), rand(SFourMomentum)), + ParticleStateful(Outgoing(), Photon(), rand(SFourMomentum)), + ), +) + +# Similar to the constructor from momenta, this checks that the given [`ParticleStateful`](@ref)s fit to the given process and throws otherwise. Again, since this can be infered from type information alone, it adds no overhead. + +try # hide + PhaseSpacePoint( + Compton(), + PerturbativeQED(), + PhasespaceDefinition(SphericalCoordinateSystem(), ElectronRestFrame()), + ( # incoming particles + ParticleStateful(Incoming(), Positron(), rand(SFourMomentum)), # incorrect particle type + ParticleStateful(Incoming(), Photon(), rand(SFourMomentum)), + ), + ( # outgoing particles + ParticleStateful(Outgoing(), Electron(), rand(SFourMomentum)), + ParticleStateful(Outgoing(), Photon(), rand(SFourMomentum)), + ), + ) +catch e # hide + @error e # hide +end # hide + +# !!! note +# While these constructors check that the given types make sense and work together, they do *not* check whether the given momenta make a physical phase space point or that the incoming or outgoing particles have on-shell 4-momenta. + +# ### Accessors + +# The phase space point provides some convenient accessors to the stateful particles within: + +psp[Incoming(), 1] # the first incoming particle +# +psp[Outgoing(), 2] # the second outgoing particle +# +particles(psp, Incoming()) # all incoming particles as a tuple + +# Momentum accessors: +momentum(psp, Incoming(), Electron(), 1) # the momentum of the first incoming electron + +# When only one particle of the species exists in the particle set, the 1 can be ommitted for convenience. + +@assert ans == momentum(psp, Incoming(), Electron()) + +# !!! note +# This method throws when multiple (or zero) particles of the given direction and species exist in the phase space point. + +# When the index of the required momentum is known at compile time, a `Val(N)` can be used instead of `N`. This performs bounds checks at compile time and removes loops from the runtime execution + +using BenchmarkTools +judge( + median(@benchmark momentum($psp, Incoming(), Photon(), Val(1))), + median(@benchmark momentum($psp, Incoming(), Photon(), 1)), +) + +# !!! note +# This is only faster when `N` is actually known at compile time, for example when it is a literal integer or a function's type parameter. For dynamic values of `N`, prefer the `Int` variant or in case of loops, directly loop over the tuple of [`momenta`](@extref QEDbase.momenta). + +# Some more overloads for the momentum function exist, for a complete list please refer to its documentation: [`momentum`](@extref QEDbase.momentum), [`momenta`](@extref QEDbase.momenta). + +# Finally, [`process`](@ref), [`model`](@ref), and [`phase_space_definition`](@ref) can be used to request the object in question: + +process(psp) +# +model(psp) +# +phase_space_definition(psp) From c0f0d5d566b6c517cda92d8e408b5f94777e07f2 Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Fri, 11 Oct 2024 14:49:31 +0200 Subject: [PATCH 7/9] Add place holders for vector and phasespacedefinition manuals --- docs/make.jl | 8 +++++++- docs/src/tutorial/ps_def.jl | 12 ++++++++++++ docs/src/tutorial/vectors.jl | 23 +++++++++++++++++++++++ 3 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 docs/src/tutorial/ps_def.jl create mode 100644 docs/src/tutorial/vectors.jl diff --git a/docs/make.jl b/docs/make.jl index a8ef9be..8daba6f 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -39,7 +39,11 @@ open(readme_path, "r") do readme_in end # setup examples using Literate.jl -literate_paths = [Base.Filesystem.joinpath(project_path, "docs/src/tutorial/particles.jl")] +literate_paths = [ + Base.Filesystem.joinpath(project_path, "docs/src/tutorial/ps_def.jl"), + Base.Filesystem.joinpath(project_path, "docs/src/tutorial/particles.jl"), + Base.Filesystem.joinpath(project_path, "docs/src/tutorial/vectors.jl"), +] tutorial_output_dir = joinpath(project_path, "docs/src/generated/") !ispath(tutorial_output_dir) && mkdir(tutorial_output_dir) @@ -49,8 +53,10 @@ tutorial_output_dir_name = splitpath(tutorial_output_dir)[end] pages = [ "Home" => "index.md", + "Phase Space Definitions" => joinpath(tutorial_output_dir_name, "ps_def.md"), "Particles and Phase Space Points" => joinpath(tutorial_output_dir_name, "particles.md"), + "Matrix and Vector Types" => joinpath(tutorial_output_dir_name, "vectors.md"), "API reference" => [ "Contents" => "library/outline.md", "Particles" => "library/particles.md", diff --git a/docs/src/tutorial/ps_def.jl b/docs/src/tutorial/ps_def.jl new file mode 100644 index 0000000..2c7bf33 --- /dev/null +++ b/docs/src/tutorial/ps_def.jl @@ -0,0 +1,12 @@ +# # Phase Space Definition + +# !!! note +# [`PhasespaceDefinition`](@ref)s are to be reworked (see this [issue](https://github.com/QEDjl-project/QEDcore.jl/issues/50)). Therefore, this manual is very rudimentary for the moment. +# + +# A [`PhasespaceDefinition`](@ref) is a representation of a phase space's layout. It is a singleton type definition and has an [`AbstractCoordinateSystem`](@extref QEDbase.AbstractCoordinateSystem) and an [`AbstractFrameOfReference`](@extref QEDbase.AbstractFrameOfReference). + +using QEDcore +ps_def = PhasespaceDefinition(SphericalCoordinateSystem(), ElectronRestFrame()) + +# The phase space definition is used in [`PhaseSpacePoint`](@ref)s for dispatching in some of the cross-section interface functions. diff --git a/docs/src/tutorial/vectors.jl b/docs/src/tutorial/vectors.jl new file mode 100644 index 0000000..45ef282 --- /dev/null +++ b/docs/src/tutorial/vectors.jl @@ -0,0 +1,23 @@ +# # Vector and Matrix Types + +# **TBW** + +using QEDcore + +# ## Lorentz Vectors + +lv = rand(SLorentzVector) + +# ## Bispinors and Adjoint Bispinors + +bs = rand(BiSpinor) +# +abs = rand(AdjointBiSpinor) +# +abs * bs + +# ## Dirac and Gamma Matrices + +gm = rand(DiracMatrix) +# +abs * gm * bs From 98855bfafcfa8cb7d82f07948ad74cd06e0abcaf Mon Sep 17 00:00:00 2001 From: AntonReinhard Date: Mon, 14 Oct 2024 12:41:52 +0200 Subject: [PATCH 8/9] Add docs for In/Out PhaseSpacePoint & Review comment --- docs/src/tutorial/particles.jl | 70 +++++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 6 deletions(-) diff --git a/docs/src/tutorial/particles.jl b/docs/src/tutorial/particles.jl index ee55e96..bf57087 100644 --- a/docs/src/tutorial/particles.jl +++ b/docs/src/tutorial/particles.jl @@ -1,12 +1,13 @@ # # Particles and Phase Space Points # There are three layers of abstraction from particles to phase space points in the QEDjl project: -# - [`AbstractParticleType`](@extref QEDbase.AbstractParticleType): Base type for singleton particle type definitions. We also call these *species*. -# - [`AbstractParticleStateful`](@extref QEDbase.AbstractParticleStateful): Base type for particles with a direction and carrying a momentum. -# - [`AbstractPhaseSpacePoint`](@extref QEDbase.AbstractPhaseSpacePoint): Representation of a point in the phase space for a combination of an [`AbstractProcessDefinition`](@extref QEDbase.AbstractProcessDefinition), [`AbstractModelDefinition`](@extref QEDbase.AbstractModelDefinition), and [`AbstractPhasespaceDefinition`](@extref QEDbase.AbstractPhasespaceDefinition). +# - [`QEDbase.AbstractParticleType`](@extref): Base type for singleton particle type definitions. We also call these *species*. +# - [`QEDbase.AbstractParticleStateful`](@extref): Base type for particles with a direction and carrying a momentum. +# - [`QEDbase.AbstractPhaseSpacePoint`](@extref): Representation of a point in the phase space for a combination of an [`QEDbase.AbstractProcessDefinition`](@extref), [`QEDbase.AbstractModelDefinition`](@extref), and [`QEDbase.AbstractPhasespaceDefinition`](@extref). # This manual is intended to showcase the basic usage of these types and their implementations in QEDcore. +struct UnexpectedSuccess <: Exception end # hide using QEDcore # To use concrete process definitions and models, we also need to use [`QEDprocesses.jl`](https://github.com/QEDjl-project/QEDprocesses.jl) @@ -21,7 +22,7 @@ using QEDprocesses @assert Electron <: Fermion @assert Positron <: AntiFermion -# All of these are subtypes of [`AbstractParticleType`](@extref QEDbase.AbstractParticleType). +# All of these are subtypes of [`QEDbase.AbstractParticleType`](@extref). # There are also convenience functions in Julia convention: @assert is_boson(Photon()) @@ -36,7 +37,7 @@ using QEDprocesses # ## ParticleStateful -# [`ParticleStateful`](@ref) is the implementation of QEDbase's [`AbstractParticleStateful`](@extref QEDbase.AbstractParticleStateful) interface. It represents a particle with a [`direction`](@extref QEDbase.ParticleDirection) (as used in the context of scattering processes, [`Incoming`](@extref QEDbase.Incoming), [`Outgoing`](@extref QEDbase.Outgoing), or [`UnknownDirection`](@extref QEDbase.UnknownDirection)), a particle species ([`Electron`](@ref), [`Positron`](@ref), [`Photon`](@ref), ...), and a 4-momentum Vector. +# [`ParticleStateful`](@ref) is the implementation of QEDbase's [`QEDbase.AbstractParticleStateful`](@extref) interface. It represents a particle with a [`direction`](@extref QEDbase.ParticleDirection) (as used in the context of scattering processes, [`QEDbase.Incoming`](@extref), [`QEDbase.Outgoing`](@extref), or [`QEDbase.UnknownDirection`](@extref)), a particle species ([`Electron`](@ref), [`Positron`](@ref), [`Photon`](@ref), ...), and a 4-momentum vector. ps = ParticleStateful(Incoming(), Electron(), rand(SFourMomentum)) @@ -84,7 +85,11 @@ try # hide (rand(SFourMomentum),), # incorrect number of incoming momenta, should be 2 (rand(SFourMomentum), rand(SFourMomentum)), ) + throw(UnexpectedSuccess()) # hide catch e # hide + if e isa UnexpectedSuccess # hide + rethrow(e) # hide + end # hide @error e # hide end # hide @@ -123,7 +128,11 @@ try # hide ParticleStateful(Outgoing(), Photon(), rand(SFourMomentum)), ), ) + throw(UnexpectedSuccess()) # hide catch e # hide + if e isa UnexpectedSuccess # hide + rethrow(e) # hide + end # hide @error e # hide end # hide @@ -161,7 +170,7 @@ judge( # !!! note # This is only faster when `N` is actually known at compile time, for example when it is a literal integer or a function's type parameter. For dynamic values of `N`, prefer the `Int` variant or in case of loops, directly loop over the tuple of [`momenta`](@extref QEDbase.momenta). -# Some more overloads for the momentum function exist, for a complete list please refer to its documentation: [`momentum`](@extref QEDbase.momentum), [`momenta`](@extref QEDbase.momenta). +# Some more overloads for the momentum function exist, for a complete list please refer to its documentation: [`QEDbase.momentum`](@extref), [`QEDbase.momenta`](@extref). # Finally, [`process`](@ref), [`model`](@ref), and [`phase_space_definition`](@ref) can be used to request the object in question: @@ -170,3 +179,52 @@ process(psp) model(psp) # phase_space_definition(psp) + +# ## In/Out Phase Space Points + +# As a special case, phase space points are allowed to only contain the incoming or outgoing particle momenta. +# These types can be helpful for overloading some functions that don't require the entire phase space point to exist. + +function in_sum(in_psp::AbstractInPhaseSpacePoint) + return sum(momenta(in_psp, Incoming())) +end + +psp = InPhaseSpacePoint( + Compton(), + PerturbativeQED(), + PhasespaceDefinition(SphericalCoordinateSystem(), ElectronRestFrame()), + (rand(SFourMomentum), rand(SFourMomentum)), +) + +in_sum(psp) + +# Every full [`PhaseSpacePoint`](@ref) is both an [`InPhaseSpacePoint`](@ref) and an [`OutPhaseSpacePoint`](@ref), too. For example, the `in_sum` function defined above still works with a full [`PhaseSpacePoint`](@ref): + +psp = PhaseSpacePoint( + Compton(), + PerturbativeQED(), + PhasespaceDefinition(SphericalCoordinateSystem(), ElectronRestFrame()), + (rand(SFourMomentum), rand(SFourMomentum)), + (rand(SFourMomentum), rand(SFourMomentum)), +) + +in_sum(psp) + +# But an [`InPhaseSpacePoint`](@ref) is not an [`OutPhaseSpacePoint`](@ref) and vice versa. We cannot call `in_sum` on an [`OutPhaseSpacePoint`](@ref): + +psp = OutPhaseSpacePoint( + Compton(), + PerturbativeQED(), + PhasespaceDefinition(SphericalCoordinateSystem(), ElectronRestFrame()), + (rand(SFourMomentum), rand(SFourMomentum)), +) + +try # hide + in_sum(psp) + throw(UnexpectedSuccess()) # hide +catch e # hide + if e isa UnexpectedSuccess # hide + rethrow(e) # hide + end # hide + @error e # hide +end # hide From cf5f65d8112674b506a6a5e7d145303df740fd5f Mon Sep 17 00:00:00 2001 From: Anton Reinhard Date: Mon, 21 Oct 2024 16:06:27 +0200 Subject: [PATCH 9/9] Fix QEDbase extrefs and add lorentzboost docstrings to index --- docs/make.jl | 11 +++++++---- docs/src/library/lorentzboosts.md | 16 ++++++++++++++++ docs/src/tutorial/particles.jl | 2 +- 3 files changed, 24 insertions(+), 5 deletions(-) create mode 100644 docs/src/library/lorentzboosts.md diff --git a/docs/make.jl b/docs/make.jl index 8daba6f..7d140cf 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -53,16 +53,19 @@ tutorial_output_dir_name = splitpath(tutorial_output_dir)[end] pages = [ "Home" => "index.md", - "Phase Space Definitions" => joinpath(tutorial_output_dir_name, "ps_def.md"), - "Particles and Phase Space Points" => - joinpath(tutorial_output_dir_name, "particles.md"), - "Matrix and Vector Types" => joinpath(tutorial_output_dir_name, "vectors.md"), + "Tutorials" => [ + "Phase Space Definitions" => joinpath(tutorial_output_dir_name, "ps_def.md"), + "Particles and Phase Space Points" => + joinpath(tutorial_output_dir_name, "particles.md"), + "Matrix and Vector Types" => joinpath(tutorial_output_dir_name, "vectors.md"), + ], "API reference" => [ "Contents" => "library/outline.md", "Particles" => "library/particles.md", "Phase Space Definition" => "library/phasespacedef.md", "Phase Space Points" => "library/phasespacepoint.md", "Vector Types" => "library/vectors.md", + "Lorentz Boosts" => "library/lorentzboosts.md", "Index" => "library/index.md", ], ] diff --git a/docs/src/library/lorentzboosts.md b/docs/src/library/lorentzboosts.md new file mode 100644 index 0000000..b148fb3 --- /dev/null +++ b/docs/src/library/lorentzboosts.md @@ -0,0 +1,16 @@ +# Lorentz Boosts + +The following is an implementation of the [Lorentz Boost Interface](@extref QEDbase Lorentz-Vector) of QEDbase.jl. + +```@meta +CurrentModule = QEDcore +``` + +```@docs +Boost +BetaVector +BetaX +BetaY +BetaZ +AbstractCoordinateTransformation +``` diff --git a/docs/src/tutorial/particles.jl b/docs/src/tutorial/particles.jl index bf57087..4a51a5e 100644 --- a/docs/src/tutorial/particles.jl +++ b/docs/src/tutorial/particles.jl @@ -33,7 +33,7 @@ using QEDprocesses @assert !is_anti_particle(Electron()) @assert !is_fermion(Photon()) -# These functions are part of QEDbase.jl's (TODO: enable link once QEDbase docs are up)`[particle interface](@extref QEDbase particles)`. +# These functions are part of QEDbase.jl's [particle interface](@extref QEDbase Particle-Interface). # ## ParticleStateful