doc/tutorials/2-geometry-code.md

0001 Tutorial 2: dRICH Visualization, Continuous Integration, and Geometry Code
0002 ==========================================================================
0003
0004 - [TUTORIAL RECORDING (mirror 1)](https://drive.google.com/file/d/1hVkBZuM_F_47VEo4VLlgFqlSEOE4Kef0/view?usp=sharing)
0005   -- [CHAT](https://drive.google.com/file/d/1Ay4FJ9kRIjyR0LKJ4cB4ZjT_0mrrlUMv/view?usp=sharing)
0006 - [TUTORIAL RECORDING (mirror 2)](https://duke.zoom.us/rec/play/xAzADPjS_bA5_LckU3kaz0BeDsqGjYen9gNpMZmndzfBAooVWlqEWwAfcSH5DzSlVrshzgrsacYhXOxJ._MoPSIDg0lOCl8Oj?canPlayFromShare=true&from=share_recording_detail&continueMode=true&componentName=rec-play&originRequestUrl=https%3A%2F%2Fduke.zoom.us%2Frec%2Fshare%2FYpwfjg8auzo6TYinWF_HVfeCK_Nbr3FmCwGc7p6xInEXr9GtZVR80scgS5_cZHn6.UxyKJKSFjAhADicc)
0007 - [Return to Tutorial Landing Page](README.md)
0008
0009 ## Visualization
0010
0011 ### Event Visualization
0012
0013 To visualize the charged particle and photon paths, [try following the event visualization tutorial](https://indico.bnl.gov/event/18360/). Unfortunately, this procedure does not work for all graphics cards and we have been unable to test this for the dRICH.
0014
0015 As an alternative, the non-interactive visual from Geant4 may work on a broader range of hardware. To use this, first rebuild the dRICH geometry with one sector only (to make it easier to visualize). Change the geometry constant `DRICH_debug_sector` from `0` to `1`, as [defined in `epic/compact/pid/drich.xml`](https://github.com/eic/epic/blob/d14e80b98cc51fb7acf014f6984caf8fe347aed1/compact/pid/drich.xml#L46). Open the compact file:
0016 ```bash
0017 nano epic/compact/pid/drich.xml  # or your preferred text editor; you may need to do this outside of 'eic-shell'
0018 ```
0019 Change the line
0020 ```xml
0021 <constant name="DRICH_debug_sector"    value="0"/>
0022 ```
0023 to
0024 ```xml
0025 <constant name="DRICH_debug_sector"    value="1"/>
0026 ```
0027 Save and quit; if using `nano`, press `^X`, then `y`, then `enter`. Now rebuild `epic`:
0028 ```bash
0029 build.sh epic
0030 ```
0031 You can confirm only one sector is drawn by running `geometry.sh` as before.
0032
0033 Now run `simulate.py` in visual mode (`-v`). Let's throw only one pion at the dRICH using test 1:
0034 ```bash
0035 simulate.py -t1 -n1 -v
0036 ```
0037 A static image will appear, showing the thrown pion and corresponding Cherenkov photons. This is a top view of a single sector; edit `simulate.py` to change the view angle. Your shell will be in a Geant4 prompt; type `exit` and press Enter to exit.
0038
0039 ![sim-vis](img/sim-vis.png)
0040
0041 When you are done, revert the changes in `epic/compact/pid/drich.xml` so that `DRICH_debug_sector` is set to `0`, then rebuild `epic`.
0042
0043 ### Optics Studies
0044
0045 Some tests in `simulate.py` are used for optical studies. In particular, test 102 sends wide, collimated photon beams from the IP at varying angles aimed at the mirror. The focus of each beam is the parallel-to-point focal region, and tends to be consistent with where the best Cherenkov ring resolution is found. As suggested by the `simulate.py` usage guide, set `DRICH_debug_optics` to `1`. In `epic/compact/pid/drich.xml`, change the line
0046 ```xml
0047 <constant name="DRICH_debug_optics"    value="0"/>
0048 ```
0049 to
0050 ```xml
0051 <constant name="DRICH_debug_optics"    value="1"/>
0052 ```
0053 and rebuild `epic`:
0054 ```bash
0055 build.sh epic
0056 ```
0057 Now run test 102:
0058 ```bash
0059 simulate.py -t102
0060 ```
0061 Use the `-n` option to change the number of photons per beam, and the `-k` option to change the number of beams. For example,
0062 ```bash
0063 simulate.py -t102 -k3 -n30
0064 ```
0065
0066 ![sim-optics](img/sim-optics.png)
0067
0068 As before, type `exit` and press Enter to exit the Geant4 prompt.
0069 When you are done, revert the changes in `epic/compact/pid/drich.xml` so that `DRICH_debug_optics` is set to `0`, then rebuild `epic`.
0070
0071 _Exercise_: edit `epic/compact/pid/drich.xml` to try to move around some components of the dRICH. Rebuild `epic` and check the geometry to see what moved. Then re-check the distribution of hits in the event display as well as the parallel-to-point focal region. Can you improve the ring resolution?
0072
0073
0074 ### Necessary Digression: Continuous Integration
0075
0076 All ePIC software repositories include Continuous Integration (CI) workflows. These workflows are triggered automatically for every `git commit` on a branch associated with a Pull Request (PR). For example, [see this PR](https://github.com/eic/epic/pull/445).
0077 - The 'Checks' tab shows the latest CI workflow run on this PR's branch; the main 'Actions' tab at the top of the page lists all of the CI workflows that are running and have run, for all PRs
0078 - After clicking the 'Checks' tab on the PR, click on `linux-eic-shell` on the left; this is the primary workflow
0079   - _Exercise:_ can you also get here from the 'Actions' tab? Knowing how to do this will let you see any CI workflow, for example, the latest CI workflow that ran on the `main` branch, which happens when a PR gets merged. CI workflows on `main` give an indication of the "health" of a repository, since all work stems from `main`
0080 - At the top you will see a diagram of the workflow jobs, such as:
0081   - `build`: compiles the `epic` code
0082   - `convert-to-gdml`: converts all subsystems to `GDML` files
0083   - `check-overlap`: checks for overlaps in the geometry
0084   - `dawn-view`: generates `DAWN` views of the geometry
0085
0086 ![sim-ci-workflow](img/sim-ci-workflow.png)
0087
0088 - Below the workflow diagram, you will find a list of "Artifacts"; these are the products of a CI workflow, such as:
0089   - `gdml`: the resulting `GDML` files
0090   - `tgeo`: the geometry `TGeo` ROOT files (that we made with `geometry.sh` last week)
0091   - `constants:` a table of geometry constants
0092   - `epic_*views`: the `DAWN` views of the geometry
0093   - **NOTE**:
0094     - you must be logged into Github in order to download these artifacts, otherwise you will not see the hyperlinks
0095     - artifacts typically have a retention period (some number of days), after which they expire and are no longer accessible (but they can be reproduced on demand)
0096
0097 _Exercise_: `drich-dev` also has a CI workflow which runs simulation, reconstruction, and benchmarks, as a complement to the CI workflows in ePIC software repositories. Check it out, try opening a test PR in `drich-dev` to run it and check the resulting artifacts.
0098
0099 ### DAWN Views from CI
0100
0101 Since we are talking about visualization, let's look at the `DAWN` views.
0102 - Choose `epic_arches_views` or `epic_brycecanyon_views` and download the `zip` file
0103 - Open `view1.png` (or `.pdf`) for a 3D view
0104 - One of the most useful views is `view1_top.png` (or `.pdf`) which shows a top view of the central slice of ePIC
0105   - When making geometry changes, it is useful to compare this view produced from `main` to that produced from your PR, so that you may check the impact of your changes on other detectors (which may happen when changing the dRICH vessel geometry or positioning)
0106
0107 ![sim-dawn-view1](img/sim-dawn-view1.png)
0108
0109 ![sim-dawn-view1-top](img/sim-dawn-view1_top.png)
0110
0111
0112 ---
0113
0114 ## Geometry Code
0115
0116 Now let's explore the geometry code. The recording of this tutorial goes through the code interactively; here we just provide a reference of the code that was shown.
0117
0118 ### Common Files
0119 - `compact/`: these are "compact `xml` files"
0120   - `definitions.xml`: common constants shared by all of ePIC, such positioning and length of the trackers, calorimeters, and PID subsystems; if you want to change the dRICH envelope and positioning, this is where to start
0121   - `display.xml` and `colors.xml`: visualization settings
0122   - Material and Surface properties:
0123     - `materials.xml`: material definitions
0124     - `optical_materials.xml`: optical material and surface property tables
0125       - anything used by the dRICH includes the string `DRICH` in the name (except for common materials such as `Aluminum`)
0126       - see [material property documentation](../material_tables.md) for notes on how these tables were generated for the dRICH
0127 - Configurations
0128   - Various combinations of detector subsystems are defined by configuration files in `configurations/`
0129     - `full.yml`: the full ePIC configuration
0130     - `arches.yml` and `brycecanyon.yml`: configurations for Arches and Brycecanyon design options
0131     - `drich_only.yml`: standalone dRICH (includes magnetic field)
0132   - Each of these are rendered as compact files during `cmake` (during `build.sh epic` from `drich-dev`)
0133     - you can find them in `$DETECTOR_PATH/`; these are the compact files that are used by simulation
0134     - rendering is done by templates in the `templates/` directory together with these configuration files
0135
0136 ### Subsystem Specific Files
0137 - Geometry compact files: `compact/`
0138   - each subsystem has at least one geometry compact file; the PID subsystems are found in `compact/pid/`
0139   - dRICH: `compact/pid/drich.xml`, contains all of our geometry constants and more
0140 - C++ Plugin files: `src/`
0141   - each subsystem also includes at least one C++ plugin file
0142     - the compact file can be though of as the "numbers" for the geometry, tunable externally (by hand or with `xml` parsers) without the need to recompile
0143     - the plugin file is the actual geometry implementation: it uses the compact files and generates the DD4hep geometry
0144   - `src/DRICH_geo.cpp` is the plugin for the dRICH
0145     - creates all aspects of the geometry
0146     - includes algorithms, such as:
0147       - spherical tiling of sensors on a sphere
0148       - mirror focusing