Warning, /acts/docs/contribution/physmon.md is written in an unsupported language. File is not indexed.
0001 # What is physmon?
0002
0003 The ACTS CI runs a suite of physics performance monitoring jobs dubbed
0004 *physmon*. The purpose is to monitor and detect changes in the physics
0005 performance, both intentional and accidental.
0006
0007 The associated job will run a number of workflow combinations. Currently, this
0008 includes the truth tracking and OpenDataDetector *full chain* workflows. The
0009 latter is further split into configurations with full seeding, truth smeared or
0010 truth estimated seeds. These jobs produce performance output files.
0011
0012 These performance output files are then evaluated using the programs dubbed
0013 [](analysis_apps). After this step, the job will then run comparisons of the
0014 diagnostics histograms created by these programs. If the comparisons indicate
0015 that the histogram contents changed meaningfully, the job will fail and report
0016 this on a pull request.
0017
0018 ## How do I investigate a physmon failure?
0019
0020 The physmon CI job attaches its results as an artifact to the CI run (also for successful runs)
0021 From your pull request, you need to click on the *Checks* tab at the top:
0022
0023 :::{figure} figures/physmon/physmon_checks.png
0024 :width: 150px
0025 :align: center
0026 :::
0027
0028 From there, click on the *Builds* workflow on the left:
0029
0030 :::{figure} figures/physmon/physmon_run.png
0031 :width: 300px
0032 :align: center
0033 :::
0034
0035 On the workflow overview, scroll down to find the attached artifacts, and locate the *physmon* artifact. You can click to download it:
0036
0037 :::{figure} figures/physmon/physmon_artifact.png
0038 :width: 100%
0039 :align: center
0040 :::
0041
0042 :::{note}
0043 GitHub Actions artifacts are deleted after a fixed amount of time. If the CI
0044 completed a while ago, it is possible this report is no longer available.
0045 :::
0046
0047 After the download, you need to unzip the archive, whose contents will look similar to this:
0048
0049 ```
0050 acts_analysis_residuals_and_pulls.root
0051 ckf_seeded.html
0052 ckf_seeded_plots
0053 ckf_truth_estimated.html
0054 ckf_truth_estimated_plots
0055 ckf_truth_smeared.html
0056 ckf_truth_smeared_plots
0057 ivf_seeded.html
0058 ivf_seeded_plots
0059 ivf_truth_estimated.html
0060 ivf_truth_estimated_plots
0061 ivf_truth_smeared.html
0062 ivf_truth_smeared_plots
0063 performance_ckf_seeded.root
0064 performance_ckf_truth_estimated.root
0065 performance_ckf_truth_smeared.root
0066 performance_truth_tracking.root
0067 performance_vertexing_seeded.root
0068 performance_vertexing_seeded_hist.root
0069 performance_vertexing_truth_estimated.root
0070 performance_vertexing_truth_estimated_hist.root
0071 performance_vertexing_truth_smeared.root
0072 performance_vertexing_truth_smeared_hist.root
0073 run.log
0074 truth_tracking.html
0075 truth_tracking_plots
0076 ```
0077
0078 The `.root` files are the performance output files and corresponding histogram
0079 files. The physmon job log file is also available. Finally, the `_plots` folder
0080 contain plots of all the histogram comparisons, and the `.html` files contain
0081 single-file reports showing the detailed results. An example of an HTML report
0082 looks like this:
0083
0084 :::{figure} figures/physmon/physmon_report.png
0085 :width: 100%
0086 :align: center
0087 :::
0088
0089 If you get a physmon job failure on your pull request, please investigate the
0090 failing report(s), and try to understand if the change causing the
0091 discrepancies is expected.
0092
0093 In case the conclusion is that the changes are indeed expected, the reference
0094 files used to generate the comparisons are located in `CI/physmon/reference/`,
0095 and can be updated to the output files found in the artifact zip archive.
