Added documentation and tests

JuliaHEP · Sep 25, 2024 · 8379199 · 8379199
1 parent 55ff572
commit 8379199
Show file tree

Hide file tree

Showing 172 changed files with 94 additions and 19,807 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -8,6 +8,47 @@ on:
       - main
     tags: '*'
 jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.10'
+          - '1' # Leave this line unchanged. '1' will automatically expand to the latest stable 1.x release of Julia.
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        env:
+          JULIA_NUM_THREADS: "3"
+        with:
+          prefix: xvfb-run
+      - uses: julia-actions/julia-processcoverage@v1
+      - name: Upload coverage reports to Codecov
+        uses: codecov/[email protected]
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: JuliaHEP/Pythia8.jl
   docs:
     name: Documentation
     runs-on: ubuntu-latest

diff --git a/Project.toml b/Project.toml
@@ -8,15 +8,18 @@ CxxWrap = "1f15a43c-97ca-5a2a-ae31-89f07a497df4"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 PYTHIA_jll = "47b8ac8e-e87e-59c1-8ebd-407ebead3f7c"
-Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
+Pythia8_cxxwrap_jll = "2ec6ad34-3a48-58c8-92a7-b3b42157112c"
 
 [compat]
 CxxWrap = "0.14"
-InteractiveUtils = "1.11.0"
+InteractiveUtils = "1.10"
 PYTHIA_jll = "8.312.0"
-Revise = "3.5.18"
+Pythia8_cxxwrap_jll = "0.1.0"
 julia = "1.6"
 
 [extras]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -8,33 +8,34 @@ This package is developed using the [CxxWrap.jl](https://github.com/JuliaInterop
 The Julia interface has been inspired by the functionality provided by [Pythia Python interface](https://pythia.org//latest-manual/PythonInterface.html).
 
 ## Installation
-The Pythia8.jl package does no require any special installation. Stable releases are registered into the Julia general registry, and therefore can be deployed with the standard `Pkg` Julia package manager. This would bring automatically an installation of Pythia8 binary libraries as artifacts that corresponds to the current platform (the so called _jll packages).
+The Pythia8.jl package does no require any special installation. Stable releases are registered into the Julia general registry, and therefore can be deployed with the standard `Pkg` Julia package manager. This would bring automatically an installation of Pythia8 binary libraries as artifacts, which corresponds to the current platform (the so called _jll packages). Linux and MacOS with both x86_64 and arm64 architectures are supported. 
+
 ```julia
 julia> using Pkg
 julia> Pkg.add("Pythia8")
 ```
-## Available Interface
-Only the classes that provides the everyday functionality of PYTHIA have been wrapped. Additional functionality can be included upon request. This is a summary of the provided classes:
-- top level: `Pythia`
+## Interface
+Only the classes that provide the everyday functionality of PYTHIA have been wrapped. Additional classes and functionality can be included upon request. This is a summary of the currently provided classes:
+- top level: `Pythia`, `PythiaParallel`
 - event access: `Event`, `Particle`, `Vec4`
 - settings and information: `HIInfo`, `Settings`, `Flag`, `Mode`, `Parm`, `Word`, `FVec`, `MVec`, `PVec`, `WVec`
 - user interface pointers: `Rndm`, `PDF`, `DecayHandler`, `RndmEngine`, `UserHooks`, `MergingHooks`, `BeamShape`, `SigmaProcess`, `TimeShower`, `SpaceShower`, `HeavyIons`
 - analysis tools: `Hist`, `HistPlot`, `SlowJet`
 - kinematic functions: `m`, `m2`, `dot3`, `cross3`, `cross4`, `theta`, `costheta`, `phi`, `cosphi`, `RRapPhi`, `REtaPhi`
 
 ## Limitations
-- Methods returning or accepting as argument a `std::map` have not wrapped (this is a current limitation of CxxWrap package).
+- Methods returning or accepting as argument a `std::map` have not wrapped (this is a current limitation of the `CxxWrap` package).
 
 ## Getting Started
 The the following trivial interactive session:
 ```Julia
 julia> pythia = Pythia8.Pythia("", false)
 Pythia8.Pythia8!PythiaAllocated(Ptr{Nothing} @0x00000001200d0000)
 
-julia> sets = pythia |> settings # which equivalent to sets = settings(pythia)
+julia> csets = pythia |> settings # which equivalent to csets = settings(pythia)
 CxxRef{Pythia8!Settings}(Ptr{Pythia8!Settings} @0x00000001200d02d0)
 
-julia> list(sets, "Init:")
+julia> list(csets, "Init:")
  *-------  PYTHIA Flag + Mode + Parm + Word + FVec + MVec + PVec + WVec Settings (with requested string) ----------* 
  |                                                                                                                 | 
  | Name                                          |                      Now |      Default         Min         Max | 
@@ -49,12 +50,23 @@ julia> list(sets, "Init:")
  | Init:showProcesses                            |                       on |           on                         | 
  |                                                                                                                 | 
  *-------  End PYTHIA Flag + Mode + Parm + Word + FVec + MVec + PVec + WVec Settings  -----------------------------* 
- julia> parm(sets, "Beams:eA")
+ julia> parm(csets, "Beams:eA")
 7000.0
 ```
+Note that class methods are called with the object instance as first argument. In C++ the `parm` method of the `Settings` class would be called as `csets.parm("Beams:eA")`, while in Julia it is called as `parm(csets, "Beams:eA")`. Thanks to the Julia multi-dispatch we do not need to prefix the methods with the module name `Pythia8.parm`, even for very common function names such as `list`.
+
+## Examples
+Currently the following examples are implemented replicating the equivalent Python ones.
+### main291.jl
+Simple test program, equivalent to `main101.cc`, but written in Julia. It fits on one slide in a talk. It studies the charged multiplicity distribution at the LHC.
+### main292.jl
+Simple test program to illustrate the usage of `PythiaParallel` in Julia. The physics case is equivalent to `main291`, but in parallel.
+### main293.jl
+Example how you can use `UserHooks` to trace pT spectrum through the program, and veto undesirable jet multiplicities. It is based on `main242.cc`.
 
 ## Tests
-Unit tests can be run with `julia --project=. test/runtests.jl`
+Unit tests can be run with `julia --project=. test/runtests.jl`. It runs in addition all the implemented examples to ensure their correct execution and detect any regression.
 
 ## Roadmap
 There are a number of issues and problems still to be resolved. We keep track of them in this list:
+- implement more examples