diff --git a/bnl2023/.buildinfo b/bnl2023/.buildinfo new file mode 100644 index 00000000..67544166 --- /dev/null +++ b/bnl2023/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 11e8bc5cb2d8d71a1af3ce9da28330fa +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/bnl2023/.doctrees/CONDUCT.doctree b/bnl2023/.doctrees/CONDUCT.doctree new file mode 100644 index 00000000..9e1d7312 Binary files /dev/null and b/bnl2023/.doctrees/CONDUCT.doctree differ diff --git a/bnl2023/.doctrees/CONTRIBUTING.doctree b/bnl2023/.doctrees/CONTRIBUTING.doctree new file mode 100644 index 00000000..ff61aac3 Binary files /dev/null and b/bnl2023/.doctrees/CONTRIBUTING.doctree differ diff --git a/bnl2023/.doctrees/LICENSE.doctree b/bnl2023/.doctrees/LICENSE.doctree new file mode 100644 index 00000000..f1b0132b Binary files /dev/null and b/bnl2023/.doctrees/LICENSE.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/DevelopingDD4hep.doctree b/bnl2023/.doctrees/developing-fcc-software/DevelopingDD4hep.doctree new file mode 100644 index 00000000..c198295c Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/DevelopingDD4hep.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/Edm4hepTransition.doctree b/bnl2023/.doctrees/developing-fcc-software/Edm4hepTransition.doctree new file mode 100644 index 00000000..d3d00d93 Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/Edm4hepTransition.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/FccCMakeGuide.doctree b/bnl2023/.doctrees/developing-fcc-software/FccCMakeGuide.doctree new file mode 100644 index 00000000..dedbc085 Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/FccCMakeGuide.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/FccDocPage.doctree b/bnl2023/.doctrees/developing-fcc-software/FccDocPage.doctree new file mode 100644 index 00000000..987b0b31 Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/FccDocPage.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/FccSoftwareGit.doctree b/bnl2023/.doctrees/developing-fcc-software/FccSoftwareGit.doctree new file mode 100644 index 00000000..565bdc19 Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/FccSoftwareGit.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/README.doctree b/bnl2023/.doctrees/developing-fcc-software/README.doctree new file mode 100644 index 00000000..d4c2bc9a Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/README.doctree differ diff --git a/bnl2023/.doctrees/developing-fcc-software/WritingAlgorithms.doctree b/bnl2023/.doctrees/developing-fcc-software/WritingAlgorithms.doctree new file mode 100644 index 00000000..04d982e1 Binary files /dev/null and b/bnl2023/.doctrees/developing-fcc-software/WritingAlgorithms.doctree differ diff --git a/bnl2023/.doctrees/distributed-computing/OutputStructure.doctree b/bnl2023/.doctrees/distributed-computing/OutputStructure.doctree new file mode 100644 index 00000000..e1716719 Binary files /dev/null and b/bnl2023/.doctrees/distributed-computing/OutputStructure.doctree differ diff --git a/bnl2023/.doctrees/distributed-computing/README.doctree b/bnl2023/.doctrees/distributed-computing/README.doctree new file mode 100644 index 00000000..a1b0d969 Binary files /dev/null and b/bnl2023/.doctrees/distributed-computing/README.doctree differ diff --git a/bnl2023/.doctrees/distributed-computing/RegisteringToFccVO.doctree b/bnl2023/.doctrees/distributed-computing/RegisteringToFccVO.doctree new file mode 100644 index 00000000..7d3eb946 Binary files /dev/null and b/bnl2023/.doctrees/distributed-computing/RegisteringToFccVO.doctree differ diff --git a/bnl2023/.doctrees/distributed-computing/Workflows.doctree b/bnl2023/.doctrees/distributed-computing/Workflows.doctree new file mode 100644 index 00000000..cce183b0 Binary files /dev/null and b/bnl2023/.doctrees/distributed-computing/Workflows.doctree differ diff --git a/bnl2023/.doctrees/distributed-computing/workflows/01/DiTauKKMCeeDelphesStandAlone.doctree b/bnl2023/.doctrees/distributed-computing/workflows/01/DiTauKKMCeeDelphesStandAlone.doctree new file mode 100644 index 00000000..50215345 Binary files /dev/null and b/bnl2023/.doctrees/distributed-computing/workflows/01/DiTauKKMCeeDelphesStandAlone.doctree differ diff --git a/bnl2023/.doctrees/distributed-computing/workflows/Overview.doctree b/bnl2023/.doctrees/distributed-computing/workflows/Overview.doctree new file mode 100644 index 00000000..3a9d2b07 Binary files /dev/null and b/bnl2023/.doctrees/distributed-computing/workflows/Overview.doctree differ diff --git a/bnl2023/.doctrees/environment.pickle b/bnl2023/.doctrees/environment.pickle new file mode 100644 index 00000000..0c129b0d Binary files /dev/null and b/bnl2023/.doctrees/environment.pickle differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/EventProduction.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/EventProduction.doctree new file mode 100644 index 00000000..9a16f010 Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/EventProduction.doctree differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/FCCAnalysesProblemsAndSolutions.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/FCCAnalysesProblemsAndSolutions.doctree new file mode 100644 index 00000000..5b2971e0 Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/FCCAnalysesProblemsAndSolutions.doctree differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/FccFastSimGeneration.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/FccFastSimGeneration.doctree new file mode 100644 index 00000000..873b816c Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/FccFastSimGeneration.doctree differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/README.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/README.doctree new file mode 100644 index 00000000..3a555e85 Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/README.doctree differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/fccanalyses/doc/starterkit/FccFastSimAnalysis/Readme.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/fccanalyses/doc/starterkit/FccFastSimAnalysis/Readme.doctree new file mode 100644 index 00000000..aea0c8a2 Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/fccanalyses/doc/starterkit/FccFastSimAnalysis/Readme.doctree differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/fccanalyses/doc/starterkit/FccFastSimVertexing/Readme.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/fccanalyses/doc/starterkit/FccFastSimVertexing/Readme.doctree new file mode 100644 index 00000000..8c133238 Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/fccanalyses/doc/starterkit/FccFastSimVertexing/Readme.doctree differ diff --git a/bnl2023/.doctrees/fast-sim-and-analysis/k4simdelphes/doc/starterkit/FccFastSimDelphes/Readme.doctree b/bnl2023/.doctrees/fast-sim-and-analysis/k4simdelphes/doc/starterkit/FccFastSimDelphes/Readme.doctree new file mode 100644 index 00000000..ace0e167 Binary files /dev/null and b/bnl2023/.doctrees/fast-sim-and-analysis/k4simdelphes/doc/starterkit/FccFastSimDelphes/Readme.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/FCCeeCLD/FCCeeCLD.doctree b/bnl2023/.doctrees/full-detector-simulations/FCCeeCLD/FCCeeCLD.doctree new file mode 100644 index 00000000..9dc33c7c Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/FCCeeCLD/FCCeeCLD.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/FCCeeCaloPhotonPi0Discrimination/FCCeeCaloPhotonPi0Discrimination.doctree b/bnl2023/.doctrees/full-detector-simulations/FCCeeCaloPhotonPi0Discrimination/FCCeeCaloPhotonPi0Discrimination.doctree new file mode 100644 index 00000000..4d39f3d6 Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/FCCeeCaloPhotonPi0Discrimination/FCCeeCaloPhotonPi0Discrimination.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/FCCeeDriftChamber/FCCeeDriftChamber.doctree b/bnl2023/.doctrees/full-detector-simulations/FCCeeDriftChamber/FCCeeDriftChamber.doctree new file mode 100644 index 00000000..d27721e9 Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/FCCeeDriftChamber/FCCeeDriftChamber.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/FCCeeGuineaPigIRBackgrounds/README.doctree b/bnl2023/.doctrees/full-detector-simulations/FCCeeGuineaPigIRBackgrounds/README.doctree new file mode 100644 index 00000000..77d05bfd Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/FCCeeGuineaPigIRBackgrounds/README.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/FccCaloPerformance/CaloFullSimExercise.doctree b/bnl2023/.doctrees/full-detector-simulations/FccCaloPerformance/CaloFullSimExercise.doctree new file mode 100644 index 00000000..7ba5e0fa Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/FccCaloPerformance/CaloFullSimExercise.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/Geometry/Geometry.doctree b/bnl2023/.doctrees/full-detector-simulations/Geometry/Geometry.doctree new file mode 100644 index 00000000..99575179 Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/Geometry/Geometry.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/README.doctree b/bnl2023/.doctrees/full-detector-simulations/README.doctree new file mode 100644 index 00000000..7583ba73 Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/README.doctree differ diff --git a/bnl2023/.doctrees/full-detector-simulations/Visualization/Visualization.doctree b/bnl2023/.doctrees/full-detector-simulations/Visualization/Visualization.doctree new file mode 100644 index 00000000..91d216de Binary files /dev/null and b/bnl2023/.doctrees/full-detector-simulations/Visualization/Visualization.doctree differ diff --git a/bnl2023/.doctrees/index.doctree b/bnl2023/.doctrees/index.doctree new file mode 100644 index 00000000..2c97d8c1 Binary files /dev/null and b/bnl2023/.doctrees/index.doctree differ diff --git a/bnl2023/.doctrees/software-basics/README.doctree b/bnl2023/.doctrees/software-basics/README.doctree new file mode 100644 index 00000000..a742eab2 Binary files /dev/null and b/bnl2023/.doctrees/software-basics/README.doctree differ diff --git a/bnl2023/.doctrees/software-basics/asking-questions.doctree b/bnl2023/.doctrees/software-basics/asking-questions.doctree new file mode 100644 index 00000000..0803566d Binary files /dev/null and b/bnl2023/.doctrees/software-basics/asking-questions.doctree differ diff --git a/bnl2023/.doctrees/software-basics/bookkeeping.doctree b/bnl2023/.doctrees/software-basics/bookkeeping.doctree new file mode 100644 index 00000000..5d2c81e3 Binary files /dev/null and b/bnl2023/.doctrees/software-basics/bookkeeping.doctree differ diff --git a/bnl2023/.doctrees/software-basics/exploring-fcc-files.doctree b/bnl2023/.doctrees/software-basics/exploring-fcc-files.doctree new file mode 100644 index 00000000..b9578628 Binary files /dev/null and b/bnl2023/.doctrees/software-basics/exploring-fcc-files.doctree differ diff --git a/bnl2023/.doctrees/software-basics/fccsw.doctree b/bnl2023/.doctrees/software-basics/fccsw.doctree new file mode 100644 index 00000000..6e486c71 Binary files /dev/null and b/bnl2023/.doctrees/software-basics/fccsw.doctree differ diff --git a/bnl2023/.doctrees/software-basics/introduction-to-course.doctree b/bnl2023/.doctrees/software-basics/introduction-to-course.doctree new file mode 100644 index 00000000..17bab766 Binary files /dev/null and b/bnl2023/.doctrees/software-basics/introduction-to-course.doctree differ diff --git a/bnl2023/.doctrees/software-basics/prerequisites.doctree b/bnl2023/.doctrees/software-basics/prerequisites.doctree new file mode 100644 index 00000000..fad8d08e Binary files /dev/null and b/bnl2023/.doctrees/software-basics/prerequisites.doctree differ diff --git a/bnl2023/.doctrees/software-basics/swan.doctree b/bnl2023/.doctrees/software-basics/swan.doctree new file mode 100644 index 00000000..80cfa71c Binary files /dev/null and b/bnl2023/.doctrees/software-basics/swan.doctree differ diff --git a/bnl2023/.doctrees/software-basics/tips-tricks.doctree b/bnl2023/.doctrees/software-basics/tips-tricks.doctree new file mode 100644 index 00000000..2ad78bc0 Binary files /dev/null and b/bnl2023/.doctrees/software-basics/tips-tricks.doctree differ diff --git a/bnl2023/CONDUCT.html b/bnl2023/CONDUCT.html new file mode 100644 index 00000000..8b9797cb --- /dev/null +++ b/bnl2023/CONDUCT.html @@ -0,0 +1,171 @@ + + + + + + + 6.2.2.3.1. Contributor Code of Conduct — FCC Tutorials documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

6.2.2.3.1. Contributor Code of Conduct

+

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

+

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.

+

Examples of unacceptable behaviour by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

+

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

+

Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by opening an issue or contacting one or more of the project maintainers.

+

This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0, available at https://contributor-covenant.org/version/1/0/0/.

+
+ + +
+
+ +
+
+
+
+ +
+ + Other Versions + v: bnl2023 + + +
+
+
Branches
+
main
+
bnl2023
+
cern2022
+
+
+
+ + + \ No newline at end of file diff --git a/bnl2023/CONTRIBUTING.html b/bnl2023/CONTRIBUTING.html new file mode 100644 index 00000000..a1dc4af7 --- /dev/null +++ b/bnl2023/CONTRIBUTING.html @@ -0,0 +1,266 @@ + + + + + + + 6. Contributing — FCC Tutorials documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

6. Contributing

+

starterkit-lessons is an open source project, and we welcome contributions of all kinds:

+
    +

  • New lessons;

    • +

  • Fixes to existing material;

    • +

  • Bug reports; and

    • +

  • Reviews of proposed changes.

    • +
+

By contributing, you are agreeing that we may redistribute your work under these licenses. +You also agree to abide by our contributor code of conduct.

+
+

6.1. Getting Started

+
    +

  1. We use the fork and pull model to manage changes. +More information about forking a repository and making a Pull Request.

    2. +

  2. For our lessons, you should branch from and submit pull requests against the master branch.

    3. +

  3. When editing lesson pages, you need only commit changes to the Markdown source files.

    4. +

  4. To build the lessons please follow the instructions.

    5. +

  5. If you’re looking for things to work on, please see the list of issues for this repository. +Comments on issues and reviews of pull requests are equally welcome.

    6. +
+
+
+

6.2. Building the lessons

+ +
+

6.2.2. Using starterkit_ci

+
+

6.2.2.1. Requirements

+

To build the lessons locally, install the following:

+
    +

  1. starterkit-ci

    2. +
+
+
+

6.2.2.2. Building

+

Build the pages:

+
$ starterkit_ci build --allow-warnings
+$ starterkit_ci check --allow-warnings
+
+
+
+
+

6.2.2.3. Browsing the result

+

Start a web server to host them:

+
$ cd build
+$ python -m http.server 8000
+
+
+

You can see your local version by using a web-browser to navigate to http://localhost:8000 or wherever it says it’s serving the book.

+
+
+
+
+
+
+ + +
+
+ +
+
+
+
+ +
+ + Other Versions + v: bnl2023 + + +
+
+
Branches
+
main
+
bnl2023
+
cern2022
+
+
+
+ + + \ No newline at end of file diff --git a/bnl2023/LICENSE.html b/bnl2023/LICENSE.html new file mode 100644 index 00000000..f47e73f2 --- /dev/null +++ b/bnl2023/LICENSE.html @@ -0,0 +1,215 @@ + + + + + + + 6.2.2.3.2. Instructional Material — FCC Tutorials documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+
+
+ +
+
+
+
+ +
+

6.2.2.3.2. Instructional Material

+

All instructional material is made available under the Creative Commons +Attribution license. The following is a human-readable summary of +(and not a substitute for) the full legal text of the CC BY 4.0 +license.

+

You are free to:

+
    +

  • to Share — copy and redistribute the material in any medium or format

    • +

  • to Adapt — remix, transform, and build upon the material for any +purpose, even commercially.

    • +
+

The licensor cannot revoke these freedoms as long as you follow the license +terms.

+

Under the following terms:

+
    +

  • Attribution — You must give appropriate credit, provide a link to the +license, and indicate if changes were made. You may do so in +any reasonable manner, but not in any way that suggests the licensor endorses +you or your use.

    • +

  • No additional restrictions — You may not apply legal terms or +technological measures that legally restrict others from doing anything the +license permits.

    • +
