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/README.md b/README.md index 6f8ae43..fefdef9 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,41 @@ -# 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/) -[![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/). + +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 +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..70df872 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,5 +1,8 @@ [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" 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..7d140cf 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -5,23 +5,98 @@ 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 +using Literate -# 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 + +# setup examples using Literate.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) +@info "Literate: create temp dir at $tutorial_output_dir" + +tutorial_output_dir_name = splitpath(tutorial_output_dir)[end] + +pages = [ + "Home" => "index.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", + ], +] + +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, + 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, + plugins=[links], + ) +finally + # 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/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/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/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/library/outline.md b/docs/src/library/outline.md new file mode 100644 index 0000000..bbffee8 --- /dev/null +++ b/docs/src/library/outline.md @@ -0,0 +1,5 @@ +## API Outline + +```@contents +Pages = ["particles.md", "phasespacedef.md", "phasespacepoint.md", "vectors.md"] +``` 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..08b35ca --- /dev/null +++ b/docs/src/library/phasespacepoint.md @@ -0,0 +1,19 @@ +# Phase Space Points + +```@meta +CurrentModule = QEDcore +``` + +## Types and Aliases +```@docs +ParticleStateful +PhaseSpacePoint +InPhaseSpacePoint +OutPhaseSpacePoint +``` + +## Accessors +```@docs +getindex +_momentum_type +``` diff --git a/docs/src/library/vectors.md b/docs/src/library/vectors.md new file mode 100644 index 0000000..6072899 --- /dev/null +++ b/docs/src/library/vectors.md @@ -0,0 +1,33 @@ +# 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 +``` diff --git a/docs/src/tutorial/particles.jl b/docs/src/tutorial/particles.jl new file mode 100644 index 0000000..4a51a5e --- /dev/null +++ b/docs/src/tutorial/particles.jl @@ -0,0 +1,230 @@ +# # Particles and Phase Space Points + +# There are three layers of abstraction from particles to phase space points in the QEDjl project: +# - [`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) + +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 [`QEDbase.AbstractParticleType`](@extref). +# 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 [particle interface](@extref QEDbase Particle-Interface). + +# ## ParticleStateful + +# [`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)) + +# 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)), + ) + throw(UnexpectedSuccess()) # hide +catch e # hide + if e isa UnexpectedSuccess # hide + rethrow(e) # hide + end # 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)), + ), + ) + throw(UnexpectedSuccess()) # hide +catch e # hide + if e isa UnexpectedSuccess # hide + rethrow(e) # hide + end # 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: [`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: + +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 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