diff --git a/.gitignore b/.gitignore index 29126e4..716a394 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,76 @@ +# Non-machine generated gitignore items +.vscode + +# Created by https://www.toptal.com/developers/gitignore/api/julia,windows,macos,linux,vs,git,vim,emacs +# Edit at https://www.toptal.com/developers/gitignore?templates=julia,windows,macos,linux,vs,git,vim,emacs + +### Emacs ### +# -*- mode: gitignore; -*- +*~ +\#*\# +/.emacs.desktop +/.emacs.desktop.lock +*.elc +auto-save-list +tramp +.\#* + +# Org-mode +.org-id-locations +*_archive + +# flymake-mode +*_flymake.* + +# eshell files +/eshell/history +/eshell/lastdir + +# elpa packages +/elpa/ + +# reftex files +*.rel + +# AUCTeX auto folder +/auto/ + +# cask packages +.cask/ +dist/ + +# Flycheck +flycheck_*.el + +# server auth directory +/server/ + +# projectiles files +.projectile + +# directory configuration +.dir-locals.el + +# network security +/network-security.data + + +### Git ### +# Created by git for backups. To disable backups in Git: +# $ git config --global mergetool.keepBackup false +*.orig + +# Created by git when using merge tools for conflicts +*.BACKUP.* +*.BASE.* +*.LOCAL.* +*.REMOTE.* +*_BACKUP_*.txt +*_BASE_*.txt +*_LOCAL_*.txt +*_REMOTE_*.txt + +### Julia ### # Files generated by invoking Julia with --code-coverage *.jl.cov *.jl.*.cov @@ -22,3 +95,452 @@ docs/site/ # committed for packages, but should be committed for applications that require a static # environment. Manifest.toml + +### Linux ### + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# KDE directory preferences +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + +### macOS ### +# General +.DS_Store +.AppleDouble +.LSOverride + +# Icon must end with two \r +Icon + + +# Thumbnails +._* + +# Files that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + +### macOS Patch ### +# iCloud generated files +*.icloud + +### Vim ### +# Swap +[._]*.s[a-v][a-z] +!*.svg # comment out if you don't need vector files +[._]*.sw[a-p] +[._]s[a-rt-v][a-z] +[._]ss[a-gi-z] +[._]sw[a-p] + +# Session +Session.vim +Sessionx.vim + +# Temporary +.netrwhist +# Auto-generated tag files +tags +# Persistent undo +[._]*.un~ + +### vs ### +## Ignore Visual Studio temporary files, build results, and +## files generated by popular Visual Studio add-ons. +## +## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore + +# User-specific files +*.rsuser +*.suo +*.user +*.userosscache +*.sln.docstates + +# User-specific files (MonoDevelop/Xamarin Studio) +*.userprefs + +# Mono auto generated files +mono_crash.* + +# Build results +[Dd]ebug/ +[Dd]ebugPublic/ +[Rr]elease/ +[Rr]eleases/ +x64/ +x86/ +[Aa][Rr][Mm]/ +[Aa][Rr][Mm]64/ +bld/ +[Bb]in/ +[Oo]bj/ +[Ll]og/ +[Ll]ogs/ + +# Visual Studio 2015/2017 cache/options directory +.vs/ +# Uncomment if you have tasks that create the project's static files in wwwroot +#wwwroot/ + +# Visual Studio 2017 auto generated files +Generated\ Files/ + +# MSTest test Results +[Tt]est[Rr]esult*/ +[Bb]uild[Ll]og.* + +# NUnit +*.VisualState.xml +TestResult.xml +nunit-*.xml + +# Build Results of an ATL Project +[Dd]ebugPS/ +[Rr]eleasePS/ +dlldata.c + +# Benchmark Results +BenchmarkDotNet.Artifacts/ + +# .NET Core +project.lock.json +project.fragment.lock.json +artifacts/ + +# StyleCop +StyleCopReport.xml + +# Files built by Visual Studio +*_i.c +*_p.c +*_h.h +*.ilk +*.meta +*.obj +*.iobj +*.pch +*.pdb +*.ipdb +*.pgc +*.pgd +*.rsp +*.sbr +*.tlb +*.tli +*.tlh +*.tmp +*.tmp_proj +*_wpftmp.csproj +*.log +*.vspscc +*.vssscc +.builds +*.pidb +*.svclog +*.scc + +# Chutzpah Test files +_Chutzpah* + +# Visual C++ cache files +ipch/ +*.aps +*.ncb +*.opendb +*.opensdf +*.sdf +*.cachefile +*.VC.db +*.VC.VC.opendb + +# Visual Studio profiler +*.psess +*.vsp +*.vspx +*.sap + +# Visual Studio Trace Files +*.e2e + +# TFS 2012 Local Workspace +$tf/ + +# Guidance Automation Toolkit +*.gpState + +# ReSharper is a .NET coding add-in +_ReSharper*/ +*.[Rr]e[Ss]harper +*.DotSettings.user + +# TeamCity is a build add-in +_TeamCity* + +# DotCover is a Code Coverage Tool +*.dotCover + +# AxoCover is a Code Coverage Tool +.axoCover/* +!.axoCover/settings.json + +# Coverlet is a free, cross platform Code Coverage Tool +coverage*[.json, .xml, .info] + +# Visual Studio code coverage results +*.coverage +*.coveragexml + +# NCrunch +_NCrunch_* +.*crunch*.local.xml +nCrunchTemp_* + +# MightyMoose +*.mm.* +AutoTest.Net/ + +# Web workbench (sass) +.sass-cache/ + +# Installshield output folder +[Ee]xpress/ + +# DocProject is a documentation generator add-in +DocProject/buildhelp/ +DocProject/Help/*.HxT +DocProject/Help/*.HxC +DocProject/Help/*.hhc +DocProject/Help/*.hhk +DocProject/Help/*.hhp +DocProject/Help/Html2 +DocProject/Help/html + +# Click-Once directory +publish/ + +# Publish Web Output +*.[Pp]ublish.xml +*.azurePubxml +# Note: Comment the next line if you want to checkin your web deploy settings, +# but database connection strings (with potential passwords) will be unencrypted +*.pubxml +*.publishproj + +# Microsoft Azure Web App publish settings. Comment the next line if you want to +# checkin your Azure Web App publish settings, but sensitive information contained +# in these scripts will be unencrypted +PublishScripts/ + +# NuGet Packages +*.nupkg +# NuGet Symbol Packages +*.snupkg +# The packages folder can be ignored because of Package Restore +**/[Pp]ackages/* +# except build/, which is used as an MSBuild target. +!**/[Pp]ackages/build/ +# Uncomment if necessary however generally it will be regenerated when needed +#!**/[Pp]ackages/repositories.config +# NuGet v3's project.json files produces more ignorable files +*.nuget.props +*.nuget.targets + +# Microsoft Azure Build Output +csx/ +*.build.csdef + +# Microsoft Azure Emulator +ecf/ +rcf/ + +# Windows Store app package directories and files +AppPackages/ +BundleArtifacts/ +Package.StoreAssociation.xml +_pkginfo.txt +*.appx +*.appxbundle +*.appxupload + +# Visual Studio cache files +# files ending in .cache can be ignored +*.[Cc]ache +# but keep track of directories ending in .cache +!?*.[Cc]ache/ + +# Others +ClientBin/ +~$* +*.dbmdl +*.dbproj.schemaview +*.jfm +*.pfx +*.publishsettings +orleans.codegen.cs + +# Including strong name files can present a security risk +# (https://github.com/github/gitignore/pull/2483#issue-259490424) +#*.snk + +# Since there are multiple workflows, uncomment next line to ignore bower_components +# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) +#bower_components/ + +# RIA/Silverlight projects +Generated_Code/ + +# Backup & report files from converting an old project file +# to a newer Visual Studio version. Backup files are not needed, +# because we have git ;-) +_UpgradeReport_Files/ +Backup*/ +UpgradeLog*.XML +UpgradeLog*.htm +ServiceFabricBackup/ +*.rptproj.bak + +# SQL Server files +*.mdf +*.ldf +*.ndf + +# Business Intelligence projects +*.rdl.data +*.bim.layout +*.bim_*.settings +*.rptproj.rsuser +*- [Bb]ackup.rdl +*- [Bb]ackup ([0-9]).rdl +*- [Bb]ackup ([0-9][0-9]).rdl + +# Microsoft Fakes +FakesAssemblies/ + +# GhostDoc plugin setting file +*.GhostDoc.xml + +# Node.js Tools for Visual Studio +.ntvs_analysis.dat +node_modules/ + +# Visual Studio 6 build log +*.plg + +# Visual Studio 6 workspace options file +*.opt + +# Visual Studio 6 auto-generated workspace file (contains which files were open etc.) +*.vbw + +# Visual Studio LightSwitch build output +**/*.HTMLClient/GeneratedArtifacts +**/*.DesktopClient/GeneratedArtifacts +**/*.DesktopClient/ModelManifest.xml +**/*.Server/GeneratedArtifacts +**/*.Server/ModelManifest.xml +_Pvt_Extensions + +# Paket dependency manager +.paket/paket.exe +paket-files/ + +# FAKE - F# Make +.fake/ + +# CodeRush personal settings +.cr/personal + +# Python Tools for Visual Studio (PTVS) +__pycache__/ +*.pyc + +# Cake - Uncomment if you are using it +# tools/** +# !tools/packages.config + +# Tabs Studio +*.tss + +# Telerik's JustMock configuration file +*.jmconfig + +# BizTalk build output +*.btp.cs +*.btm.cs +*.odx.cs +*.xsd.cs + +# OpenCover UI analysis results +OpenCover/ + +# Azure Stream Analytics local run output +ASALocalRun/ + +# MSBuild Binary and Structured Log +*.binlog + +# NVidia Nsight GPU debugger configuration file +*.nvuser + +# MFractors (Xamarin productivity tool) working folder +.mfractor/ + +# Local History for Visual Studio +.localhistory/ + +# BeatPulse healthcheck temp database +healthchecksdb + +# Backup folder for Package Reference Convert tool in Visual Studio 2017 +MigrationBackup/ + +# Ionide (cross platform F# VS Code tools) working folder +.ionide/ + +### Windows ### +# Windows thumbnail cache files +Thumbs.db +Thumbs.db:encryptable +ehthumbs.db +ehthumbs_vista.db + +# Dump file +*.stackdump + +# Folder config file +[Dd]esktop.ini + +# Recycle Bin used on file shares +$RECYCLE.BIN/ + +# Windows Installer files +*.cab +*.msi +*.msix +*.msm +*.msp + +# Windows shortcuts +*.lnk + +# End of https://www.toptal.com/developers/gitignore/api/julia,windows,macos,linux,vs,git,vim,emacs diff --git a/docs/make.jl b/docs/make.jl index 0b54b61..64ecb3f 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,3 +1,10 @@ +using Pkg + +# targeting the correct source code +# this asumes the make.jl script is located in QEDcore.jl/docs +project_path = Base.Filesystem.joinpath(Base.Filesystem.dirname(Base.source_path()), "..") +Pkg.develop(; path=project_path) + using LorentzVectorBase using Documenter @@ -5,23 +12,23 @@ DocMeta.setdocmeta!( LorentzVectorBase, :DocTestSetup, :(using LorentzVectorBase); recursive=true ) -const numbered_pages = [ - file for file in readdir(joinpath(@__DIR__, "src")) if - file != "index.md" && splitext(file)[2] == ".md" +pages = [ + "Home" => "index.md", "Interface" => "10-interface.md", "Reference" => "95-reference.md" ] makedocs(; modules=[LorentzVectorBase], authors="Uwe Hernandez Acosta ", - repo="https://github.com/JuliaHEP/LorentzVectorBase.jl/blob/{commit}{path}#{line}", + repo=Documenter.Remotes.GitHub("JuliaHEP", "LorentzVectorBase.jl"), sitename="LorentzVectorBase.jl", format=Documenter.HTML(; + prettyurls=get(ENV, "CI", "false") == "true", canonical="https://JuliaHEP.github.io/LorentzVectorBase.jl", - repolink="https://github.com/JuliaHEP/LorentzVectorBase.jl", - edit_link="main", + # repolink="https://github.com/JuliaHEP/LorentzVectorBase.jl", + # edit_link="main", assets=String[], ), - pages=["index.md"; numbered_pages], + pages=pages, ) -deploydocs(; repo="github.com/JuliaHEP/LorentzVectorBase.jl") +deploydocs(; repo="github.com/JuliaHEP/LorentzVectorBase.jl", push_preview=true) diff --git a/docs/src/10-interface.md b/docs/src/10-interface.md index 0ae28ec..f16fd22 100644 --- a/docs/src/10-interface.md +++ b/docs/src/10-interface.md @@ -1,79 +1,88 @@ # [Interface](@id interface) -This section explains how the object can become a `LorentzVector`. +This section explains how an object can become a _object with kinematic informations_. ## Definition -We will call _`LorentzVector`-compliant_, a type that fulfills our interface described in this section. The package that provides such a type will be called _the provider_. +A type that adheres to the interface described in this section will be referred to as +_`KinematicInterface`-compliant_. A package providing such a type will be called _the provider_. -## Coordinate systems +## Coordinate Systems -The provider must specify a preferred coordinate system for its _`LorentzVector`-compliant_ type and provides accesors to the components in this system with standardized methods (specified below). In case the object natively supports several coordinate systems, the one for which the component access is the most efficient will be chosen as the _preferred coordinate system_. It has to be one of the supported coordinate system. +The provider must define a preferred coordinate system for its _`KinematicInterface`-compliant_ +type and provide accessors for the components of this system using standardized methods +(outlined below). If the object natively supports multiple coordinate systems, the provider +should choose the one in which component access is the most efficient as the _preferred +coordinate system_. This system must be one of the supported options. -The `LorentzVectorBase` package complements the component accessors to cover all the supported coordinate systems. It uses the components in the _preferred coordinate_ system to implement the complementary accessors. The Julia dispatch mechanism is used to give the preference to the accessors provided with the objet. +The `LorentzVectorBase` package supplements these component accessors to cover all supported +coordinate systems. It uses the components of the _preferred coordinate system_ to implement +complementary accessors. Julia’s dispatch mechanism prioritizes the accessors provided by +the object itself. -📝 A `LorenztVector`-compliant type can include more data than the four-vector. E.g., a type describing an elementary particle can comply, while containing more data than the particle four-momentum. +!!! note -## Implementation + A `KinematicInterface`-compliant type can store additional data beyond the four-vector. For instance, + a type representing an elementary particle may comply while containing more information than + just the particle’s four-momentum. -A type `MyLorentzVector` will comply to the `LorentzVector` interface if one of the following set of methods is implemented. +## Implementation -### Option 1: position with cartesian coordinates +A type `MyLorentzVector` (which do not necessary need to be a vector) will comply with the `KinematicInterface` if it implements +one of the following sets of methods: -| Required Methods | Brief Description | -|--------------------------------------------------------------|-------------------------------------------------| -| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface | -| `LorentzVectorBase.coordinatesystem(::Type{MyLorentzVector}) = LorentzVectorBase.XYZE` | Declare the preferred coordinate system | -| `LorentzVectorBase.x(::Tupe{MyLorentzVector})` | x cartesian coordinate | -| `LorentzVectorBase.y(::Tupe{MyLorentzVector})` | y cartesian coordinate | -| `LorentzVectorBase.z(::Tupe{MyLorentzVector})` | z cartesian coordinate | -| `LorentzVectorBase.t(::Tupe{MyLorentzVector})` | t cartesian coordinate | -| | | +### Option 1: Position with Cartesian Coordinates +| Required Methods | Brief Description | +| --------------------------------------------------------------------------------------- | ----------------------------------------------- | +| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface | +| `LorentzVectorBase.coordinate_system(::Type{MyLorentzVector}) = LorentzVectorBase.XYZE` | Declare the preferred coordinate system | +| `LorentzVectorBase.x(::MyLorentzVector)` | X Cartesian coordinate | +| `LorentzVectorBase.y(::MyLorentzVector)` | Y Cartesian coordinate | +| `LorentzVectorBase.z(::MyLorentzVector)` | Z Cartesian coordinate | +| `LorentzVectorBase.t(::MyLorentzVector)` | Time coordinate (t) | -### Option 2: four-momentum with catesian coordinates +### Option 2: Four-Momentum with Cartesian Coordinates -| Required Methods | Brief Description | -|--------------------------------------------------------------|-------------------------------------------------| -| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface | -| `LorentzVectorBase.coordinatesystem(::Type{MyLorentzVector}) = LorentzVectorBase.XYZE` | Declare the preferred coordinated system | -| `LorentzVectorBase.px(::Tupe{MyLorentzVector})` | momentum x-component | -| `LorentzVectorBase.py(::Tupe{MyLorentzVector})` | momentum y-component | -| `LorentzVectorBase.pz(::Tupe{MyLorentzVector})` | momentim z-component | -| `LorentzVectorBase.energy(::Tupe{MyLorentzVector})` | energy | +| Required Methods | Brief Description | +| --------------------------------------------------------------------------------------- | ----------------------------------------------- | +| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface | +| `LorentzVectorBase.coordinate_system(::Type{MyLorentzVector}) = LorentzVectorBase.XYZE` | Declare the preferred coordinate system | +| `LorentzVectorBase.px(::MyLorentzVector)` | Momentum X-component | +| `LorentzVectorBase.py(::MyLorentzVector)` | Momentum Y-component | +| `LorentzVectorBase.pz(::MyLorentzVector)` | Momentum Z-component | +| `LorentzVectorBase.energy(::MyLorentzVector)` | Energy | -### Option 3 four-momentum with cylindrical coordinates +### Option 3: Four-Momentum with Cylindrical Coordinates -| Required Methods | Brief Description | -|--------------------------------------------------------------|-------------------------------------------------| -| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface | -| `LorentzVectorBase.coordinatesystem(::Type{MyLorentzVector})`| Declare the preferred coordinated system. Must return PtEtaPhiM, PtEtaPhiE, PtYPhiM, or PtYPhiE (from LorentzVectorBase).| -| `LorentzVectorBase.pt(::Tupe{MyLorentzVector})` | transverse momemun | -| `LorentzVectorBase.phi(::Tupe{MyLorentzVector})` | azimuthal angle | +| Required Methods | Brief Description | +| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `LorentzVectorBase.islorentzvector(::Type{MyLorentzVector})` | Declare that your type implements the interface | +| `LorentzVectorBase.coordinate_system(::Type{MyLorentzVector})` | Declare the preferred coordinate system, which must return `PtEtaPhiM`, `PtEtaPhiE`, `PtYPhiM`, or `PtYPhiE` (from `LorentzVectorBase`) | +| `LorentzVectorBase.pt(::MyLorentzVector)` | Transverse momentum | +| `LorentzVectorBase.phi(::MyLorentzVector)` | Azimuthal angle | -
-and *one of* +Additionally, you must implement _one_ of the following: -|   |   | -|---|---| -| `LorentzVectorBase.eta(::Tupe{MyLorentzVector})` | pseudorapity | -| `LorentzVectorBase.rapidity(::Tupe{MyLorentzVector})` | rapidity relative to the beam axis (z-axis) | +| Required Method | Description | +| ----------------------------------------------- | ------------------------------------------- | +| `LorentzVectorBase.eta(::MyLorentzVector)` | Pseudorapidity | +| `LorentzVectorBase.rapidity(::MyLorentzVector)` | Rapidity relative to the beam axis (z-axis) | -
-and *one of* +And _one_ of: -|   |   | -|-|-| -| `LorentzVectorBase.energy(::Tupe{MyLorentzVector})` | energy | -| `LorentzVectorBase.mass(::Tupe{MyLorentzVector})` | invariant mass | +| Required Method | Description | +| --------------------------------------------- | -------------- | +| `LorentzVectorBase.energy(::MyLorentzVector)` | Energy | +| `LorentzVectorBase.mass(::MyLorentzVector)` | Invariant mass | -The methods that returns the coordinates of the preferred system (returned by `coordinate_system()`) must be implemented. +The methods returning the coordinates of the preferred system (as specified by `coordinate_system()`) must be implemented. -## Optional methods +## Optional Methods -|   |   | -|-|-| -| `LorentzVectorBase.mass2(::MyType{MyLorentzVector})` | mass to the square | -| `LorentzVectorBase.rho2(::MyType{MyLorentzVector})` | ρ² = \|**p**\|² | -| Any of the above method i.e, a method of option Y when methods of option X are provided || +| Optional Method | Description | +| -------------------------------------------- | -------------------------------------------- | +| `LorentzVectorBase.mass2(::MyLorentzVector)` | Square of the mass | +| `LorentzVectorBase.rho2(::MyLorentzVector)` | ρ² = \|**p**\|² (squared momentum magnitude) | +Additionally, any method from another option (i.e., a method from Option Y when methods from Option X are provided) may also be implemented.