source/physics_benchmarks/README.md

0001 Physics Benchmarks for the EIC
0002 ==============================
0003
0004 [![Mirror and Trigger EICweb](https://github.com/eic/physics_benchmarks/actions/workflows/mirror.yaml/badge.svg)](https://github.com/eic/physics_benchmarks/actions/workflows/mirror.yaml)
0005 ![pipeline status](https://eicweb.phy.anl.gov/EIC/benchmarks/physics_benchmarks/badges/master/pipeline.svg)
0006
0007 ## Documentation Links
0008
0009 - [`EDM4eic`](https://github.com/eic/EDM4eic) - EIC data model. (See [`ReconstructedParticle`](https://eic.github.io/EDM4eic/classedm4eic_1_1_reconstructed_particle.html) for most needs)
0010 - [`EICrecon`](https://github.com/eic/EICrecon) reconstruction framework.
0011 - Benchmark repository common code - [common_bench](https://eicweb.phy.anl.gov/EIC/benchmarks/common_bench)
0012 - ROOT's [`RDataFrame`](https://root.cern/doc/master/classROOT_1_1RDataFrame.html)
0013
0014 ## Adding new benchmarks
0015
0016 See the [`benchmarks/Exclusive-Diffraction-Tagging/diffractive_vm`](https://github.com/eic/physics_benchmarks/tree/master/benchmarks/Exclusive-Diffraction-Tagging/diffractive_vm)
0017 directory for a basic example. Note currently the reconstruction is far from perfect.
0018
0019 ### Pass/Fail tests
0020
0021 - Create a script that returns exit status 0 for success.
0022 - Any non-zero value will be considered failure.
0023
0024 See [common_bench](https://eicweb.phy.anl.gov/EIC/benchmarks/common_bench) for details.
0025
0026 ## Running Locally
0027
0028 ### Local development example
0029
0030 Here we setup to use our local build of the `juggler` library.
0031
0032 ```
0033 git clone https://eicweb.phy.anl.gov/EIC/benchmarks/physics_benchmarks.git && cd physics_benchmarks
0034 git clone https://eicweb.phy.anl.gov/EIC/benchmarks/common_bench.git setup
0035 source setup/bin/env.sh && ./setup/bin/install_common.sh
0036 source .local/bin/env.sh && build_detector.sh
0037 mkdir_local_data_link sim_output
0038 mkdir -p results config
0039
0040 ```
0041
0042 ## Repositories and Workflow
0043
0044 ### Repositories
0045
0046 The collaboration uses [the EIC group on eicweb](https://eicweb.phy.anl.gov/EIC) which contains the subgroups
0047 [detectors](https://eicweb.phy.anl.gov/EIC/detectors) and
0048 [benchmarks](https://eicweb.phy.anl.gov/EIC/benchmarks).
0049
0050 The main software components locally developed are:
0051 - [`EICrecon`](https://github.com/eic/EICrecon) ([documentation](https://eicrecon.epic-eic.org/#/)) - Event processing framework (i.e. algorithms live)
0052 - [`EDM4eic`](https://github.com/eic/EDM4eic) - EIC data model
0053 - [`npsim`](https://github.com/eic/npsim) - DD4hep simulation steering
0054
0055 The key collaboration/user code repositories are:
0056 - [epic](https://github.com/eic/epic/) - ePIC at IP6
0057 - [D2EIC](https://github.com/eic/D2EIC) - Detector II at IP8
0058 - [Detector benchmarks](https://github.com/eic/detector_benchmarks) ([eicweb mirror](https://eicweb.phy.anl.gov/EIC/benchmarks/detector_benchmarks)) - Set of analysis scripts  run on the Geant4 output before any digitization or reconstruction. Also contains some detector calibrations.
0059 - [Physics benchmarks](https://github.com/eic/physics_benchmarks) ([eicweb mirror](https://eicweb.phy.anl.gov/EIC/benchmarks/physics_benchmarks)) - Analysis of reconstructed for physics performance.  The goal is to provide metrics for optimizing detector design and reconstruction.
0060 - [Reconstruction benchmarks](https://eicweb.phy.anl.gov/EIC/benchmarks/reconstruction_benchmarks) (legacy only)
0061
0062 ### Pipelines and Artifacts
0063
0064 The SWG leverages gitlab's CI/CD features heavily in our workflow.
0065 Here are some simplified explanations of these.
0066
0067 #### Pipeline
0068
0069 A pipeline is an automated set of jobs/scripts that are triggered by certain actions, such as pushing a merge request or merging into the master/main branch of a repository.
0070 Typically there is one pipeline per repository but there can multiple and a pipline can trigger downstream pipelines ("child" pipelines) or it can be triggered by an upstream pipeline. They can also be triggered manually.
0071
0072 The graph below show some of the downstream pipeline triggers (arrows) between different repositories.
0073 ```mermaid
0074 graph TD;
0075   epic[ePIC<br>eic/epic]-->db[Detector Benchmarks<br>eic/detector_benchmarks];
0076   db-->rb[Reconstruction Benchmarks<br>eicweb:benchmarks/reconstruction_benchmarks];
0077   db-->pb[Physics Benchmarks<br>eic/physics_benchmarks];
0078   eicrecon[EICrecon<br>eic/EICrecon]-->container[EIC container/eic-shell<br>eic/container];
0079   container-->db;
0080 ```
0081
0082 Note that on any change to the detectors will cause all the benchmarks to be run.
0083
0084 "OK, pipelines run automatically. What is the big deal?"
0085
0086 #### Artifacts
0087
0088 All pipeline jobs have "artifacts" which are just selected files that are saved and can be downloaded individually or as a zip file.
0089
0090 Note artifacts are not the output data which is far too big. Artifacts are small files such as images, plots, text files, reports, etc.
0091
0092 Artifacts can be browsed via the web interface, for example, the latest in reconstruction benchmark results in the
0093 [summary job can be browsed](https://eicweb.phy.anl.gov/EIC/benchmarks/physics_benchmarks/-/jobs/artifacts/master/browse/results?job=summary).