+

Notices:

+
    +

  • You do not have to comply with the license for elements of the material in +the public domain or where your use is permitted by an applicable exception +or limitation.

    • +

  • No warranties are given. The license may not give you all of the permissions +necessary for your intended use. For example, other rights such as publicity, +privacy, or moral rights may limit how you use the material.

    • +
+
+
+

6.2.2.3.3. Software

+

Except where otherwise noted, the example programs and other software provided +by Software Carpentry are made available under the OSI-approved MIT +license.

+

Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the “Software”), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions:

+

The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software.

+

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE.

+
+ + +
+
+ +
+
+
+
+ +
+ + Other Versions + v: bnl2023 + + +
+
+
Branches
+
main
+
bnl2023
+
cern2022
+
+
+
+ + + \ No newline at end of file diff --git a/bnl2023/_downloads/27539a26cd9b60d3a72306f6e3a893a6/acolmu.png b/bnl2023/_downloads/27539a26cd9b60d3a72306f6e3a893a6/acolmu.png new file mode 100644 index 00000000..4ef9f325 Binary files /dev/null and b/bnl2023/_downloads/27539a26cd9b60d3a72306f6e3a893a6/acolmu.png differ diff --git a/bnl2023/_downloads/c5d588f0a6740fc45d4cd2af64268b19/p_mup.png b/bnl2023/_downloads/c5d588f0a6740fc45d4cd2af64268b19/p_mup.png new file mode 100644 index 00000000..e1ea158a Binary files /dev/null and b/bnl2023/_downloads/c5d588f0a6740fc45d4cd2af64268b19/p_mup.png differ diff --git a/bnl2023/_downloads/d3e59f826ae7c334ae9070c7d62060e0/costheta_mup.png b/bnl2023/_downloads/d3e59f826ae7c334ae9070c7d62060e0/costheta_mup.png new file mode 100644 index 00000000..ad389e42 Binary files /dev/null and b/bnl2023/_downloads/d3e59f826ae7c334ae9070c7d62060e0/costheta_mup.png differ diff --git a/bnl2023/_images/browser_Muon0.png b/bnl2023/_images/browser_Muon0.png new file mode 100644 index 00000000..02e33197 Binary files /dev/null and b/bnl2023/_images/browser_Muon0.png differ diff --git a/bnl2023/_images/browser_events.png b/bnl2023/_images/browser_events.png new file mode 100644 index 00000000..dbc10dd6 Binary files /dev/null and b/bnl2023/_images/browser_events.png differ diff --git a/bnl2023/_images/browser_missingET.png b/bnl2023/_images/browser_missingET.png new file mode 100644 index 00000000..bf78508c Binary files /dev/null and b/bnl2023/_images/browser_missingET.png differ diff --git a/bnl2023/_images/swan.png b/bnl2023/_images/swan.png new file mode 100644 index 00000000..97777647 Binary files /dev/null and b/bnl2023/_images/swan.png differ diff --git a/bnl2023/_sources/CONDUCT.md.txt b/bnl2023/_sources/CONDUCT.md.txt new file mode 100644 index 00000000..922ba821 --- /dev/null +++ b/bnl2023/_sources/CONDUCT.md.txt @@ -0,0 +1,13 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion. + +Examples of unacceptable behaviour by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team. + +Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by opening an issue or contacting one or more of the project maintainers. + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 1.0.0, available at [https://contributor-covenant.org/version/1/0/0/](https://www.contributor-covenant.org/version/1/0/0/). diff --git a/bnl2023/_sources/CONTRIBUTING.md.txt b/bnl2023/_sources/CONTRIBUTING.md.txt new file mode 100644 index 00000000..2ef0fbc5 --- /dev/null +++ b/bnl2023/_sources/CONTRIBUTING.md.txt @@ -0,0 +1,114 @@ +(contributing-lesson)= +# Contributing + +[starterkit-lessons][repo] is an open source project, and we welcome contributions of all kinds: + +* New lessons; +* Fixes to existing material; +* Bug reports; and +* Reviews of proposed changes. + +By contributing, you are agreeing that we may redistribute your work under [these licenses][license]. +You also agree to abide by our [contributor code of conduct][conduct]. + +## Getting Started + +1. We use the [fork and pull][gh-fork-pull] model to manage changes. + More information about [forking a repository][gh-fork] and [making a Pull Request][gh-pull]. + +2. For our lessons, you should branch from and submit pull requests against the `master` branch. + +3. When editing lesson pages, you need only commit changes to the Markdown source files. + +4. To build the lessons please follow the [instructions](#building-the-lessons). + +5. If you're looking for things to work on, please see [the list of issues for this repository][issues]. + Comments on issues and reviews of pull requests are equally welcome. + +## Building the lessons + +### Using `venv` (recommended) + +#### Requirements +Make sure you have `venv` (virtual environment) in your working directory. It can be created with the following command: +``` +$ python3 -m venv venv +``` +Activate it in the shell and install the requirements, which are gathered in a file provided by the repository. +``` +$ source venv/bin/activate +$ pip3 install -r requirements.txt +``` +After sourcing, your shell prompt will be augmented by the `(venv)` prefix, e.g. +``` +(venv) mylaptop:~/fcc/fcc-tutorials +``` + +:::{admonition} Building `fcc-tutorials` in FCCSW stack +:class: solution + +In case the Python from FCCSW stack is being used, it is necessary to clear +`PYTHONPATH` environment variable after sourcing of the stack +``` +source /cvmfs/fcc.cern.ch/sw/latest/setup.sh +unset PYTHONPATH +``` + +Sourcing of the FCCSW stack might be needed in cases when the Python provided by +the OS is too old, currently this is the case for CentOS 7 (`lxplus`). +::: + +#### Building +The documentation pages are build by executing +``` +$ sphinx-build -b html . build +``` + +#### Browsing the result +Open in your browser the file +``` +$PWD/build/index.html +``` + +### Using `starterkit_ci` + +#### Requirements + +To build the lessons locally, install the following: + +1. [starterkit-ci](https://pypi.org/project/starterkit-ci/) + +#### Building +Build the pages: + +```shell +$ starterkit_ci build --allow-warnings +$ starterkit_ci check --allow-warnings +``` + +#### Browsing the result +Start a web server to host them: + +```shell +$ cd build +$ python -m http.server 8000 +``` +You can see your local version by using a web-browser to navigate to `http://localhost:8000` or wherever it says it's serving the book. + +[conduct]: CONDUCT.md +[repo]: https://github.com/HEP-FCC/fcc-tutorials +[issues]: https://github.com/HEP-FCC/fcc-tutorials/issues +[license]: LICENSE.md +[pro-git-chapter]: http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project +[gh-fork]: https://help.github.com/en/articles/fork-a-repo +[gh-pull]: https://help.github.com/en/articles/about-pull-requests +[gh-fork-pull]: https://reflectoring.io/github-fork-and-pull/ + + +```{eval-rst} +.. toctree:: + :hidden: + + CONDUCT.md + LICENSE.md +``` diff --git a/bnl2023/_sources/LICENSE.md.txt b/bnl2023/_sources/LICENSE.md.txt new file mode 100644 index 00000000..1998afa3 --- /dev/null +++ b/bnl2023/_sources/LICENSE.md.txt @@ -0,0 +1,64 @@ +# Instructional Material + +All instructional material is made available under the [Creative Commons +Attribution license][cc-by-human]. The following is a human-readable summary of +(and not a substitute for) the [full legal text of the CC BY 4.0 +license][cc-by-legal]. + +You are free to: + +* to **Share** --- copy and redistribute the material in any medium or format +* to **Adapt** --- remix, transform, and build upon the material for any + purpose, even commercially. + +The licensor cannot revoke these freedoms as long as you follow the license +terms. + +Under the following terms: + +* **Attribution** --- You must give appropriate credit, provide a [link to the + license][cc-by-human], and indicate if changes were made. You may do so in + any reasonable manner, but not in any way that suggests the licensor endorses + you or your use. + +* **No additional restrictions** --- You may not apply legal terms or + technological measures that legally restrict others from doing anything the + license permits. + +Notices: + +* You do not have to comply with the license for elements of the material in + the public domain or where your use is permitted by an applicable exception + or limitation. +* No warranties are given. The license may not give you all of the permissions + necessary for your intended use. For example, other rights such as publicity, + privacy, or moral rights may limit how you use the material. + +# Software + +Except where otherwise noted, the example programs and other software provided +by Software Carpentry are made available under the [OSI][osi]-approved [MIT +license][mit-license]. + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +[cc-by-human]: https://creativecommons.org/licenses/by/4.0/ +[cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode +[mit-license]: https://opensource.org/licenses/mit-license.html +[osi]: https://opensource.org diff --git a/bnl2023/_sources/developing-fcc-software/DevelopingDD4hep.md.txt b/bnl2023/_sources/developing-fcc-software/DevelopingDD4hep.md.txt new file mode 100644 index 00000000..b41fa816 --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/DevelopingDD4hep.md.txt @@ -0,0 +1,11 @@ +# Developing DD4hep Detector models + +:::{admonition} Learning Objectives +:class: objectives + +This tutorial will teach you how to: + +* implement detector models in DD4hep +::: + +See indico: https://indico.cern.ch/event/1182767/contributions/5093296/ diff --git a/bnl2023/_sources/developing-fcc-software/Edm4hepTransition.md.txt b/bnl2023/_sources/developing-fcc-software/Edm4hepTransition.md.txt new file mode 100644 index 00000000..131da6f5 --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/Edm4hepTransition.md.txt @@ -0,0 +1,101 @@ +# Guide to the Transition of FCCSW to EDM4hep + +For the studies of the Conceptual Design Report, FCC software used its own datamodel, [FCCEDM](https://github.com/hep-fcc/fccedm). +The technical implementation was based on a novel library called [PODIO](https://github.com/aidasoft/podio), and tries to use "Plain Old Data" to achieve thread safety and general ease of use. + +While FCCEDM has served its purpose, continued use has revealed some minor issues, inconsistencies and impracticalities (see [here](https://github.com/HEP-FCC/fcc-edm/issues?q=is%3Aissue+) and [here](https://fccsw-forum.web.cern.ch/t/event-data-model-discussion/32)). +Since then, FCC has joined a common software effort with other Future Collider Communities, and decided to base the common software ([Key4HEP](https://cern.ch/key4hep)) on a new, common datamodel ([EDM4HEP](https://github.com/key4hep/edm4hep)). + +The types defined by EDM4HEP are somewhat closer to [LCIO](https://github.com/ilcsoft/lcio), but like FCCEDM it is implemented with PODIO. +In any case, the transition, while time-intensive, is no major technical challenge, and provides the basis for a common experiment software beyond FCC. + + +This document should guide users and developers through the transition. + +EDM4HEP and FCCEDM can coexist, but for a frictionless transition, FCCEDM should be replaced completely as soon as possible. + + +The following sections focus on the Gaudi-based framework FCCSW and explain how to transition the components of the datamodel. +The latest developments can be found on [this branch](https://github.com/HEP-FCC/FCCSW/tree/edm4hep) (PRs welcome). + + + +## Technical Information + +### Build System + +EDM4HEP ships a CMake configuration (in uppercase: `EDM4HEPConfig.cmake`) that defines CMake Targets (in lowercase: `EDM4HEP::edm4hep`). +To include and link edm4hep, it is sufficient to add the following to the `CMakeLists.txt` of an example project: + + + + +``` + +find_package(EDM4HEP) + + gaudi_add_module(ExampleModule + src/components/*.cpp + INCLUDE_DIRS # nothing needs to be added here, the target defines the includes + LINK_LIBRARIES EDM4HEP::edm4hep) +``` + + +### Component source Code + +The code now can be adapted changing any mention of `datamodel` to `edm4hep` and converting the types: + +#### Generation / MCParticles + +FCCEDM had several types to describe particles at the Generator Level: `GenParticle`, `GenVertex` and `GenJet`. +The mother/daughter relationship was encoded in the vertices; A particle and its decay product were supposed to share one vertex object (the mother particle as its endvertex, the daughter particle as its startvertex). A library for creating directed acyclic graphs was supposed to help deal with this slightly cumbersome system, but was not really used in practice. + +EDM4HEP replaces this by the single type `MCParticle`. This contains the vertex information, and Jets are generally treated as particles in EDM4hep. + +The correspondence is fairly direct: + +| | | +|----|----| +| EDM4HEP | FCCEDM | +| MCParticle | MCParticle/GenVertex/GenJet | +| PDG | core.pdgId | +| generatorStatus | core.status | +| charge | charge | +| time | startVertex.ctau # Note the unit differences! | +| vertex | startVertex.position | +| endpoint | endVertex.position | +| momentum, mass | core.p4 | +| momentumAtEndpoint || +| spin | | +| colorFlow | | + + + +### Job options + +As the GenVertex type is no longer an independent type in edm4hep, any components that used to write GenParticles and GenVertices need to be adapted (the opportunity was used to also update the spelling from `genparticles` to `GenParticles` for the Gaudi data property): + +```diff +- hepmc_converter.genparticles.Path="allGenParticles" +- hepmc_converter.genvertices.Path="allGenVertices" ++ hepmc_converter.GenParticles.Path="allGenParticles" +``` + +The configuration for the SimG4SaveSmearedParticles tool needs to be adapted in the following way: + +```diff +- from Configurables import SimG4SaveSmearedParticles +- saveparticlestool = SimG4SaveSmearedParticles("saveSmearedParticles") +- saveparticlestool.particles.Path = "smearedParticles" +- saveparticlestool.particlesMCparticles.Path = "particleMCparticleAssociation" ++ saveparticlestool.RecParticles.Path = "smearedParticles" ++ saveparticlestool.MCRecoParticleAssoc.Path = "particleMCparticleAssociation" + +``` + +```diff + +- particle_converter = SimG4PrimariesFromEdmTool("EdmConverter") +- particle_converter.genParticles.Path = "allGenParticles" ++ particle_converter.GenParticles.Path = "allGenParticles" +``` diff --git a/bnl2023/_sources/developing-fcc-software/FccCMakeGuide.md.txt b/bnl2023/_sources/developing-fcc-software/FccCMakeGuide.md.txt new file mode 100644 index 00000000..c3c1321e --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/FccCMakeGuide.md.txt @@ -0,0 +1,178 @@ +# CMake guide for the FCC software + +## Overview + +CMake is a tool for building software, which has become the de-facto +standard outside HEP. In HEP, it is for example used by the ILC/CLIC +communities and by the LHCb collaboration. For CMS people, CMake is the +equivalent of scram. In FCCSW, CMake is used mainly via Gaudi macros, which are however fairly similar to plain CMake commands in syntax. + +This [LHCb Twiki](https://twiki.cern.ch/twiki/bin/view/LHCb/GaudiCMakeConfiguration) has some additional information on +various Gaudi CMake functions. + + + +## Quick start into building FCCSW + +### Set up the environment + +In case you are unsure, it is best to use the `init.sh` script provided with FCCSW: + +``` +source ./init.sh` +``` + +Note that mixing setup scripts (from another package, for example) may or may not work as intended - more likely not. +For any requests to changes in the environment, feel free to contact the software team on the mailing list or any other channels. +Developers may also look into `spack` to have more fine-grained control over the build dependencies. + +### Using the top-level Makefile + + +- The software can be compiled in the root directory with `make -j8`. +- After adding new files, do `make configure` +- Building single packages: `make packagename` +- Cleaning up (rebuild from scratch): `make purge` +- To change the build-type (e.g. Release or Debug), set the `BUILDTYPE` variable (e.g. `BUILDTYPE=Debug make`) + +### Using plain CMake + +The steps that the top-level Makefile does can also be done manually: + +* Create a build directory: `mkdir build; cd build` +* Run CMake in the build directory: `cmake .. ` +* Change any cmake options by rerunning cmake. For example: `cmake .. -DCMAKE_INSTALL_PREFIX=install`. Tools like ccmake may also be useful: `ccmake ..` +* Compile the software, using all the cpus available: ```make -j `getconf _NPROCESSORS_ONLN` ``` +* Install by running `make install` +* In case any dependency is changed, most likely you need to remove all the contents of the build folder and rerun cmake and the compilation. + + + +## CMake example packages + +Colin provides [a few simple CMake +examples](https://github.com/cbernet/cmake-examples) independent from +the FCC software framework. They are helpful to understand the basics of +CMake. + +Get these packages: + + git clone https://github.com/cbernet/cmake-examples.git + cd cmake-examples + +Follow the instructions in +[README.md](https://github.com/cbernet/cmake-examples/blob/master/README.md). + +## CMake in the FCC software framework + +The FCC software framework is split into single packages `Generation`, `Examples`, `Simulation` , .... Each of these packages contains +the file `CMakeLists.txt`, defining its content. To build the entire +SW, a Makefile is provided in the top level directory, so `make` can be invoked there to build FCCSW. To rebuild a single package +`make packagename` is sufficient. + +Note that single subdirectory cannot be installed individually at the moment. +If you need to install, it is best to compile everything in the beginning (which may take a while), and then work with the build folder. Any changes should only lead to the changed subdirectories being recompiled. + + +When adding new source files to a package, the CMake build system needs +to be made aware of them. Usually `CMakeLists.txt` contains a wildcard +expression that adds all implementation files in a subfolder, e.g. +`src/*.cpp` , so there is no need to explicitly add the names of the +new files. To update the list of files, it is fastest to run +`make configure` . + +Note that when changing the name of a property of an algorithm or a +tool, `make` (and not only `make packagename` ) needs to be run for +Gaudi to be aware of the change. + +The `make` command creates a directory `build.xxxx` where `xxxx` depends on your platform and compiler. All build files +are writtin in that directory. There are situations where you need to clean this build folder before you can +successfully build the software: + +- The FCCSW environment changed (version change) +- Fetching changes from other users or the HEP-FCC repository with deleted files + +In those cases you'll need to do `make purge` (this target deletes the build and install directories) and rebuild the +entire software. + + +### Runtime Environment + +FCCSW consists of executables, headers, scripts, dynamic libraries, xmls and special files describing gaudi components. +In order to use these, some environment variables need to be set. +FCCSW includes a setup script that is installed automatically and can be sourced to set up the required variables. + +Gaudi also offers the possibility to set up the environment via the `xenv` command. This is done by simply prefixing the command you want to run with the `run` script in the top level directory of FCCSW, or directly in the build directory. + +```bash +./build/run fccrun Examples/options/pythia.py +``` + +Sometimes it is convenient to run FCCSW directly from the binaries in the build directory without installing them. +This can be done by using the `run` script in the build directory, or setting the environment variables as in `setup.sh` for the build folder. +Note that the directories in the build folder differ a bit. Mostly it is important the the LD_LIBRARY_PATH is pre-fixed with the library directories. The fccrun command should pick up the components from the build folder then. + + + +## CTest in FCCSW + +FCCSW also uses the cmake for integration tests. +This is described in detail in the documentation page on [adding tests to FCCSW](https://github.com/HEP-FCC/FCCSW/blob/master/doc/AddingTestsToFCCSW.md). + +## Using an internal library + +Libraries are the main tool to avoid code duplication, i.e. make pieces of code available in other parts of the framework. +Once Gaudi is notified that a certain subdirectory is needed by invoking `gaudi_depends_on_subdir`, internal libraries defined in this subdirectory can be used by simply adding them to the list of `INCLUDE_DIRS` and `LINK_LIBRARIES`. An example would be the way the internal library `DetCommon` is used by the module [`Test/TestGeometryPlugins`](https://github.com/HEP-FCC/FCCSW/blob/master/Test/TestGeometry/CMakeLists.txt) in FCCSW. +The required changes to use the `DetCommon` library are +* declare the dependency on the subdirectory `Detector/DetCommon` +* add the `DetCommon` headers by adding `DetCommon` to the `INCLUDE_DIRS` line +* link the `DetCommon` libraries by adding `DetCommon` to the `LINK_LIBRARIES` line. + + +## Building a new Gaudi module + +A more general introduction to Gaudi modules and the differences with respect to libraries can be found in the [LHCb twiki](https://twiki.cern.ch/twiki/bin/view/LHCb/GaudiCMakeConfiguration#Building_a_Module_AKA_component). +The best way is to look at existing modules in FCCSW for inspiration. The syntax to declare the module [`TestGeometryPlugins`](https://github.com/HEP-FCC/FCCSW/blob/master/Test/TestGeometry/CMakeLists.txt), for example, is: + +```cmake +gaudi_add_module(TestGeometryPlugins + src/components/*.cpp + INCLUDE_DIRS Geant4 FWCore SimG4Interface SimG4Common DetInterface DetCommon TestGeometry + LINK_LIBRARIES GaudiKernel FWCore Geant4 DetCommon TestGeometry) + +``` + +## Using an external library + +This can be done using the standard cmake command [find_package](https://cmake.org/cmake/help/v3.0/command/find_package.html). See [Colins CMake examples](https://github.com/cbernet/cmake-examples) for details. + +Sometimes external libraries require special treatment, and their documentation needs to be consulted. One known case is DD4hep, for which in some cases the CMake variable `${DD4hep_COMPONENT_LIBRARIES}` needs to be used in the `LINK_LIBRARIES` line (if the DDRec or DDSegmentation package is used). Example: + +```cmake +gaudi_add_library(DetCommon + src/*.cpp + INCLUDE_DIRS DD4hep ROOT Geant4 DetSegmentation + LINK_LIBRARIES GaudiKernel DD4hep ROOT Geant4 DetSegmentation ${DD4hep_COMPONENT_LIBRARIES} + PUBLIC_HEADERS DetCommon) + +``` + +ROOT is needed in many modules of FCCSW. More information how to use it in a CMake-based project is available on the [ROOT website](https://root.cern.ch/how/integrate-root-my-project-cmake). + +### Customizing how CMake is run + +An environment variable is used to forward command line arguments to the cmake command, for example to run cmake with the `trace` option: + +``` +CMAKEFLAGS='--trace' make +``` + +:::{admonition} How do I check compilation flags? +:class: callout + +Instead of running `make`, run: + +```shell +make VERBOSE=1 +``` +::: diff --git a/bnl2023/_sources/developing-fcc-software/FccDocPage.md.txt b/bnl2023/_sources/developing-fcc-software/FccDocPage.md.txt new file mode 100644 index 00000000..978d44b9 --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/FccDocPage.md.txt @@ -0,0 +1,122 @@ +# Writing documentation for the FCC software + + +## Where to put documentation + +- API documentation of classes and functions is done with Doxygen notation in the source code. +- Slightly higher level documentation on usage of a piece of software is usually put directly in the corresponding repository. +- Long-form documentations that introduce users to a piece of software belong in [fcc-tutorials](https://hep-fcc.github.io/fcc-tutorials/). + +:::{admonition} Where to put documentation +:class: callout + +It is sometimes difficult to decide between the last two. In those cases either will be great. +::: + + +## When and how is the documentation page updated? + +There are both a main website () and a readthedocs-style page for the tutorials (). + +Both consists of a static website based on `github-pages`. The main website points to EOS (`/eos/project/f/fccsw-web/www`), from where it is redirected to the github-pages site of FCCSW. Only members +of the corresponding e-group have write access. All markdown and configuration files are stored in the [`gh-pages`](https://github.com/HEP-FCC/FCCSW/tree/gh-pages) branch of the +FCCSW Github repository. All dependencies (jquery, bootstrap-sass) are included in the mentioned repository and any change should be automatically deployed to: + +[http://hep-fcc.github.io/FCCSW/](http://hep-fcc.github.io/FCCSW/) + + +## Structure of the content of the main page + +Folders can be added to aggregate markdown files by category: + +- `computing`: FCC Computing Resources +- `presentations`: Selection of Publications and Presentations relating to FCC Software +... + +The rest of folders and files are mainly configuration files to generate the website itself with [Jekyll](https://jekyllrb.com/): + +- `_data`: Contains `permalinks.yaml` YAML file with the links shown on the website +- `_includes`: HTML files to define the structure of the website (header, footer, ...) +- `_layouts`: HTML Structure for those part that are commonly used (posts, sites, title headers, ...) +- `css`: Define the style of the website +- `geo`: Geometry visualization +- `node_modules`: Contains Javascript installed dependencies +- `Gemfile`: Define Ruby dependencies +- `package.json`: Define Javascript dependencies +- `_config`: General configuration file with metadata used by Jekyll + + +## Running website generation locally + +**This is meant for testing not to override the generated website!** + +Modify the content and serve the page with: + +```bash +jekyll serve --baseurl= +``` + +Now you should be able to see the website at `localhost:4000`. + + +### About jekyll + +We are using jekyll to build our website. If you are interested in extending the website have a look in +the [repository](https://github.com/HEP-FCC/FCCSW/tree/gh-pages). Documentation of jekyll may be found +[elsewhere](https://jekyllrb.com/). In case of questions contact the fcc-experiments-sw-dev mailing list. + + +## For website admins + +Administrators controlling access to the webspace need to be members of the e-group `cernbox-project-fccsw-web-admins`. + +If you want to have write-access you need to request membership in +`cernbox-project-fccsw-web-writers`. If you are the main responsible for these activities, you should own the service account `fccsweos` that has admin rights for both the physics data EOS space and the web EOS space. + + +## Custom Admonitions + +The `fcc-tutorial` makes use of custom admonition classes: + +* prereq +* callout +* challenge +* solution +* objectives +* keypoints +* discussion + +Example of an admonition: +```markdown +:::{admonition} Custom admonition +:class: solution + +Text of a custom admonition. +::: +``` + +:::{admonition} Custom admonition +:class: solution + +Text of a custom admonition. +::: + +To create collapsible admonition add additional classes: +* To create collapsible admonition closed by default add only `dropdown` class. +* To create collapsible admonition open by default add two classes `dropdown` and + `toggle-shown`. + +Example of collapsible admonition: +```markdown +:::{admonition} Collapsable admonition +:class: prereq dropdown toggle-shown + +Text of a collapsable admonition. +::: +``` + +:::{admonition} Collapsable admonition +:class: prereq dropdown toggle-shown + +Text of a collapsable admonition. +::: diff --git a/bnl2023/_sources/developing-fcc-software/FccSoftwareGit.md.txt b/bnl2023/_sources/developing-fcc-software/FccSoftwareGit.md.txt new file mode 100644 index 00000000..7dde1fe8 --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/FccSoftwareGit.md.txt @@ -0,0 +1,195 @@ +# Github workflow and contribution guide + + + +## Overview + +This page should allow users that are new to Git to get started with the FCC +software, and describes the workflow for accessing and contributing FCC +code. + +For a general introduction to git, have a look at these tutorials: + +- [Atlassian tutorial](https://www.atlassian.com/git/tutorials/) +- [Interactive tutorial](http://pcottle.github.io/learnGitBranching/) +- [The git book](https://git-scm.com/book/en/v2) + +## First time setup of git + +Please refer to [this tutorial](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) and the [GitHub help](https://help.github.com/articles/set-up-git/). + +## Generate and set up ssh keys for github + +When working on lxplus we recommend to clone github repositories via SSH, especially if you want to contribute code. For this to work, you need to generate ssh keys for authentication. See the corresponding github [help-page](https://help.github.com/articles/generating-an-ssh-key/). + +:::{admonition} Generate and set up ssh keys for github +:class: callout + + If you only want to use the software it may be easier to use https. In that case you don't need to generate the keys but have to replace `git@github:` with `https://github.com/` in all the instructions. Note that you'll not be able to push to your repository when you are on lxplus. You can also start using https for now and later re-add your repository with ssh authentication, see the [trouble shooting section](#trouble-shooting) +::: + + +## Improving your git experience + +It may be useful to install [Git integration tools](https://github.com/git/git/tree/master/contrib/completion) for your shell that allow tab-completion of most git commands and also can show you in your prompt on which branch you currently are, what changes you have pending, etc. + +## Development workflow + +You will be using (at least) 3 versions of the FCCSW repository: + +1. The official [FCCSW on github](https://github.com/HEP-FCC/FCCSW) +2. Your fork of FCCSW on github (see [github help](https://help.github.com/articles/fork-a-repo/) on what that means) +3. Your local repository copy in your work area (e.g. on AFS) + +The repositories 1 and 2 are added as remote to the repository 3: + +```bash +git clone git@github.com:[YOUR_GITHUB_USER]/FCCSW.git # create a local copy (3) of your fork (2) +cd FCCSW +git remote add hep-fcc git@github.com:HEP-FCC/FCCSW.git # add official repo (1) as additional remote +``` + +### Keeping your local repository up to date + +- fetch all changes from the official repository (1) + + ```bash + git fetch hep-fcc + ``` + +- rebase your development area to the master branch from the official repository (1), **please read [this](https://www.atlassian.com/git/tutorials/rewriting-history) to avoid loss of work** + + ```bash + git rebase -i hep-fcc/master + ``` + + in this process you can also fix any commits that need touching up, **be aware that deleting commits in the list will result also in the deletion of the corresponding changes** (more info in the [GitHub help](https://help.github.com/articles/about-git-rebase/) and the [Atlassian tutorial](https://www.atlassian.com/git/tutorials/rewriting-history)) + +- push your local changes to your fork (2), see [below](#contributing-code) how to create a local branch + + ``` + git push origin [NAME_OF_LOCAL_BRANCH] + ``` + +### Contributing code + +- if you are fixing a bug, first create an issue in the github [issue tracker](https://github.com/HEP-FCC/FCCSW/issues) +- develop your feature in your local copy (3) on a local branch of your choice, to create a branch do: + + ``` + git branch -b [NAME_OF_LOCAL_BRANCH] + ``` + +- refer to [this tutorial](https://www.atlassian.com/git/tutorials/saving-changes) to see how to commit changes +- occasionally, get new code from the official repository (1) as explained above and merge it in this branch +- test: + - that the code compiles and all tests succeed (`make && make test`) + - that your code runs (even better: [add an automatic test](https://github.com/HEP-FCC/FCCSW/blob/master/doc/AddingTestsToFCCSW.md)) + - that it produces the expected results +- push your local branch to your fork (2) (see [above](#keeping-your-local-repository-up-to-date)) +- create a pull request from your fork (2) to the offical repository's (1) master branch (see github [help-page](https://help.github.com/articles/creating-a-pull-request/)) + - also see the [recommendations for pull requests](#pull-requests) + +## Recommendations + +Please always follow the recommendations below. + +### General recommendations + +- if you're working on a given topic, always create a branch for + it, e.g. `pythia_interface`. You may commit many times to this branch + in your local repository. When you have something solid create a + pull request to the official FCCSW repository. +- Have a look at our [coding guidelines](https://github.com/HEP-FCC/FCCSW/blob/master/doc/CppCodingStyleGuidelines.md). + +### Commit comments + +- feel free to commit often to your local repository, make a pull request once the topic you are working on is finished + - if the feature you are working on is large, consider making a work in progress-pull request (see [below](#pull-requests)) + - git commits represent a snapshot of the software as a whole, and not only the difference to a previous commit (although that as well, in practice). It is recommended that each commit compiles and passes the tests. Take a look at the [commit history of FCCSW](https://github.com/HEP-FCC/FCCSW/commits/master) and the histories of some individual files to find both good and bad examples. + +- always provide a meaningful comment for each commit + - if you are working on an issue, refer to that issue by adding "refs. #[issue id]", see also + [GitHub help](https://help.github.com/articles/closing-issues-via-commit-messages/) +- commit comments should look like the one below, so that they show up + correctly in git printouts. + + ``` + first version of a pythia interface # this line should be a short 1 liner + + Here, you may write a few more lines if needed + ``` + +### Cleaning history + +- before opening a pull request it may be a good idea to check that your history makes sense (commit messages explain what you did, no unnecessary commits, etc.), check with: + + ``` + git log + ``` +- if you see commits that you'd like to change, there are several ways of doing that, the most commonly used is `git rebase`: + - with the interactive version you can rebase your development branch to the official master and fix the history at the same time + + ``` + git fetch hep-fcc # get changes from the official repo + git rebase -i hep-fcc/master # do the actual rebase + ``` + + - git will guide you through the steps, where you can delete entire commits (and the corresponding changes), merge commits and change commit messages + - more information can be found in [this tutorial](https://www.atlassian.com/git/tutorials/rewriting-history#git-rebase-i) + +### Pull requests + +- Give a meaningful title that appropriately describes what you did (e.g. Add new calorimeter clustering) + - Pull requests of work in progress (to make people aware that you are working on a feature) create a PR starting with "[WIP]" +- In the description, give a short bullet-point list of what was done +- If your pull request fixes issues tracked in the [issue tracker](https://github.com/HEP-FCC/FCCSW/issues): + - Make sure you added a test that shows they are actually fixed + - In the description mention that you fixed it by referring to the issue: "fixes #" (this will automatically close the issue, see also [GitHub help](https://help.github.com/articles/closing-issues-via-commit-messages/)) + +## Trouble-shooting + +### When I try to push to the repository, I get an authentication error + +Check with `git remote -v` which remote repositories you have added to your local copy. You should see something like: + +``` +hep-fcc git@github.com:HEP-FCC/FCCSW.git (fetch) +hep-fcc git@github.com:HEP-FCC/FCCSW.git (push) +origin git@github.com:[your git user name]/FCCSW.git (fetch) +origin git@github.com:[your git user name]/FCCSW.git (push) +``` + +If you see something similar but all the addresses start with `https`, see [below](#i-have-cloned-with-https-and-now-i-cant-push-my-changes-what-do-i-do). + +If you only see `origin git@github.com:HEP-FCC/FCCSW.git`, you need to add your own repository, push to that one and do a pull request, as described above. To add your own repository do: + +``` +git remote rename origin hep-fcc +git remote add myfccsw git@github.com:[your git user name]/FCCSW.git +``` + + +### I have cloned with https and now I can't push my changes, what do I do? + +You only need to change the URL of your remote pointing to your repository to one that uses SSH instead: + +``` +git remote set-url [the remote name] git@github.com:[your git user name]/FCCSW.git +``` + +Now you can push to that remote with: + +``` +git push [the remote name] [the branch you want to push] +``` + +--- + +## Need help? + +In case you have any questions on this guide, or need help to sort out +an issue with a repository, feel free to drop a mail to +fcc-experiments-sw-dev at CERN, and we'll be happy to help you. +Alternatively create an issue in the [bug tracker](https://github.com/HEP-FCC/FCCSW/issues) +![smile](https://twiki.cern.ch/twiki/pub/TWiki/SmiliesPlugin/smile.gif "smile") diff --git a/bnl2023/_sources/developing-fcc-software/README.md.txt b/bnl2023/_sources/developing-fcc-software/README.md.txt new file mode 100644 index 00000000..4c6af99d --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/README.md.txt @@ -0,0 +1,18 @@ +# Developing FCCSW + +Sooner rather than later you will find it necessary write code for FCCSW. These pages cover some software development topics to remove any friction. + + + +```{eval-rst} +.. toctree:: + :caption: Contents: + + FccSoftwareGit.md + FccCMakeGuide.md + WritingAlgorithms.md + DevelopingDD4hep.md + Edm4hepTransition.md + FccDocPage.md + +``` diff --git a/bnl2023/_sources/developing-fcc-software/WritingAlgorithms.md.txt b/bnl2023/_sources/developing-fcc-software/WritingAlgorithms.md.txt new file mode 100644 index 00000000..7a20ea1c --- /dev/null +++ b/bnl2023/_sources/developing-fcc-software/WritingAlgorithms.md.txt @@ -0,0 +1,61 @@ +# Writing Gaudi Algorithms + + +:::{admonition} Learning Objectives +:class: objectives + +This tutorial will teach you how to: + +* write an algorithm for FCCSW +* interact with the cmake based build system +* use other Gaudi components in the algorithms +::: + + +## Getting Started + +Writing Gaudi components requires a bit of boilerplate code. +Often it is easiest to start from existing files and modify them as needed. +For this tutorial, there is a dedicated repository that contains an example. +Start by cloning it locally: + +```bash +git clone https://github.com/key4hep/k4-project-template +``` + +It contains a CMake configuration (as described in more detail in the previous tutorial) so it can be built with: + +```bash +cd k4-project-template +mkdir build install +cd build +cmake .. -DCMAKE_INSTALL_PREFIX=../install +make -j 4 +``` + +To run the algorithms contained in this repository, it is not necesary to run + +``` +make install +``` + +you can use the `run` script in the `build` directory, like: + +```bash +./run fccrun ../K4TestFWCore/options/createExampleEventData.py + +``` + + +## Exercise: Adding an Algorithm + +The repository contains an `EmptyAlg` in `K4TestFWCore/src/components`. + + +* As a first exercise, copy and modify this algorithm to print out the current event number. + +* Second step: If you used `std::cout` in the first step, try to use the gaudi logging service instead. + +* Third Step: Print out a string before the event number that should be configurable at runtime. + +* Finally: use the Gaudi Random Number Generator Service to approximate pi with a [Monte Carlo Integration](https://en.wikipedia.org/wiki/Monte_Carlo_integration) diff --git a/bnl2023/_sources/distributed-computing/OutputStructure.md.txt b/bnl2023/_sources/distributed-computing/OutputStructure.md.txt new file mode 100644 index 00000000..6846f00c --- /dev/null +++ b/bnl2023/_sources/distributed-computing/OutputStructure.md.txt @@ -0,0 +1,17 @@ +# Structure for /eos/experiment/fcc/prod + +## Overview +FCC Monte Carlo productions will be handled by the DIRAC system and stored at CERN under + +``` + /eos/experiment/fcc/prod/fcc +``` + +where `/eos/experiment/fcc/prod` is the mapped endpoint and `/fcc` is required to honour DIRAC request to start with `/`. +A hierarchical structure for the output files has been defined for an efficient use of this area. +The purpose of these pages is to describe such a structure. + +Complete metadata will be available from DIRAC through the unique identifier `DiracProdID` discussed above. + + + diff --git a/bnl2023/_sources/distributed-computing/README.md.txt b/bnl2023/_sources/distributed-computing/README.md.txt new file mode 100644 index 00000000..ba2e1464 --- /dev/null +++ b/bnl2023/_sources/distributed-computing/README.md.txt @@ -0,0 +1,23 @@ +# Distributed computing + +These pages provide - and dissect - examples of workflows to be run on distributed resources with the [DIRAC Interware system][dirac] +through [iLCDirac][ilcdirac], the extension developed by the Linear Collider community and used also by CALICE. + +The procedure to be enabled to use the FCC resources through DIRAC is first described. Additional information about the use of +iLCDirac can be found in the [CLIC][wikiclic] and [ILC][wikiilc] dedicated Wiki pages. + +Unless specified, in the rest of this section the word `DIRAC` refers to the `iLCDirac` extension introduced above. + +[dirac]: https://dirac.readthedocs.io/en/latest/ +[ilcdirac]: https://iopscience.iop.org/article/10.1088/1742-6596/513/3/032077/meta +[wikiclic]: https://twiki.cern.ch/twiki/bin/view/CLIC/DiracForUsers +[wikiilc]: https://flcwiki.desy.de/ILCDirac + +```{eval-rst} +.. toctree:: + :caption: Contents: + + RegisteringToFccVO.md + Workflows.md + OutputStructure.md +``` diff --git a/bnl2023/_sources/distributed-computing/RegisteringToFccVO.md.txt b/bnl2023/_sources/distributed-computing/RegisteringToFccVO.md.txt new file mode 100644 index 00000000..54fab184 --- /dev/null +++ b/bnl2023/_sources/distributed-computing/RegisteringToFccVO.md.txt @@ -0,0 +1,102 @@ +# Getting started with FCC distributed computing + +## Registering to the FCC VO + +The [standard Grid VO registration procedure][signup] +should be followed to be enable to use the resources connected with the FCC VO. + +:::{admonition} Note +:class: callout + +You need to use a browser where you have installed your certificate and the CERN +CA certificates. Firefox usually works fine, Google Chrome usually does not +work. Safari might also work. +::: + +[signup]: https://voms2.cern.ch:8443/voms/fcc/aup/sign.action + +## Enabling DIRAC + +DIRAC available on CernVM-FS. To enable the relevant applications and scripts, the +following setup script needs first to be sourced + +```bash +source /cvmfs/clicdp.cern.ch/DIRAC/bashrc +``` + +To submit jobs through DIRAC a proxy needs to be created and uploaded: + +```bash +dirac-proxy-init -g fcc_user +``` +A successful creation looks like this: +``` +Generating proxy... +Enter Certificate password: +Added VOMS attribute /fcc +Uploading proxy.. +Proxy generated: +subject : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis/CN=2178341058/CN=3000266373 +issuer : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis/CN=2178341058 +identity : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis +timeleft : 23:53:58 +DIRAC group : fcc_user +path : /tmp/x509up_u2759 +username : ganis +properties : NormalUser +VOMS : True +VOMS fqan : ['/fcc'] + +Proxies uploaded: + DN | Group | Until (GMT) + /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis | | 2022/05/13 12:12 +``` +The last section shows the valid proxies upload to the DIRAC system. It can also be checked with +```bash +dirac-proxy-info -m +``` +with output similar to +``` +subject : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis/CN=2178341058/CN=3000266373 +issuer : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis/CN=2178341058 +identity : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis +timeleft : 23:50:40 +DIRAC group : fcc_user +path : /tmp/x509up_u2759 +username : ganis +properties : NormalUser +VOMS : True +VOMS fqan : ['/fcc'] +== Proxies uploaded == +DN | Group | Until (GMT) +/DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis | | 2022/05/13 12:12 +``` + +If everything worked fine, your proxy should be mapped to the `fcc001` user. This can be checked this way: + +```bash +export EOS_MGM_URL=root://eospublic.cern.ch +XrdSecPROTOCOL=gsi,unix eos whoami +``` +the result should look similar to this: +``` +Virtual Identity: uid=140035 (99,140035) gid=2855 (99,2855) [authz:gsi] host=lxplus743.cern.ch domain=cern.ch geo-location=0513 +``` + +At CERN the uid of `fcc001` is 140035. + +## The web portal + +The [DIRAC web portal][diracweb] is available to check the status of things. It shows all the jobs submmited and the +files registered. Some example screenshot is shown below. + + +:::{admonition} Note +:class: callout + +As for the VO registration, you need to use a browser where you have installed +your certificate and the CERN CA certificates. Firefox usually works fine, +Google Chrome usually does not work. Safari might also work. +::: + +[diracweb]: https://voilcdiracwebapp2.cern.ch/DIRAC/?view=tabs&theme=Crisp&url_state=1|*DIRAC.JobMonitor.classes.JobMonitor diff --git a/bnl2023/_sources/distributed-computing/Workflows.md.txt b/bnl2023/_sources/distributed-computing/Workflows.md.txt new file mode 100644 index 00000000..c090fd2c --- /dev/null +++ b/bnl2023/_sources/distributed-computing/Workflows.md.txt @@ -0,0 +1,16 @@ +# FCC DIRAC example workflows + +These pages provide - and dissect - examples of workflows to be run on distributed resources with the [DIRAC Interware system][dirac]. + +The python scripts discussed in these pages are available at [https://github.com/HEP-FCC/FCCDIRAC][fccdirac]. + +[dirac]: https://dirac.readthedocs.io/en/latest/ +[fccdirac]: https://github.com/HEP-FCC/FCCDIRAC + +```{eval-rst} +.. toctree:: + :caption: Contents: + + workflows/Overview.md + workflows/01/DiTauKKMCeeDelphesStandAlone.md +``` diff --git a/bnl2023/_sources/distributed-computing/workflows/01/DiTauKKMCeeDelphesStandAlone.md.txt b/bnl2023/_sources/distributed-computing/workflows/01/DiTauKKMCeeDelphesStandAlone.md.txt new file mode 100644 index 00000000..a5458c99 --- /dev/null +++ b/bnl2023/_sources/distributed-computing/workflows/01/DiTauKKMCeeDelphesStandAlone.md.txt @@ -0,0 +1,358 @@ +# Workflow 1 + +## Purpose + +Demonstrate the use of DIRAC generate 10000 tau+tau- events @91.2 GeV with KKMC and process through Delphes/IDEA. + +## Output files + +**Local mode**
+The output file is located under a sub-directory name `Local__JobDir` created under the current directory. + +**WMS mode**
+In WMS mode the file will be located under + +``` +/fcc/user///_///edm4hep_test_output.root +``` + +e.g. at CERN (storage element `CERN-DST-EOS`): + +``` +/eos/experiment/fcc/prod/fcc/user/g/ganis/2021_07/59821/59821752/edm4hep_test_output.root +``` + +## DIRAC components involved + +This exercise constist of two steps, the event generation with `KKMCee` and the `Delphes` simulation. + +For the first step we need the `KKMC` DIRAC application which we configure with the process, the number of events, the energy and +the name of the output file. + +The second step consists in running the `DelphesPythia8_EDM4HEP` standalone application with arguments + +1. The `Delphes` card implementing the IDEA detector concept; +2. The definition of the EDM4hep output; +3. The pythia card reading LHE file formats; +4. The output file. + +For this we use the generic application DIRAC interface. + +## The script, dissected + +The submission script for this workflow is called [FCC_Dirac_Workflow1.py][workflow1-py]. +The script accepts one argument to control where the job is executed: + +``` +python FCC_Dirac_Workflow1.py -h +``` + +``` + +Usage: + + FCC_Dirac_Workflow1.py (|)* + +General options: + -o --option : Option=value to add + -s --section : Set base section for relative parsed options + -c --cert : Use server certificate to connect to Core Services + -d --debug : Set debug mode (-ddd is extra debug) + - --cfg= : Load additional config file + - --autoreload : Automatically restart if there's any change in the module + - --license : Show DIRAC's LICENSE + -h --help : Shows this help + +Options: + -w --wms : WMS where to run +``` + +[workflow1-py]: https://raw.githubusercontent.com/HEP-FCC/FCCDIRAC/master/workflows/1/FCC_Dirac_Workflow1.py + +### The utility function + +```python +# Create sandbox files +import os +from shutil import copy2 +import array + +# Utility function +def copywithreplace(filein, fileout, repls): + # If no replacements, just copy the file + if len(repls) == 0: + copy2(filein, fileout) + return + # input file + fin = open(filein, "rt") + # output file to write the result to + fout = open(fileout, "wt") + # for each line in the input file + for line in fin: + # Apply each requested replacement + ltmp = line + for r in repls: + lout = ltmp.replace(str(r[0]), str(r[1])) + ltmp = lout + fout.write(lout) + # close input and output files + fin.close() + fout.close() +``` + +### Adding the `--wms` switch + +```python +from DIRAC import S_OK, S_ERROR +from DIRAC.Core.Base import Script + +# Define a simple class to hold the script parameters +class Params(object): + def __init__(self): + self.wms = 'wms' + def setWMS(self, value): + self.wms = value + return S_OK() + +# Instantiate the params class +cliParams = Params() +Script.registerSwitch('w', 'wms', "WMS where to run", cliParams.setWMS) +Script.parseCommandLine(ignoreErrors=False) +# Get the list of services (the switch above appearer as servicesList[0]) +servicesList = Script.getPositionalArgs() +print servicesList +``` + +### The DIRAC API instance + +```python +from ILCDIRAC.Interfaces.API.DiracILC import DiracILC + +dIlc = DiracILC() +``` + +### The DIRAC Job manager + +```python +from ILCDIRAC.Interfaces.API.NewInterface.UserJob import UserJob + +job = UserJob() +job.setOutputSandbox(['*.log', '*.sh', '*.py', '*.xml']) +outputdatafile='kktautau_delphes_edm4hep_output.root' +job.setOutputData(outputdatafile, '','CERN-DST-EOS' ) + +job.setJobGroup( "KKMC_EDM4HEP_Run" ) +job.setName( "KKMC_EDM4HEP" ) +job.setLogLevel("DEBUG") +``` + +### The `KKMC` application instance + +```python +from ILCDIRAC.Interfaces.API.NewInterface.Applications import KKMC + +kkmc = KKMC() +kkmc.setVersion('Key4hep-2021-04-30') +kkmc.setEvtType('Tau') +kkmc.setEnergy(91.2) +nevts = 10000 +outputfile = 'kktautau_delphes_' + str(nevts) + '.LHE' +kkmc.setNumberOfEvents(nevts) +kkmc.setOutputFile(outputfile) + +job.append(kkmc) +``` + +### The steering files for `Delphes` + +```python +# Delphes card +delphescardpath=os.path.expandvars('$DELPHES/cards/delphes_card_IDEA.tcl') +delphescard=os.path.basename(delphescardpath) +copy2(delphescardpath, delphescard) +# EDM4hep output definition +edm4hepoutdefpath=os.path.expandvars('$K4SIMDELPHES/edm4hep_output_config.tcl') +edm4hepoutdef=os.path.basename(edm4hepoutdefpath) +copy2(edm4hepoutdefpath, edm4hepoutdef) +# Pythia card +pythiacardpath=os.path.expandvars('$K4GEN/Pythia_LHEinput.cmd') +pythiacard=os.path.basename(pythiacardpath) +replacements = [['Main:numberOfEvents = 100','Main:numberOfEvents = ' + str(nevts)], + ['Beams:LHEF = Generation/data/events.lhe','Beams:LHEF = ' + outputfile]] +copywithreplace(pythiacardpath, pythiacard, replacements) +``` + +### Completing the sandbox for `Delphes` + +```python +# Set the sandbox content +job.setInputSandbox(['./' + delphescard, './' + edm4hepoutdef, './' + pythiacard]) +``` + +### Standalone `Delphes` using the DIRAC generic application + +```python +from ILCDIRAC.Interfaces.API.NewInterface.Applications import GenericApplication + +ga = GenericApplication() +ga.setSetupScript("/cvmfs/sw.hsf.org/spackages2/key4hep-stack/2021-04-30/x86_64-centos7-gcc8.3.0-opt/t5gcd6ltt2ikybap2ndoztsg5uyorxzg/setup.sh") +ga.setScript("/cvmfs/sw.hsf.org/spackages2/k4simdelphes/00-01-05/x86_64-centos7-gcc8.3.0-opt/beesqo4r5wuqrrijyz57kxbqcdp5pp4v/bin/DelphesPythia8_EDM4HEP") +ga.setArguments(delphescard + ' ' + edm4hepoutdef + ' ' + pythiacard + ' ' + outputdatafile) + +job.append(ga) +``` + +### Submitting the job to the chosen WMS + +```python +submitmode='wms' +if len(servicesList) > 0: + submitmode= servicesList[0] +print job.submit(dIlc, mode=submitmode) +``` + +## Running the script on lxplus + +Suggestion is, after having cloned the repository and initialized the environment, to go to the workflow sub-directory, created a 'run' sub-directory and run +from there: + +``` +$ cd workflow/1 +$ mkdir run; cd run +``` + +### Local submission + +```bash +$ python ../FCC_Dirac_Workflow1.py --wms local +``` + +``` +['local'] +kkmc Key4hep-2021-04-30 +Attribute list : + forgetAboutInput: Not defined + randomSeed: -1 + outputSE: Not defined + seedFile: Not defined + energy: 91.2 + ... + logFile: kkmc_Key4hep-2021-04-30_Step_1.log + +ApplicationScript +Attribute list : + forgetAboutInput: Not defined + outputSE: Not defined + energy: 91.2 + ... + logFile: ApplicationScript_Step_2.log + + +Proceed and submit job(s)? y/[n] : y + +[long output] + +2021-07-28 16:27:53 UTC dirac-jobexec/ILCDIRAC.Workflow.Modules.UserJobFinalization INFO: GUID = CCADDA80-3B2E-7E9C-3C14-5A493AB48BD4 +2021-07-28 16:27:53 UTC dirac-jobexec DEBUG: Workflow execution successful, exiting +{'OK': True, 'Value': 'Execution completed successfully'} +``` + +The local sandbox should contain the following: + +``` +$ ls -lt +``` +``` +total 32 +drwx------. 2 ganis sf 2048 Jul 28 18:27 Local_pQl06k_JobDir +-rw-r--r--. 1 ganis sf 1483 Jul 28 18:25 Pythia_LHEinput.cmd +-rw-r--r--. 1 ganis sf 587 May 10 15:31 edm4hep_output_config.tcl +-rw-r--r--. 1 ganis sf 27219 Apr 30 14:50 delphes_card_IDEA.tcl +``` + +and the output directory: + +``` +$ ls -lt Local_pQl06k_JobDir/kktautau* +-rw-r--r--. 1 ganis sf 9642099 Jul 28 18:27 Local_pQl06k_JobDir/kktautau_delphes_edm4hep_output.root +-rw-r--r--. 1 ganis sf 32586567 Jul 28 18:27 Local_pQl06k_JobDir/kktautau_delphes_10000.LHE +$ ls -lt Local_pQl06k_JobDir/*.log +-rw-r--r--. 1 ganis sf 257109 Jul 28 18:27 Local_pQl06k_JobDir/ApplicationScript_Step_2.log +-rw-r--r--. 1 ganis sf 44250 Jul 28 18:27 Local_pQl06k_JobDir/kkmc_Key4hep-2021-04-30_Step_1.log +-rw-r--r--. 1 ganis sf 900532 Jul 28 18:27 Local_pQl06k_JobDir/localEnv.log +``` + +### WMS submission + +```bash +python ../FCC_Dirac_Workflow1.py +``` + +``` +... +Proceed and submit job(s)? y/[n] : +y +... +'Value': 59838136, 'JobID': 59838136} +``` + +The `JobID` defines uniquely the job and can be used for any operation, for example to check the status: + +``` +dirac-wms-job-status 59838136 +``` + +``` +JobID=59838136 Status=Waiting; MinorStatus=Pilot Agent Submission; Site=ANY; +``` + +or, when the job is finished, get the job files: + +``` +$ dirac-wms-job-get-output 59838136 +``` +``` +Job output sandbox retrieved in /afs/cern.ch/user/g/ganis/local/dirac/GIT/FCCDIRAC/workflows/1/run/59838136/ +$ ls -lt 59838136/ +total 1295 +-rw-r--r--. 1 ganis sf 273338 Jul 28 19:13 std.out +-rw-r--r--. 1 ganis sf 38583 Jul 28 19:13 std.err +-rw-r--r--. 1 ganis sf 256445 Jul 28 19:13 ApplicationScript_Step_2.log +-rw-r--r--. 1 ganis sf 464310 Jul 28 19:12 localEnv.log +-rw-r--r--. 1 ganis sf 43690 Jul 28 19:12 kkmc_Key4hep-2021-04-30_Step_1.log +-rwxr-xr-x. 1 ganis sf 559 Jul 28 19:12 kkmc_Key4hep-2021-04-30_Run_1.sh +-rw-r--r--. 1 ganis sf 227185 Apr 30 15:47 setup.sh +-rw-r--r--. 1 ganis sf 19080 Jan 1 1970 jobDescription.xml +``` +or get the output data: + +``` +$ dirac-wms-job-get-output-data 59838136 +``` + +``` +Job 59838136 output data retrieved +$ ls -lt kktautau_delphes_edm4hep_output.root +-rwxr-xr-x. 1 ganis sf 9652641 Jul 29 11:30 kktautau_delphes_edm4hep_output.root +``` + +The output data are also available on storage element: + +``` +$ ls -lt /eos/experiment/fcc/prod/fcc/user/g/ganis/2021_07/59838/59838136/ +``` +``` +total 9427 +-rw-r--r--. 1 fcc001 fcc-cg 9652641 Jul 28 19:13 kktautau_delphes_edm4hep_output.root +``` + +The job id of the user jobs get also be retrieved with the `dirac-wms-select-jobs` command, e.g. +``` +$ dirac-wms-select-jobs --Date=2021-07-28 --Owner="ganis" +``` +``` +==> Selected 1 jobs with conditions: Date = 2021-07-28, Owner = ganis +59838136 +``` +or from the web portal. + diff --git a/bnl2023/_sources/distributed-computing/workflows/Overview.md.txt b/bnl2023/_sources/distributed-computing/workflows/Overview.md.txt new file mode 100644 index 00000000..cd9af288 --- /dev/null +++ b/bnl2023/_sources/distributed-computing/workflows/Overview.md.txt @@ -0,0 +1,155 @@ +# Overview of the submission scripts + +Command line submission to DIRAC is performed using python scripts instantiating the relevant classes. +The general structure of the script is the following: + +1. Instantiation of the interface to DIRAC; +2. Creation of a Job manager instance, including input and output sandbox, and all relevant config and data files; +3. Creation and configuration of the application to be run and their registration to the job manager instance; +4. Job submission + +The script may contain or import all the code relevant to the correct definition of the various steps above. +DIRAC also provides some standard tooling for parsing arguments and homogenize the submission script experience. + +The parser is defined the DIRAC core, is part of the generic definition of [Script][script] and provides a callback for +customizing the actions. Typical usage looks like this: + +```python +from DIRAC import S_OK, S_ERROR +from DIRAC.Core.Base import Script + +# Define a simple class to hold the script parameters +class Params(object): + def __init__(self): + self.wms = 'wms' + def setWMS(self, value): + self.wms = value + return S_OK() + +# Instantiate the params class +cliParams = Params() +Script.registerSwitch('w', 'wms', "WMS where to run", cliParams.setWMS) +Script.parseCommandLine(ignoreErrors=False) + +# Get the list of services (the switch above appearer as servicesList[0]) +servicesList = Script.getPositionalArgs() +# The value for argument 'wms' is the first entry in servicelist list + +``` + +[script]: https://dirac.readthedocs.io/en/latest/CodeDocumentation/Core/Base/Script.html + +The DIRAC interface is controlled by the API interface class `DiracILC`, which derives from the upstream [DIRAC API][diracapi]. +Typical usage is the following: + +```python +from ILCDIRAC.Interfaces.API.DiracILC import DiracILC +... +dIlc = DiracILC() +``` + +The returned `dILc` variable contais the API context to be used when relevant. + +[diracapi]: https://raw.githubusercontent.com/DIRACGrid/DIRAC/integration/src/DIRAC/Interfaces/API/Dirac.py + +The job manager is an instance of `UserJob` - which derives from [Job][job] - is instantiated next. +Typical usage is the following: + +```python +from ILCDIRAC.Interfaces.API.NewInterface.UserJob import UserJob +... +job = UserJob() +job.setOutputSandbox(['*.log', '*.sh', '*.py', '*.xml']) +outputdatafile='kktautau_delphes_edm4hep_output.root' +job.setOutputData(outputdatafile, '','CERN-DST-EOS' ) +job.setJobGroup( "KKMC_EDM4HEP_Run" ) +job.setName( "KKMC_EDM4HEP" ) +job.setLogLevel("DEBUG") +... +# Information can be added thorugh out the script +delphescard='delphes_card_IDEA.tcl' +... +# Set the sandbox content +job.setInputSandbox(['./' + delphescard, './' + edm4hepoutdef, './' + pythiacard]) +``` + +[job]: https://dirac.readthedocs.io/en/latest/UserGuide/GettingStarted/UserJobs/ + +Applications are created, configured and added to the job manager in the order of running: +An example is the following: + +```python +from ILCDIRAC.Interfaces.API.NewInterface.Applications import KKMC +... +kkmc = KKMC() +kkmc.setVersion('Key4hep-2021-04-30') +kkmc.setEvtType('Tau') +kkmc.setEnergy(91.2) +nevts = 10000 +outputfile = 'kktautau_delphes_' + str(nevts) + '.LHE' +kkmc.setNumberOfEvents(nevts) +kkmc.setOutputFile(outputfile) + +job.append(kkmc) +``` + +Available applications defined in [here][diracapp]. + +[diracapp]: https://gitlab.cern.ch/CLICdp/iLCDirac/ILCDIRAC/-/tree/Rel-v31r0/Interfaces/API/NewInterface + +Finally the job is submitted: + +```python +print job.submit(dIlc, mode='wms') +# Use wms='local' for running on the local computer +``` + +Local submission can be used for testing. + +## Before starting: cloning of workflows repository + +The example scripts described in these pages, together with the relevant setup scripts, are available from the +[FCCDIRAC][fccdirac] repository. + +The following steps must be executed (only once!) before trying to execute any of the workflows: + +```bash +$ git clone https://github.com/HEP-FCC/FCCDIRAC +$ cd FCCDIRAC + +$ source init_fcc.sh +Setting up the latest Key4HEP software stack from CVMFS ... + ... Key4HEP release: key4hep-stack/2021-07-16 + ... Use the following command to reproduce the current environment: + ... + source /cvmfs/sw.hsf.org/spackages2/key4hep-stack/2021-07-16/x86_64-centos7-gcc8.3.0-opt/wxwfgu65rjnk7s6frj25qsoq5miay4ft/setup.sh + ... + ... done. + +$ source init_dirac.sh +Setting the iLCDirac environment ... + +$ source init_dirac_proxy.sh +Initializing the DIRAC/Grid proxy ... +Generating proxy... +Enter Certificate password: +Added VOMS attribute /fcc +Uploading proxy.. +Proxy generated: +subject : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis/CN=2888907760/CN=1791020771 +issuer : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis/CN=2888907760 +identity : /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis +timeleft : 23:53:59 +DIRAC group : fcc_user +path : /tmp/x509up_u2759 +username : ganis +properties : NormalUser +VOMS : True +VOMS fqan : ['/fcc'] + +Proxies uploaded: + DN | Group | Until (GMT) + /DC=ch/DC=cern/OU=Organic Units/OU=Users/CN=ganis/CN=393971/CN=Gerardo Ganis | | 2022/05/13 12:12 +``` + +[fccdirac]: https://github.com/HEP-FCC/FCCDIRAC diff --git a/bnl2023/_sources/fast-sim-and-analysis/EventProduction.md.txt b/bnl2023/_sources/fast-sim-and-analysis/EventProduction.md.txt new file mode 100644 index 00000000..db25cde9 --- /dev/null +++ b/bnl2023/_sources/fast-sim-and-analysis/EventProduction.md.txt @@ -0,0 +1,334 @@ +# Central production of events + +The central production of events for FCC physics studies is done using the +[EventProducer](https://github.com/HEP-FCC/EventProducer) framework. + +:::{admonition} Get in touch with coordinators +:class: prereq +In order to use the [EventProducer](https://github.com/HEP-FCC/EventProducer), +please get in contact with the FCC software and computing coordinators as +running central production of events requires specific rights +[(see here)](https://hep-fcc.github.io/FCCSW/computing/computing.html). + +When samples produced by the [EventProducer](https://github.com/HEP-FCC/EventProducer) +framework are ready they will appear on this +[web-page](http://fcc-physics-events.web.cern.ch/). +::: + + +## Clone and initialisation + + +If you do not attempt to contribute to the repository, simply clone it: + +```shell +git clone git@github.com:HEP-FCC/EventProducer.git +``` + +If you aim at contributing to the repository, you need to fork and then clone the forked repository: + +```shell +git clone git@github.com:YOURGITUSERNAME/EventProducer.git +``` + +Then initialise: + +```shell +source ./init.sh +``` + +In order to run batch generation, please add your CERN user name to the userlist in `config/users.py` + +## Generate LHE files from gripacks + +To send jobs starting from a gridpack that does not exist but that you have produced, do the following: + - place gridpack on eos + - for FCC-hh `/eos/experiment/fcc/hh/generation/gridpacks/` + - for FCC-ee `/eos/experiment/fcc/ee/generation/gridpacks/` + - if the gridpack is from Madgraph, name it `mg_process` (and call option `gp_mg` when running generation commands), if from powheg please name it `pw_process` (and call option `gp_pw`), + - add to `config/param_FCCee/hh.py` an entry corresponding to the gridpack name in the `gridpacklist` list, depending on the study. + +If the gridpack already exists and has been properly added to the correct `config/param_FCCee/hh.py`, then simply run: + +```shell +python bin/run.py --FCCee --LHE --send --condor --typelhe gp_mg -p -n -N -q --prodtag --detector +``` + +example to send 10 jobs of 10 000 events of ZHH events at 365GeV using the longlunch queue of HTCondor for FCC--ee for the spring2021 production tag and the IDEA detector: + +```shell +python bin/run.py --FCCee --LHE --send --condor --typelhe gp_mg -p mg_ee_zhh_ecm365 -n 10000 -N 10 -q longlunch --prodtag spring2021 --detector IDEA +``` + +The options `--ncpus` and `--priority` can also be specified to increase the numbers of cpus on the cluster and to change the priority queue. + + +## Generate LHE files directly from MG5 + + +To send jobs directly from MG5, you need a configuration file (see in `mg5/examples` directory `*.mg5`) and, optionally: + - a `cuts.f` file (containing additional cuts) + - a model (see in `models` directory for instance) + +:::{admonition} Nota Bene +:class: callout + +At the moment no example is generated for FCC-ee this way. Below is an example +for FCC-hh. +::: + +As before, you need to add the process to the `config/param_FCChh.py` file. Then you can run with the following command: + +```shell +python bin/run.py --FCC --LHE --send --condor --typelhe mg -p mg_pp_hh_test --mg5card mg5/examples/pp_hh.mg5 --model mg5/models/loop_sm_hh.tar -N 2 -n 10000 -q workday --memory 16000. --disk 8000. +``` + +The options `--ncpus` and `--priority` can also be specified to increase the numbers of cpus on the cluster and to change the priority queue. + +## Generate STDHEP files directly from Whizard + Pythia6 + +This section describe how to send Whizard + Pythia6 jobs and produce STDHEP files. The steps to be followed can be described as: +1. Define process in `gridpacklist` in `config/param_FCCee/.py`. +2. Write the Whizard sin card and put it in: `/eos/experiment/fcc/ee/generation/FCC-config//FCCee/Generator/Whizard/` by making a Pull Request to the corresponding production tag branch of [FCC-config](https://github.com/HEP-FCC/FCC-config/) for example `wzp6_ee_eeH_ecm240.sin` +3. Once the Pull Request is approved and the file has appeared on the corresponding `` on `eos` +4. Send jobs + +```shell +python bin/run.py --FCCee --STDHEP --send --typestdhep wzp6 --condor -p -N -n --prodtag -q +``` + +Example produce 1 job of 10000 events of mumuH at FCC-ee 240GeV + +```shell +python bin/run.py --FCCee --STDHEP --send --typestdhep wzp6 --condor -p wzp6_ee_mumuH_ecm240 -N 1 -n 10000 --prodtag spring2021 -q longlunch +``` + +## Generate EDM4hep files from the LHE and decay with Pythia8 + +1. If you want to let Pythia decay without specifying anything, you can use the default card, but if you have requested extra partons at matrix element, you might need to specify matching parameters to your pythia card +2. If you want to use a specific decay, make sure that the decay you want is in `decaylist` and `branching_ratios` of the `config/param_FCCee/hh.py` +3. Then create appropriate Pythia8 card, by appending standard card with decay syntax if needed and add it to the proper directory. +For a given production tag of FCC-ee this directory is: + +```shell +/eos/experiment/fcc/ee/generation/FCC-config//FCCee/Generator/Pythia8/ +``` + +:::{admonition} Nota Bene +:class: callout + +Please do not write directly on EOS. Cards should be added by making a +documented pull request to the corresponding production tag branch in +[FCC-config](https://github.com/HEP-FCC/FCC-config/). +::: + +4. Send the jobs: + +```shell +python bin/run.py --FCChh/FCCee --reco --send --type lhep8 --condor -p -N -q --prodtag --detector +``` + +Example produce 10 jobs of FCC Delphes events of ttz decaying the Z to neutrinos. : + +```shell +python bin/run.py --FCCee --reco --send --type lhep8 --condor -p mg_ee_zhh_ecm365 -N 10 -q workday --prodtag spring2021 --detector IDEA +``` + +Please note that the decay in pythia is optional, and that there is no need to specify the number of events to run on as it will by default run over all the events present in the LHE file + +The options `--ncpus` and `--priority` can also be specified to increase the numbers of cpus on the cluster and to change the priority queue. + + +## Generate EDM4hep files from STDHEP + +To produce Delphes EDM4hep files from STDHEP, just run this kind of command + +```shell +python bin/run.py --FCCee --reco --send --type stdhep --condor -p -N -q --prodtag --detector +``` + +For example to run over one STDHEP file of mumuH process: + +```shell +python bin/run.py --FCCee --reco --send --type stdhep --condor -p wzp6_ee_mumuH_ecm240 -N 1 -q longlunch --prodtag spring2021_training --detector IDEA +``` + + +## Generate EDM4hep files from Pythia8 + +This section describe the way most of the events were produced, using Pythia directly. The steps to be followed can be described as: +1. Define process in `pythialist` in the `config/param_FCCee/hh.py` corresponding to your FCC choice. +2. Write Pythia8 process card and put it in: `/eos/experiment/fcc/ee/generation/FCC-config//FCCee/Generator/Pythia8` by making a Pull Request to the corresponding production tag branch of [FCC-config](https://github.com/HEP-FCC/FCC-config/) for example `p8_ee_Zbb_ecm91.cmd` +3. Once the Pull Request is approved and the file has appeared on the corresponding `` on `eos`, send jobs + +```shell +python bin/run.py --FCC-hh/FCCee --reco --send --type p8 --condor -p --pycard -n -N -q --prodtag --detector +``` + +Example produce 1 job of 10000 events of ZH at FCC-ee 240GeV + +```shell +python bin/run.py --FCCee --reco --send --type p8 -p p8_ee_ZH_ecm240 -n 10000 -N 1 --condor -q longlunch --prodtag spring2021 --detector IDEA +``` + +The options `--ncpus` and `--priority` can also be specified to increase the numbers of cpus on the cluster and to change the priority queue. + +:::{admonition} Important +:class: callout + +If `--pycard` option is not specified, this step will run with the default +Pythia8 card (in this case `p8_ee_default.cmd`), that does not include specific +decays nor specific matching/merging parameters. +::: + +To assist you in writing your own Pythia8 configuration cards, the manual is available [here](http://home.thep.lu.se/~torbjorn/pythia81html/Welcome.html) + +## Expert mode + +The following commands should be run with care, as they update the database, web-page etc... +They run automatically every four hours with crontab, thus you will eventually know when your samples are ready to be used by browsing the corresponding configuration on this [web-page](http://fcc-physics-events.web.cern.ch/). +The `--force` option is used to force the script to run in order to optimize running time, processes that have not been flagged will not be checked. + +### Updating the database + +1. First one need to check the eos directories that have been populated with new files. + +Example for LHE: + +```shell +python bin/run.py --FCCee --LHE --checkeos [--process process] [--force] +``` + +Example for Delphes events: + +```shell +python bin/run.py --FCCee --reco --checkeos --prodtag spring2021 [--process process] [--force] +``` + +2. Second one need to check the quality of the files that have been produced. +Example for LHE: + +```shell +python bin/run.py --FCCee --LHE --check [--process process] [--force] +``` + +Example for Delphes events: + +```shell +python bin/run.py --FCCee --reco --check --prodtag spring2021 [--process process] [--force] +``` + +3. Then the checked files needs to be merged (individual yaml files are created for each file produced and the information needs to be aggregated): +Example for LHE: + +```shell +python bin/run.py --FCCee --LHE --merge [--process process] [--force] +``` + +Example for Delphes events: + +```shell +python bin/run.py --FCCee --reco --merge --prodtag spring2021 [--process process] [--force] +``` + +### Cleaning bad jobs + +To clean jobs that are flagged as bad, the following command can be used for LHE: + +```shell +python bin/run.py --FCCee --LHE --clean [--process process] +``` + +and for Delphes + +```shell +python bin/run.py --FCCee --reco --clean --prodtag spring2021 [--process process] +``` + +As the code checks the files that are in the end written on eos, we need to clean also old jobs that don't produced outputs 3 days after they started. +To do so run the following command for LHE + +```shell +python bin/run.py --FCCee --LHE --cleanold [--process process] +``` + +and for Delphes + +```shell +python bin/run.py --FCCee --reco --cleanold --prodtag spring2021 [--process process] +``` + +If you want to completly remove a process, the following command can be used with care for LHE: + +```shell +python bin/run.py --FCCee --LHE --remove --process process +``` + +and for Delphes + +```shell +python bin/run.py --FCCee --reco --remove --process process --prodtag spring2021 +``` + + +### Update the webpage + +The webpage can be updated after the files have been checked and merged by running for LHE + +```shell +python bin/run.py --FCCee --LHE --web +``` + +and for Delphes + +```shell +python bin/run.py --FCCee --reco --web --prodtag spring2021 +``` + + +### Create the sample list for analyses + +To create the list of samples to be used in physics analyses for `spring2021` production tag: + +```shell +python bin/run.py --FCCee --reco --sample --prodtag spring2021 +``` + +### All in One + +a script can be used to do all the steps in one go, for example for LHE at FCC-ee: + +```shell +./scripts/cronrun_LHE_FCCee.sh +``` + +and for Delphes events: + +```shell +./scripts/cronrun_RECO_FCCee.sh +``` + +for example for Delphes events with `spring2021` production tag and `IDEA` detector: + +```shell +./scripts/cronrun_RECO_FCCee.sh spring2021 IDEA +``` + +## Produce samples with EventProducer outside of official campaign + +This section explains how you can use the EventProducer to produce your own database of events. +1. You first need to create three output directories with sufficient disk space. One where the samples could be written, for example on your CERN `eos`. An other public directory to store the database that is created and associate each job/file on eos, and one that can be browsed from the web, for example using your eos cern box for all: + +```shell +For samples /eos/home-//generation/ +For public /eos/home-//public/FCCDicts/ +For web /eos/home-//www/data/FCCee/ +``` + +2. Edit the file `config/param_FCCee.py`: + - Replace `webbasedir` by your directory `For web` + - Replace `pubbasedir` by your directory `For public` + - Replace `eosbaseoutputdir` by `For samples` + - If you want to use your own `FCC-config`, also replace `eosbaseinputdir` to point to where it is cloned. + +3. You should now be ready to send jobs using your own work areas, you will have to run the checks yourself, have a look at the [Expert mode](#expert-mode) diff --git a/bnl2023/_sources/fast-sim-and-analysis/FCCAnalysesProblemsAndSolutions.md.txt b/bnl2023/_sources/fast-sim-and-analysis/FCCAnalysesProblemsAndSolutions.md.txt new file mode 100644 index 00000000..ffe934bd --- /dev/null +++ b/bnl2023/_sources/fast-sim-and-analysis/FCCAnalysesProblemsAndSolutions.md.txt @@ -0,0 +1,568 @@ +# FCCAnalyses: Common problems and solutions + +This directory contains a number of examples each showcasing a specific functionality of the FCCAnalyses framework. It serves as a reference guide for how to implement specific common usecases or you can work through the examples one-by-one in order as a tutorial to familiarize yourself with the full functionality of the framework. + +Each example is a stand-alone script for demonstration purposes, and does not make assumptions on a specific physics case. To understand how to write a full analysis with the FCCAnalyses framework please have a look at (insert a link to documentation about code class-structure) - the examples here only illustrate specific technical functionalities. + +By calling `python .py` you can run the specific example over the integrated test file found (add the testdata directory), and it will create a new directory in your current working directory with the name of the example to write the output to. If you prefer to run over your own input file or a different output directory you can run with options: + +```sh +python .py -i -o +``` + +Certain examples may have additional options, you can always check what options +are available with `python .py -h`. + + +## Prerequisites + +The FCCAnalyses framework is based on the [RDataFrame](https://root.cern/doc/master/classROOT_1_1RDataFrame.html) interface which allows fast and efficient analysis of [ROOT's TTrees](https://root.cern/doc/master/classTTree.html) and on samples following the [EDM4HEP event data model](https://edm4hep.web.cern.ch/). Some brief explanations and links to further material on the two are given below, a basic understanding of both is necessary for using this framework to write your own analysis code. + + +### EDM4hep event model + +```{figure} https://github.com/key4hep/EDM4hep/raw/master/doc/edm4hep_diagram.svg +:align: center + +EDM4hep event data model overview. +``` + +The EDM4hep data model attempts to describe event data with the set of standard +datatypes. It is described in a single +[YAML file](https://github.com/key4hep/EDM4hep/blob/master/edm4hep.yaml) and +generated with the help of [Podio](https://github.com/AIDASoft/podio). For +example the datatype for the calorimeter hit has following members: +``` +#------------- CalorimeterHit +edm4hep::CalorimeterHit: + Description: "Calorimeter hit" + Author : "F.Gaede, DESY" + Members: + - uint64_t cellID //detector specific (geometrical) cell id. + - float energy //energy of the hit in [GeV]. + - float energyError //error of the hit energy in [GeV]. + - float time //time of the hit in [ns]. + - edm4hep::Vector3f position //position of the hit in world coordinates in [mm]. + - int32_t type //type of hit. Mapping of integer types to names via collection parameters "CalorimeterHitTypeNames" and "CalorimeterHitTypeValues". +``` + +[Link to EDM4HEP class overview](https://edm4hep.web.cern.ch/namespaceedm4hep.html) + + +(structure-of-edm4hep-files)= +### Structure of EDM4hep files + +The content of an EDM4hep file can be seen by opening it in ROOT, and by +inspecting the content of the `events` tree with a TBrowser. Example with a +file from the "spring2021" campaign: + +```sh +root -l /eos/experiment/fcc/ee/generation/DelphesEvents/spring2021/IDEA/wzp6_ee_mumuH_ecm240/events_012879310.root +root[0] TBrowser b +``` + +```{figure} images/browser_events.png +:align: center +:class: with-border + +Example file from "spring2021" campaign in ROOT TBrowser. +``` + +As shown in the screenshot above, there are two types of branches: + +1. Branches without a pound sign (`#`) in their name like: `Electron`, `Muon`, ... + They refer to collections of objects. +:::{admonition} Nota Bene +:class: callout +`Particle` denotes the collection of Monte-Carlo particles. `Muon` contains the +isolated muons, while `AllMuon` contains all muons, isolated or not. +::: + +2. Branches with a pound sign in their name: + Each of the object collections listed above, e.g. `Collection`, has up to six + associated collections of references, i.e. indices that point to another or to + the same object collection. They are labeled `Collection#i`, with + `i = 0 ... 5`. For example, the `Muon` collection has one single associated + collection of references, `Muon#0`. + +To figure out which collection is pointed to by `Muon#0` (or by any other +collection of references), one can look at the value of `Muon#0.collectionID` +(see screenshot below). +The `collectionID` of `Muon#0` is the collection number `7` (in the example file +used here), which, in the list of "object collections" above, corresponds to the +collection of `ReconstructedParticles`. +Indeed, the `Muon` collection itself contains nothing (see screenshot below): +all the information is contained in the `ReconstructedParticles`. The `Muon` +collection, together with `Muon#0`, just provides a convenient way to access, +among the `ReconstructedParticles`, those that were identified as muons. + +```{figure} images/browser_Muon0.png +:align: center +:class: with-border + +Muon collection example. +``` + +The same holds for the `Electron` and `Photon` collections. On the other hand, +the `MissingET` collection is already a `ReconstructedParticle`, as can be seen +by inspecting it in the TBrowser: + +```{figure} images/browser_missingET.png +:align: center +:class: with-border + +Missing $E_T$ collection example. +``` + +The `Particle` collection corresponds to the Monte-Carlo particles. It has two +associated collections of references, `Particle#0` and `Particle#1`. As can +be seen by looking at their collectionID, they both point to collection number +5, i.e. to the Particle collection itself. Particle#0 and Particle#1 contain, +respectively, links to the parents and to the daughters of the MC particles --- +as can be seen in the +[EDM4hep yaml description here](https://github.com/key4hep/EDM4hep/blob/master/edm4hep.yaml#L156-L157). +Examples will be given below, showing how to navigate through the Monte-Carlo +record using `Particle`, `Particle#0` and `Particle#1`. + + +## Overall organisation of analysis code (C++) + +All the common code lives in `FCCAnalyses` namespace which is by default loaded +when running `fccanalysis` command. Then each module of analyzers in one header +file has its own dedicated namespace, thus to call a given function from a given +module it should look like `FCCAnalyses::::` but +`::` should also work. For example, to call `get_px` +from the `ReconstructedParticle` module write: +`ReconstructedParticle::get_px()`. + + +## Reading objects from EDM4hep + +The example +[read_EDM4HEP.py](https://github.com/HEP-FCC/FCCAnalyses/blob/master/examples/basics/read_EDM4HEP.py) shows you how to access the different objects such as jets, electrons, muons, +missing $E_T$ etc. from the EDM4hep files. Generally a new variable is +calculated with a statement inside the `analysers(df)` function of the +`RDFanalysis` class like +`dataframe.Define("", ")>")` +which creates a column in the RDataFrame named `` filled with the +return value of the `` for the given object. + +Here, accessor functions are the functions found in the C++ analyzers code that +return a certain variable. Since the analyzers code defines a specific namespace +for each module, such as ReconstructedParticle or MCParticle, the full accessor +function call looks like `::(object)`. To access the +$p_T$ of a reconstructed object you would therefore call +`ReconstructedParticle::get_pt(object)` and for a MC-particle the call would be +`MCParticle::get_pt(object)`. The namespace corresponds to the file name of the +C++ code, making it clear where to look for the source code if you have a +question about the internal workings of one such functions. + +Below you can find an overview of the basic, most commonly required functions, +to illustrate the naming conventions. This is not an exhaustive list, if you +want to find out all functions that are available please take a look in the +respective analyzers code itself --- +[here for reconstructed particles](https://github.com/HEP-FCC/FCCAnalyses/blob/master/analyzers/dataframe/FCCAnalyses/ReconstructedParticle.h) +and +[here for MC particles](https://github.com/HEP-FCC/FCCAnalyses/blob/master/analyzers/dataframe/FCCAnalyses/MCParticle.h). + + +| Variable | Function name | Available for | +| ------------- | ------------- | ------------- | +| Transverse momentum | `get_pt(object)` | `MCParticle`, `ReconstructedParticle` | +| Pseudorapidity | `get_eta(object)` | `MCParticle`, `ReconstructedParticle` | +| Energy | `get_e(object)` | `MCParticle`, `ReconstructedParticle` | +| Mass | `get_mass(object)` | `MCParticle`, `ReconstructedParticle` | +| Charge | `get_charge(object)` | `MCParticle`, `ReconstructedParticle` | +| Number (in event) | `get_n(object)` | `MCParticle`, `ReconstructedParticle` | +| PDG ID | `get_pdg(object)` | `MCParticle` | + + +If you want to add your own function have a look at the +[Writing a new analyzer](#writing-a-new-analyzer) section on this page. + +For the name of the object, in principle the names of the EDM4hep collections +are used --- photons, muons and electrons are an exception where a few extra +steps are required, as shown in the example here. + +This example also shows how to apply object selection cuts, for example +selecting only reconstructed objects with a transverse momentum $p_T$ larger +than a given threshold by using the +`ReconstructedParticle::sel_pt()()` function. + +In the end of the example you can see how the selected variables are written to +branches of the output n-tuple, using the +`dataframe.Snapshot("", )`, where in all examples here +the name of the output-tree is always `events` and the branch_list is defined as +a `ROOT.vector('string')` as demonstrated in the example. Note that branches of +variables that exist multiple times per event, i.e. anything derived from a +collection such as the $p_T$ of jets, result in vector branches. This is also +true for some quantities that in principle only exist once per event, but are +collections in the EDM4hep format, such as the missing transverse energy. + + +## Association between `RecoParticles` and `MonteCarloParticles` + +By design, the association between the reconstructed particles and the +Monte-Carlo particles proceeds via the `MCRecoAssociations` collection, and its +two associated collections of references, `MCRecoAssociations#0` and +`MCRecoAssociations#1`, all of the same size. The collectionID of +`MCRecoAssociations#0` is equal to 7 in the example file used here (see above, +[](structure-of-edm4hep-files)), which means that `MCRecoAssociations#0` points +to the `ReconstructedParticles`. While the collectionID of +`MCRecoAssociations#1` is equal to 5, i.e. `MCRecoAssociations#1` points to the +Particle collection (i.e. the Monte-Carlo particles). + +Their usage is best understood by looking into the code of +[ReconstructedParticle2MC::getRP2MC_index](https://github.com/HEP-FCC/FCCAnalyses/blob/96c132c452469d4f66c8752c0397ba542d61cf75/analyzers/dataframe/src/ReconstructedParticle2MC.cc#L126-L136) +reported below: + +```cpp +ROOT::VecOps::RVec +ReconstructedParticle2MC::getRP2MC_index(const ROOT::VecOps::RVec& recind, + const ROOT::VecOps::RVec& mcind, + const ROOT::VecOps::RVec& reco) { + ROOT::VecOps::RVec result; + result.resize(reco.size(),-1.); + for (size_t i=0; i +MCParticle::get_list_of_particles_from_decay(int i, + const ROOT::VecOps::RVec& in, + const ROOT::VecOps::RVec& ind) { + + std::vector res; + + // i = index of a MC particle in the Particle block + // in = the Particle collection + // ind = the block with the indices for the daughters, Particle#1.index + + // returns a vector with the indices (in the Particle block) of the daughters of the particle i + + int db = in.at(i).daughters_begin ; + int de = in.at(i).daughters_end; + if ( db == de ) return res; // particle is stable + for (int id = db; id < de; id++) { + res.push_back( ind[id] ) ; + } + + return res; +} +``` + +This returns the "first branching" daughters. For example, if we have a Higgs +that decays into ZZ\*, with both Z's decaying into muons, the method +`get_list_of_daughters_from_decay`, applied to `i` = the index of the Higgs, +returns the indices of the two Z's in the Particle collection. In order to +retrieve the indices of the four muons, use instead +`MCParticle::get_list_of_stable_daughters_from_decay` +([link](https://github.com/HEP-FCC/FCCAnalyses/blob/9937fe77e5702b30d53b5e364b3fa6a4b134197c/analyzers/dataframe/src/MCParticle.cc#L447)). + +These functions are not meant to be called directly from the python +configuration file, but from some other function that will determine the value +of the argument `i`. See an example +[here](https://github.com/HEP-FCC/FCCeePhysicsPerformance/blob/069b633ab06126546daa0b0ba4719342096a9a4a/case-studies/flavour/VertexExamples/analysis_Bs2DsK.py#L63) +in FCCeePhysicsPerformance, the important lines being: + +```python +.Alias("Particle1", "Particle#1.index") +# MC indices of the decay Bs -> Ds+ K- +# In the file I process, only the Bs0 (not the Bsbar) has been forced to decay into Ds+ K- +# Look for (Ds+ K-) in the list of unstable decays of a Bs - hence oscillations are +# not accounted for. So there should be at most one such decay per event. In any case, +# would there be > 1, the method gives the first one encountered. +# Returns the indices of : mother Bs, Ds+, K- + +.Define("Bs2DsK_indices", "MCParticle::get_indices_ExclusiveDecay( -531, {431, -321}, false, false) ( Particle, Particle1)" ) +``` + +Again, the first line is needed for RootDataFrame to interpret correctly the +pound sign. + +To retrieve the **parents** of a Monte-Carlo particle: the logic is the same, +one should use `parents_begin` and `parents_end`, which point to the +`Particle#0` collection. + + +## Writing a new analyzer + +There are several ways how to define a new analyzer, which can have various +forms and complexity. The analyzer then can be used in the RDF Define and Filter +statements. Here we list several of them and their use cases, full RootDataFrame +documentation can be viewed +[here](https://root.cern/doc/master/classROOT_1_1RDataFrame.html). + + +### C++ string + +To define a simple analyzer one can use RDataFrame's feature of providing +functions directly as string of C++ code, something like: +```python +.Define("myvec", + "ROOT::VecOps::RVec v; for (int i : { 1, 2, 3, 4, 5, 6, 7 }) v.push_back(i); return v;") +.Define("myvecsize", "myvec.size()") +``` + +### Using ROOT gInterpreter + +It is also possible to define more complex analyzer and feed it to the ROOT +gInterpreter + +```python +ROOT.gInterpreter.Declare(""" +template +ROOT::VecOps::RVec myRange(ROOT::VecOps::RVec& vec, std::size_t begin, std::size_t end) { + ROOT::VecOps::RVec ret; + ret.reserve(end - begin); + for (auto i = begin; i < end; ++i) + ret.push_back(vec[i]); + return ret; +} +""") +``` + +and then call it in the `Define` +```python +.Define("mysubvec", "myRange(myvec, 2, 4)") +``` + +### Inside an existing FCCAnalyses module + +When you believe you need to develop a new function within an existing +FCCAnalyses namespace, you should proceed as follow: +In the corresponding header file in `analyzers/dataframe/FCCAnalyses` you should +add the definition of your function, for example: + +```cpp +/// Get the invariant mass from a list of reconstructed particles +float getMass(const ROOT::VecOps::RVec & in); +``` + +In the corresponding source file in `analyzers/dataframe/src` you should add the +implementation of your function, for example: + +```cpp +float getMass(const ROOT::VecOps::RVec& in) { + ROOT::Math::LorentzVector> result; + + for (auto & p: in) { + ROOT::Math::LorentzVector> tmp; + tmp.SetPxPyPzE(p.momentum.x, p.momentum.y, p.momentum.z, p.energy); + result+=tmp; + } + + return result.M(); +} +``` + +Note that for efficiency, the arguments should be passed as `const` reference. + +If your code is simple enough, it can also add the function only to the header +file and even templated, for example: + +```cpp +template +inline ROOT::VecOps::RVec> as_vector(const ROOT::VecOps::RVec& in) { + return ROOT::VecOps::RVec>(1, in); +}; +``` + + +## Writing a new struct + +When you believe you need to develop a new struct within an existing namespace, +you should proceed as follow: +In the header file in `analyzers/dataframe/FCCAnalyses` you should add a +`struct` or a `class` like: + +```cpp +/// Get the number of particles in a given hemisphere (defined by it's angle wrt to axis). Returns 3 values: total, charged, neutral multiplicity +struct getAxisN { +public: + getAxisN(bool arg_pos=0); + ROOT::VecOps::RVec operator() (const ROOT::VecOps::RVec & angle, + const ROOT::VecOps::RVec & charge); +private: + bool _pos; /// Which hemisphere to select, false/0=cosTheta<0 true/1=cosTheta>0. Default=0 +}; +``` +where the `public` members should contain the name of the function with the +constructor arguments (in this example `getAxisN`) and the `operator()` that +correspond to the function that will be evaluated for each event and return the +output. The private section should contains members that will be needed at run +time, usually the arguments of the constructor. + + +In the corresponding source file in `analyzers/dataframe/src` you should add the +implementation of your class, for example: +```cpp +getAxisN::getAxisN(bool arg_pos) { + _pos=arg_pos; +} + +ROOT::VecOps::RVec getAxisN::operator() (const ROOT::VecOps::RVec & angle, + const ROOT::VecOps::RVec & charge) { + ROOT::VecOps::RVec result = {0, 0, 0}; + + for (size_t i = 0; i < angle.size(); ++i) { + if (_pos==1 && angle[i]>0.){ + result[0]+=1; + if (std::abs(charge[i])>0) result[1]+=1; + else result[2]+=1; + } + if (_pos==0 && angle[i]<0.){ + result[0]+=1; + if (std::abs(charge[i])>0) result[1]+=1; + else result[2]+=1; + } + } + + return result; +} +``` +where you separate the class construction and its implementation. + + +## Writing a new module + +If you think new module/namespace is needed, create a new header file in +`analyzers/dataframe/FCCAnalyses`, for example `MyModule`. It should look like: + +```cpp +#ifndef MYMODULE_ANALYZERS_H +#define MYMODULE_ANALYZERS_H + +// Add here your defines + +namespace FCCAnalyses { + namespace MyModule { + +// Add here your analyzers + } +} +#endif +``` + +create a new source file in `analyzers/dataframe/src`, for example `myModule.cc`. +It should look like: + +```cpp +#include "FCCAnalyses/myNamespace.h" +// Add here your defines + +namespace FCCAnalyses { + namespace MyModule { + // Add here your functions, structs + + } +} +``` + + +## Writing your own analysis using the case-studies generator + + +:::{admonition} Experimental feature +:class: danger + +The following feature is experimental and might not work as expected. Please, +contact developers. +::: + +For various physics case studies, standard RDF tools might not be sufficient and require a backing library of helper objects and static functions exposed to ROOT. + +An analysis package creation tool is developed to provide the minimal building blocks for such extensions and uniformise such developments. + + +### Analysis package generation + +Two modes are currently supported for the linking of these extensions to the analysis framework: + +- scan at CMake+compilation time a _standard_ extensions directory (in `case-studies`) where the analysis package can be deployed. It requires an `includes` and `src` subdirectory, along with a `classes_def.xml` and `classes.h` files in the latter for the ROOT dictionary definition. +- generate a _standalone_ package which can be compiled independently, given the path to this `FCCAnalyses` installation is found. It allows to generate a minimal set of files required to connect this extension to the RDF utilitaries. + +The generation of such a package can be done using the following recipe: + +```bash +fccanalysis init [-h] [--name NAME] [--author AUTHOR] [--description DESCRIPTION] [--standalone] [--output-dir OUTPUT_DIR] package +``` +where the mandatory parameter, `package`, refers to the analysis package name (along with the namespace it will define ; should be unique at runtime). +Additionally, several optional parameters are handled: +- `NAME` specifies the analyser helpers filename (where all static functions exposed to the RDF framework through the ROOT dictionary will be stored) ; +- `AUTHOR`, preferably following the "`name `" convention, and `DESCRIPTION`, will be added into the C++ files boilerplates to keep track of the author(s) and purpose(s) of this package ; +- `--standalone` to switch to the standalone package described above. In combination with the `OUTPUT_DIR` parameter, it allows to store the minimal working example in a completely arbitrary path (instead of the standard `case-studies` subdirectory) with its own CMake directive. + +In the _standalone_ mode, the analysis package can be built using the standard CMake recipe, given the FCCAnalyses environment in `setup.sh` is properly sourced: + +```bash +mkdir build && cd build +cmake ${OUTPUT_DIR} && make +make install +``` +The latter ensures that the headers and shared library/ROOT translation dictionaries are installed in a location reachable by FCCAnalyses. + +### Analysis package exposure to RDF + +To allow an arbitrary multiplicity of analysis packages to be handled at the level of a configuration script runnable with "`fccanalysis run`", an additional (optional) `analysesList` list-type object can be parsed. + +On top of the usual `FCCAnalyses` shared object, includes, and corresponding dictionary, the custom case study analysis package name will be parsed, and automatically loaded in the ROOT runtime environment to be exposed to the RDF interface. diff --git a/bnl2023/_sources/fast-sim-and-analysis/FccFastSimGeneration.md.txt b/bnl2023/_sources/fast-sim-and-analysis/FccFastSimGeneration.md.txt new file mode 100644 index 00000000..47b2f9ba --- /dev/null +++ b/bnl2023/_sources/fast-sim-and-analysis/FccFastSimGeneration.md.txt @@ -0,0 +1,979 @@ +FCC: Getting started with event generation +=================================================================================== + + +## Overview + + +## Enabling FCCSW + +The FCC software `FCCSW` is fully embedded in the `key4hep` software stack or ecosystem, which means that the components providing the framework and those FCC specific are all available in `key4hep`. To configure your environment for the FCC software is therefore sufficient to initialise `key4hep`: + +``` +source /cvmfs/sw.hsf.org/key4hep/setup.sh +``` +:::{admonition} Nota Bene +:class: callout + +For legacy reasons the following is still provided, fully equivalent to the above +``` +source /cvmfs/fcc.cern.ch/sw/latest/setup.sh +``` +Note however that not all the `cvmfs` tier-1 centers replicate the `fcc.cern.ch`, so this may lead to slowdowns or even failures. +::: + +Builds exist on CernVM-FS for `CentOS7` (this is the Operating System run on `lxplus`) using as compiler `Gcc 11` (currently gcc version `11.2.0`). + +:::{admonition} Nota Bene +:class: callout + +The combination of old `glibc` version available on `CentOS7` with the backward compatibility attributes of glibc makes the provided stack in principle working for newer OSes, such as `CentOS8`, `AlmaLinux9` or `Fedora37`. This in general holds, though less core aspects, such graphics, might still be OS specific. +::: + +The `gaudimain` steering application here is called `k4run` which should be available at this point: + +```bash +$ which k4run +/cvmfs/sw.hsf.org/spackages7/k4fwcore/1.0pre16/x86_64-centos7-gcc11.2.0-opt/tp4u6/bin/k4run +``` +(The output might differ, but shouldn't be empty and the structure should be similar). + +The application `fccrun` is still provided, fully equivalent to `k4run`. + +:::{admonition} Nota Bene +:class: callout + +You will need to source the `/cvmfs/sw.hsf.org/key4hep/setup.sh` script everytime you want to use the software. +::: + + +## Generators + +### Overview + +The physics generators available for FCC usually come from `key4hep`. However, any generator +able to generate events in one of the understood formats, e.g. HepMC or EDM4hep or LHEf, can be used in standalone. +Following the discussion at the [1st ECFA workshop on Generators](https://indico.cern.ch/event/1078675/), the recommended formats are `HepMC3` and `EDM4hep`; `LHEf` is still much in use though. +This pages intend to illustrate the use of a few general purpose generators available when enabling FCCSW: +pythia8, whizard, MadGraph5, Herwig, KKMCee, BHLUMI, BabaYaga. + +### Pythia8 + +Pythia8 is fully intergrated in `Key4hep` software stack and it provides diverse functionality in addition to event generation, including capability to read events in `LHEf` format. + +To use Pythia8 we need a Gaudi steering file and a Pythia8 configuration file, usually having extension `.cmd`. Examples of these `.cmd` files are available from the [FCC-config](https://github.com/HEP-FCC/FCC-config/tree/main/FCCee/Generator/Pythia8) repository. + +The Gaudi steering file needs to activate the `GaudiTool` that interfaces `Pythia8`, available from the `k4Gen` repository under the name [PythiaInterface](https://github.com/HEP-FCC/k4Gen/blob/main/k4Gen/src/components/PythiaInterface.h). + +An example of steering file can be found at [pythia.py](https://raw.githubusercontent.com/HEP-FCC/k4Gen/main/k4Gen/options/pythia.py). The steering file runs the minimal set of algorithms to run Pythia8 and produce an output in `EDM4hep` format: +``` +$ wget https://raw.githubusercontent.com/HEP-FCC/k4Gen/main/k4Gen/options/pythia.py +$ k4run pythia.py -h | head -n 1 + --> Pythia8 --> HepMCToEDMConverter --> StableParticles --> out +``` +For example, to generate 500 e+e- → mu+mu- at 91.2 GeV, we can do the following: download the configuration file: +``` +$ wget https://raw.githubusercontent.com/HEP-FCC/FCC-config/main/FCCee/Generator/Pythia8/p8_ee_Zmumu_ecm91.cmd +``` +and run +``` +k4run pythia.py -n 500 --out.filename p8_mumu_500.e4h.root --Pythia8.PythiaInterface.pythiacard p8_ee_Zmumu_ecm91.cmd +``` + +### Whizard + +Whizard is available as standalone program: + +```bash +$ which whizard +/cvmfs/sw.hsf.org/spackages6/whizard/3.0.3/x86_64-centos7-gcc11.2.0-opt/yy7yk/bin/whizard +``` + +Whizard is run as this: + +``` +whizard .sin +``` + +Example of Sindarin configuration files are found under + +``` bash +ls /cvmfs/sw.hsf.org/spackages6/whizard/3.0.3/x86_64-centos7-gcc11.2.0-opt/yy7yk/share/whizard/examples/ +``` +or at [https://gitlab.tp.nt.uni-siegen.de/whizard/public/-/tree/master/share/examples](https://gitlab.tp.nt.uni-siegen.de/whizard/public/-/tree/master/share/examples). + +Some examples more specific to FCC can be found at [https://fccsw.web.cern.ch/fccsw/share/gen/whizard/Zpole/](https://fccsw.web.cern.ch/fccsw/share/gen/whizard/Zpole/)`. + + +:::{admonition} Show dimuon example +:class: toggle + +It is advised to work in a separate directory for each process. For example, for Z_mumu, we have: + +```bash + mkdir -p test_whizard/Z_mumu; cd test_whizard/Z_mumu + wget https://fccsw.web.cern.ch/fccsw/share/gen/whizard/Zpole/Z_mumu.sin + whizard Z_mumu.sin +``` + +``` +| Writing log to 'whizard.log' +|=============================================================================| +| | +| WW WW WW WW WW WWWWWW WW WWWWW WWWW | +| WW WW WW WW WW WW WW WWWW WW WW WW WW | +| WW WW WW WW WWWWWWW WW WW WW WW WWWWW WW WW | +| WWWW WWWW WW WW WW WW WWWWWWWW WW WW WW WW | +| WW WW WW WW WW WWWWWW WW WW WW WW WWWW | +| | +| | + +... + +|=============================================================================| +| WHIZARD 3.0.1 +|=============================================================================| +| Reading model file '/cvmfs/sw.hsf.org/spackages6/whizard/3.0.1/x86_64-centos7-gcc11.2.0-opt/pmm4s/share/whizard/models/SM.mdl' +| Preloaded model: SM +| Process library 'default_lib': initialized +| Preloaded library: default_lib +| Reading model file '/cvmfs/sw.hsf.org/spackages6/whizard/3.0.1/x86_64-centos7-gcc11.2.0-opt/pmm4s/share/whizard/models/SM_hadrons.mdl' +| Reading commands from file 'Z_mumu.sin' +| Switching to model 'SM', scheme 'default' + +... + +$description = "A WHIZARD 3.0 Example. + Z -> mumu @ 91.2 events for FCC ee." +$y_label = "$N_{\textrm{events}}$" +$sample = "z_mumu" +| Starting simulation for process 'zmumu' +| Simulate: using integration grids from file 'zmumu.m1.vg' +| RNG: Initializing TAO random-number generator +| RNG: Setting seed for random-number generator to 22345 +| Simulation: requested number of events = 1000 +| corr. to luminosity [fb-1] = 6.6285E-04 +| Events: writing to HepMC file 'z_mumu.hepmc' +| Events: writing to raw file 'z_mumu.evx' +| Events: generating 1000 unweighted, unpolarized events ... +| Events: event normalization mode '1' +| ... event sample complete. +| Events: actual unweighting efficiency = 1.16 % +Warning: Encountered events with excess weight: 6 events ( 0.600 %) +| Maximum excess weight = 2.465E+00 +| Average excess weight = 4.511E-03 +| Events: closing HepMC file 'z_mumu.hepmc' +| Events: closing raw file 'z_mumu.evx' +| There were no errors and 2 warning(s). +| WHIZARD run finished. +|=============================================================================| +``` + +::: + +The file `z_mumu.hepmc` contains 100 e+e- → mu+mu-(gamma) events in HepMC 3 format . + +### KKMCee + +`KKMCee` is an adaptation of the `KKMC` Monte Carlo generator (the latest version of the `Koral` generators) to the +case of FCC-ee. +KKMCee is available as standalone program when using the key4hep stack: + +```bash +which KKMCee +``` + +``` +/cvmfs/sw.hsf.org/spackages6/kkmcee/5.00.02/x86_64-centos7-gcc11.2.0-opt/eodg6/bin/KKMCee +``` + +A help function is available: + +``` +KKMCee -h +``` + +:::{admonition} Show help function output +:class: toggle + +``` ++++ Wrapper around the KKMCee executable +++ + +Usage: \tKKMCee -f Mu|Tau|UDS|C|B|Hadrons -e Ecms -n Nevts -o output_file [-s initial_seed] [OPTIONS] + \tKKMCee -c config_file [-s initial_seed] + +Options: + -c, --config file Path to configuration file + -f, --flavour flavour Flavour to be generated (Mu|Tau|UDS|C|B|Hadrons) + -e, --ecms energy Center of Mass energy in GeV + -n, --nevts events Number of events to be generated + -o, --outfile file File with the generated events in HEPMCv3 format [kkmcee.hepmc] + -s, --initialseed Long number to be used for initial seeding (randomly generated, if missing) + -b, --bessig bessig Beam-Energy-Spread of both beams (or of the first beam, if bessig2<0.) + [fraction of Ecms/2, default -1. (no spread)] + -g, --bessig2 bessig2 Beam-Energy-Spread of the second beam if different from the first beam; fraction of Ecms/2. + [fraction of Ecms/2, default -1. (no spread or equal to first beam)] + -r, --besrho rho Beam-Energy-Spread correlation [default 0.] + -d, --debug lvl PrintOut Level 0,1,2 [default 1] + +Special options for taus only: + -t, --taudec t1*1000+t2 decay channel for the first (t1) and second tau (t2) + 0 Inclusive + 1,2,3 electron,mu,pi + 4,5,6,7 rho,a1,K,K* + 8,9,10,11,12,13 3pip0,pi3pi0,3pi2pi0,5pi,5pip0,3pi3p0 + 14, ... (other rare decays see tauola++) + --tauopt file File with tau options (see Tauola section in KKMCee_defaults) + the file is included as it is and overwrites other settings + +Examples: +KKMCee -f Mu -e 91.2 -n 10000 -o kkmu_10000.hepmc -b 0.001 +KKMCee -c kkmc_ditau.input +KKMCee -f B -e 91.2 -n 1000 -o kkbb_1000.hepmc + + NB: (1) This wrapper works only for KKMCee versions 5 or newer + (2) Output is HEPMC v3 +``` + +::: + +Note that the BES (Beam Energy Spread) options are only available in version 4.32.01 and higher. + +A configuration example file for taus is available under at + +``` +ls `dirname $( which KKMCee )`/../share/KKMCee/examples/kkmc-tauola.input +``` + +:::{admonition} Show dimuon example +:class: toggle + +To generate a sample of dimuon events using the example files, do the following + +```bash +KKMCee -f Mu -e 91.2 -n 1000 -o kkmu_1000.hepmc +``` + +The output should look something like this: + +``` +Seeds: 29318493 48191772 + 29318493 IJKLIN= 29318493 48191772 + 0 NTOTIN= 0 + 0 NTOT2N= 0 + ------- starting from the scratch ---------- +ranmar initialized: ij,kl,ijkl,ntot,ntot2= 974 18625 29318493 0 0 + 1000 requested events + --------------- + **************************** + * KK2f_ReaDataX Starts * + **************************** + --------------- + --------------- + --------------- + --------------- + --------------- +BeginX +******************************************************************************** +* ACTUAL DATA FOR THIS PARTICULAR RUN +******************************************************************************** +*indx_____data______ccccccccc0ccccccccc0ccccccccc0ccccccccc0ccccccccc0ccccccccc0 +* Center-of-mass energy [GeV] + 1 91.0000 CMSene =xpar( 1) Average Center of mass energy [GeV] +******************************************************************************** +* Define process + 413 1.00000 KFfin, muon + 100 1.00000 store lhe file to (LHE_OUT.LHE) + --------------- 26 36 LHE_OUT.LHE +************************* one can change the lhf file name between brackets +******************************************************************************** +EndX + ************************** + * KK2f_ReaDataX Ends * + ************************** + Tables are READ from DiskFile dizet/table.down +amz,amh,amtop,swsq,gammz,amw,gammw= + = 91.1876000 125.1000000 173.0000000 0.2234020 2.4953766 80.3588894 2.0898788 + + ... + + + + Event listing (summary) + + I particle/jet KS KF orig p_x p_y p_z E m + + 1 !e-! 21 11 0 0.000 0.000 45.500 45.500 0.001 + 2 !e+! 21 -11 0 0.000 0.000 -45.500 45.500 0.001 + 3 (Z0) 11 23 1 0.039 0.001 0.115 90.879 90.879 + 4 gamma 1 22 1 0.000 0.000 -0.001 0.001 0.000 + 5 gamma 1 22 1 -0.039 -0.001 -0.114 0.120 0.000 + 6 mu- 1 13 3 14.678 0.229 43.067 45.500 0.106 + 7 mu+ 1 -13 3 -14.639 -0.229 -42.952 45.379 0.106 + sum: 0.00 0.000 0.000 0.000 91.000 91.000 + iev= 501 + generation finished + xSecPb, xErrPb = 1442.5021729176829 13.903134156944603 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ GLK_PRINT: bmin.eq.bmax, id= 50004 ++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++ +++ GLK_PRINT: bmin.eq.bmax, id= 50005 ++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +real 0m4.043s +user 0m3.777s +sys 0m0.085s +``` + +::: + +and a file `kkmu_1000.hepmc` created. + +`KKMCee` creates several files during its run. These are saved into a folder called `KKMCee--