Warning, /drich-dev/README.md is written in an unsupported language. File is not indexed.
0001 # dRICH-dev
0002 Resources and Tools for EPIC dRICH development
0003
0004 | **Table of Contents** | |
0005 | --: | --- |
0006 | [Setup](#setup) | How to download and build the code |
0007 | [ePIC Software Stack](#flowchart) | Flowchart of ePIC Software and Dependency |
0008 | [Geometry and Materials](#geometry) | Detector geometry and material properties description |
0009 | [Simulation](#simulation) | Running the simulation in Geant4 |
0010 | [Reconstruction](#reconstruction) | Running the reconstruction algorithms |
0011 | [Benchmarks](#benchmarks) | Running the analysis benchmarks and performance plots |
0012 | [Miscellaneous](#miscellaneous) | Additional code for support |
0013
0014 | **Documentation Links** | |
0015 | --: | --- |
0016 | [Tutorial Series](doc/tutorials/README.md) | Series of dRICH-specific Tutorials |
0017 | [Links](doc/links.md) | Collection of dRICH Software and Resources |
0018 | [Branches and Pull Requests](doc/branches.md) | Active development branches and pull requests |
0019 | [Project Board](https://github.com/orgs/eic/projects/4) | Issues and Pull Request Tracking |
0020 | [Material Properties](doc/material_tables.md) | Generation of Material Property Tables |
0021
0022 ## Notes
0023 EPIC Software is modular: see [the flowchart below](#flowchart) for
0024 general guidance of the modules relevant for RICH development. It shows their
0025 dependences, calls, and data flow.
0026
0027 See also [the collection of links](doc/links.md) to various resources and dRICH
0028 implementations.
0029
0030 ## Active Branches
0031
0032 Depending on the development, you likely need to change `git` branches for some
0033 of the modules. See the [active branches tables](doc/branches.md) for tables
0034 of branches for varying configurations.
0035
0036 ## Notes for ATHENA
0037 - This repository was used for development of the ATHENA dRICH and pfRICH; it
0038 has since been modified to support EPIC
0039 - See [doc/athena.md](doc/athena.md) for guidance how to run using the ATHENA geometry;
0040 this is temporarily supported for helping test reconstruction algorithms
0041 - See [doc/athena-branches.md](doc/athena-branches.md) for information about the
0042 development branches and pull requests that were used for the ATHENA proposal
0043
0044 ---
0045
0046 <a name="setup"></a>
0047 # Setup
0048 - First, clone this `drich-dev` repository
0049 - If you follow the directions below as is, everything will be installed in
0050 subdirectories of this repository; you will need a few GB of disk space
0051 - If you have experience with the ATHENA software stack, you may prefer your
0052 own set up; in that case, make symlinks to your local `git` repository
0053 clones, so you can use the scripts in this directory
0054 - Obtain the EIC Software image (`jug_xl`):
0055 - follow [ePIC Software Tutorials](https://indico.bnl.gov/category/443/)
0056 to obtain the EIC software image
0057 - the `eic-shell` script is used to start a container shell
0058 - all documentation below assumes you are running in `eic-shell`
0059 - this image contains all the dependencies needed for EPIC simulations
0060 - tip: when in a container shell (`eic-shell`), see `/usr/local` or `/opt/software/linux.../gcc.../`
0061 for the installed software
0062 - for example, if you want to check exactly what is available in the
0063 [EDM4hep data model](https://github.com/key4hep/EDM4hep), see the headers
0064 in `/opt/software/linux.../gcc.../edm4hep.../include/edm4hep/` (these are
0065 produced by the [edm4hep.yaml](https://github.com/key4hep/EDM4hep/blob/master/edm4hep.yaml)
0066 configuration file)
0067 - be sure to regularly update your image by running `eic-shell --upgrade`; this is necessary
0068 to keep up with upstream changes, such as in EDM4hep or DD4hep
0069 - Obtain EPIC Software modules, either clone or symlink the repositories to the
0070 specified paths:
0071 - Modules:
0072 - [`epic`](https://github.com/eic/epic) to `./epic`, for the EPIC detector geometry,
0073 based on [DD4hep](https://github.com/AIDASoft/DD4hep)
0074 - [`irt`](https://github.com/eic/irt) to `./irt`, for the Indirect Ray Tracing for RICH reconstruction
0075 - [`EDM4eic`](https://github.com/eic/EDM4eic) to `./EDM4eic`, for the data model; this extends
0076 [`EDM4hep`](https://github.com/key4hep/EDM4hep), the common data model, which is included
0077 in the EIC software image
0078 - [`EICRecon`](https://github.com/eic/EICrecon) to `./EICrecon`, for the reconstruction framework
0079 - [`reconstruction_benchmarks`](https://eicweb.phy.anl.gov/EIC/benchmarks/reconstruction_benchmarks) to
0080 `./reconstruction_benchmarks`, for the reconstruction benchmarks and performance studies
0081 - Cloning:
0082 - Only clone the repositories that you need or intend to modify; they are all installed in the `eic-shell`
0083 image, but if you want to build the latest possible version of a repository, clone it; `drich-dev` is
0084 designed to _override_ `eic-shell` image builds
0085 - Clone the Github repositories with SSH, which is required for
0086 contributions (you must be a member of the EIC organization and ePIC Devs
0087 team), otherwise you need to clone with HTTPS (or fork and clone the fork
0088 with SSH)
0089 - SSH clone:
0090 ```bash
0091 git clone git@github.com:eic/epic.git
0092 git clone git@github.com:eic/irt.git
0093 git clone git@github.com:eic/EDM4eic.git
0094 git clone git@github.com:eic/EICrecon.git
0095 ```
0096 - HTTPS clone:
0097 ```bash
0098 git clone https://github.com/eic/epic.git
0099 git clone https://github.com/eic/irt.git
0100 git clone https://github.com/eic/EDM4eic.git
0101 git clone https://github.com/eic/EICrecon.git
0102 ```
0103 - Some repositories are still hosted on [EICweb](https://eicweb.phy.anl.gov/EIC); if you want to contribute
0104 to them, you will also need an account there. Again, if you have access, clone with SSH, otherwise clone
0105 with HTTPS:
0106 - SSH clone:
0107 ```bash
0108 git clone git@eicweb.phy.anl.gov:EIC/benchmarks/reconstruction_benchmarks.git
0109 ```
0110 - HTTPS clone:
0111 ```bash
0112 git clone https://eicweb.phy.anl.gov/EIC/benchmarks/reconstruction_benchmarks.git
0113 ```
0114 - Checkout the appropriate branches of each repository, depending on your needs
0115 - see [Branches and Pull Requests](doc/branches.md)
0116 - see also the [project page](https://github.com/orgs/eic/projects/4/views/1)
0117 for more up-to-date information
0118 - Follow directions below to build each module
0119
0120 ## Environment
0121 - execute `source environ.sh`
0122 - this file contains several environment variables needed by many scripts;
0123 it is recommended to read through `environ.sh` and make any changes as
0124 needed
0125 - `$BUILD_NPROC` is the number of parallel threads used for multi-threaded
0126 building and running multi-threaded
0127 - change it, if you prefer
0128 - memory-hungry builds will be built single-threaded
0129 - `$EIC_SHELL_PREFIX` is the main directory where module builds will be installed
0130 - `environ.sh` will change this to `./prefix`, so that all module builds
0131 will be installed locally
0132 - change it, if you prefer a different directory
0133 - you can find documentation for many other variables in the corresponding
0134 module repositories
0135 - there are some additional "comfort" settings, which depend on your host
0136 environment; it is not required to use these, but feel free to add your own
0137 - if `~/bin` exists, it will be added to your `$PATH`
0138
0139 ## Building Modules
0140 - you must be in the EIC container (`eic-shell`) and have environment
0141 variables set (`source environ.sh`)
0142 - build each repository, one-by-one, in order of dependences
0143 - build scripts, in recommended order:
0144 ```bash
0145 ./build.sh EDM4eic
0146 ./build.sh irt
0147 ./build.sh epic
0148 ./build.sh EICrecon
0149 ./build.sh reconstruction_benchmarks
0150 ```
0151 - you could also run `./rebuild_all.sh` to (re)build all of the modules in the
0152 recommended order
0153 - run `source environ.sh` again, if:
0154 - if this is your first time building, or a clean build
0155 - if a module's environment has been updated, in particular `epic/templates/setup.sh.in`
0156 - finally, build the local `drich-dev` code:
0157 ```bash
0158 make # build and install the code
0159 make clean # remove built targets (only if you want to recompile from scratch)
0160 ```
0161 - this will produce several executables in `bin/` from code in `src/`
0162
0163 ### Recommendations and Troubleshooting
0164 - be mindful of the environment variables
0165 - if in doubt, run `source environ.sh` to update all of them
0166 - inspect all of the printed environment variables
0167 - execute `./rebuild_all.sh` to quickly rebuild all repositories, in order of
0168 dependences; this is useful when you switch branches in *any* of the
0169 repositories, or if you pull in updates
0170 - sometimes things will break, simply because a dependent module is out of
0171 date; in that case, make sure all repositories are as up-to-date as
0172 possible; you may also need to update your Singularity/Docker image
0173 (`eic-shell --upgrade`)
0174 - be mindful of which branch you are on in each repository, especially if you
0175 have several active pull requests
0176 - for example, `irt` requires the new `EDM4eic` components and datatypes, which
0177 at the time of writing this have not been merged to `EDM4eic` `main`
0178 - use `./check_branches.sh` to quickly check which branches you are on in all
0179 repositories
0180 - use `./check_status.sh` to run `git status` in each repository, which is
0181 useful during active development
0182 - for clean builds, you can generally pass the word `clean` to any build script
0183 (you can also do `./rebuild_all.sh clean` to clean-build everything)
0184 - most build scripts will run `cmake --build` multi-threaded
0185 - the `$BUILD_NPROC` environment variable should be set to the number of
0186 parellel threads you want to build with (see `environ.sh`)
0187
0188 ---
0189
0190 <a name="flowchart"></a>
0191 # ePIC Software Stack
0192 This is a flowchart showing the ePIC Software Stack, dependencies, and data flow, with some focus
0193 on parts specific for the dRICH. This `drich-dev` repository uses all of these, and in many cases,
0194 wraps functionality in dRICH-specific code stored here in `drich-dev`.
0195
0196 ## Abridged Flowchart
0197
0198 ```mermaid
0199 flowchart TB
0200 classDef epic fill:#ff8888,color:black
0201
0202 EventGeneration[Event<br/>Generation]:::epic
0203 subgraph Simulation
0204 epic[<strong>epic</strong><br/>Geometry]:::epic
0205 end
0206 subgraph Reconstruction
0207 irt[<strong>irt</strong><br/>PID Algorithm]:::epic
0208 EICrecon[<strong>EICrecon</strong><br/>Reconstruction]:::epic
0209 end
0210 subgraph Benchmarks
0211 PhysicsBenchmarks[<strong>physics_benchmarks</strong>]:::epic
0212 ReconstructionBenchmarks[<strong>reconstruction_benchmarks</strong>]:::epic
0213 DetectorBenchmarks[<strong>detector_benchmarks</strong>]:::epic
0214 end
0215 EDM4eic[<strong>EDM4eic</strong><br/>Data Model]:::epic
0216
0217 EventGeneration --> epic ---> EICrecon --> PhysicsBenchmarks
0218 irt --> EICrecon
0219 EICrecon --> ReconstructionBenchmarks
0220 epic ---> DetectorBenchmarks
0221 EDM4eic --> Reconstruction
0222 EDM4eic --> Benchmarks
0223 ```
0224
0225 ## Full Flowchart
0226
0227 ```mermaid
0228 flowchart LR
0229 classDef epic fill:#ff8888,color:black
0230 classDef dep fill:#00aaaa,color:black
0231 classDef obj fill:#88ff88,color:black
0232 classDef data fill:#ffff88,color:black
0233 classDef op fill:#770077,color:white
0234
0235 subgraph Legend
0236 epic[ePIC<br/>Repository]:::epic
0237 dep(Dependency<br/>Repository):::dep
0238 data[(Data files)]:::data
0239 obj{{Object}}:::obj
0240 op{Boolean}:::op
0241 dep --> epic --> data
0242 obj --> epic
0243 end
0244 ```
0245
0246
0247 ```mermaid
0248 flowchart TB
0249 classDef epic fill:#ff8888,color:black
0250 classDef dep fill:#00aaaa,color:black
0251
0252 subgraph Data Model
0253 EDM4hep(EDM4hep):::dep
0254 EDM4eic[EDM4eic]:::epic
0255 PODIO(PODIO):::dep
0256 end
0257 PODIO --> EDM4hep --> EDM4eic
0258 PODIO --> EDM4eic
0259 ```
0260
0261 ```mermaid
0262 flowchart TB
0263 classDef epic fill:#ff8888,color:black
0264 classDef dep fill:#00aaaa,color:black
0265 classDef obj fill:#88ff88,color:black
0266 classDef data fill:#ffff88,color:black
0267 classDef op fill:#770077,color:white
0268
0269 subgraph Event Generation
0270 Pythia6(Pythia6):::dep
0271 Pythia8(Pythia8):::dep
0272 OtherGen(etc.):::dep
0273 Hepmc[(HEPMC files)]:::data
0274 Gun(Particle Guns<br/>ddsim OR npsim):::dep
0275 GenOR{OR}:::op
0276 end
0277 Pythia6 --> Hepmc
0278 Pythia8 --> Hepmc
0279 OtherGen --> Hepmc
0280 Hepmc --> GenOR
0281 Gun --> GenOR
0282
0283 subgraph Simulation
0284 DD4hep(DD4hep):::dep
0285 Geant(Geant4):::dep
0286 end
0287 Geant --> DD4hep
0288
0289 subgraph Geometry
0290 Epic[epic]:::epic
0291 subgraph Compact Files
0292 DDCompact{{Compact files}}:::obj
0293 DDMat{{Material Properties}}:::obj
0294 end
0295 DDPlugin{{Geometry Plugins}}:::obj
0296 end
0297 SimOut[(Simulation Output<br/>edm4hep ROOT files)]:::data
0298 DD4hep --> Gun
0299 GenOR --> Epic
0300 DD4hep --> Epic
0301 DDCompact --> Epic
0302 DDMat --> Epic
0303 DDPlugin --> Epic
0304 Epic --> SimOut
0305
0306 subgraph Reconstruction Framework
0307 JANA(JANA2):::dep
0308 EICreconPlugins{{EICrecon<br/>Plugins}}:::obj
0309 EICreconFactories{{EICrecon<br/>Factories}}:::obj
0310 EICreconServices{{EICrecon<br/>Services}}:::obj
0311 EICrecon[EICrecon]:::epic
0312 end
0313 subgraph Reconstruction Algorithms
0314 IRT[irt]:::epic
0315 RecoAlgorithms{{Reconstruction<br/>Algorithms}}:::obj
0316 RecoAlgorithmConfigs{{Algorithm<br/>Configurations}}:::obj
0317 end
0318 RecOut[(Reconstruction Output<br/>edm4hep ROOT files)]:::data
0319 IRT --> RecoAlgorithms
0320 EICreconServices --> EICreconFactories
0321 EICreconFactories --> EICrecon
0322 IRT --> EICreconServices
0323 RecoAlgorithmConfigs --> RecoAlgorithms
0324 RecoAlgorithms --> EICreconFactories
0325 EICreconFactories --> RecoAlgorithmConfigs
0326 EICreconPlugins --> EICrecon
0327 JANA --> EICrecon
0328 SimOut --> EICrecon
0329 EICrecon --> RecOut
0330
0331 subgraph Benchmarks
0332 PhysicsBenchmarks[physics_benchmarks]:::epic
0333 ReconstructionBenchmarks[reconstruction_benchmarks]:::epic
0334 DetectorBenchmarks[detector_benchmarks]:::epic
0335 end
0336 AnaOut[(Reconstruction Analysis<br/>ROOT files)]:::data
0337 SimOut --> DetectorBenchmarks
0338 RecOut --> PhysicsBenchmarks
0339 RecOut --> ReconstructionBenchmarks --> AnaOut
0340
0341 ```
0342
0343
0344 ---
0345
0346 <a name="geometry"></a>
0347 # Geometry and Materials
0348 - the geometry and materials are implemented in DD4hep, in the
0349 [epic](https://github.com/eic/epic) repository
0350 - see the [DD4hep class index](https://dd4hep.web.cern.ch/dd4hep/reference/)
0351 or the [homepage](https://dd4hep.web.cern.ch/dd4hep/) for documentation
0352 - the following files in `epic/` are relevant for the dRICH:
0353 - `compact/drich.xml`: the compact file for the dRICH
0354 - constants for the geometry (e.g., dimensions, positions)
0355 - see `compact/definitions.xml` for main constants (for the full detector),
0356 such as global positioning
0357 - use `./search_compact_params.sh [PATTERN]` to quickly obtain the
0358 *numerical* value of any constant, where `[PATTERN]` is case sensitive
0359 (e.g., `./search_compact_params.sh DRICH`); this is a script in
0360 `drich-dev` which wraps `npdet_info`
0361 - see `comment` tags for details of all parameters
0362 - `compact/optical_materials.xml` for surface and material property tables,
0363 such as refractive index
0364 - property tables relevant for the dRICH can be generated by following
0365 [doc/material_tables.md](doc/material_tables.md)
0366 - see `compact/materials.xml` for material definitions and
0367 `compact/elements.xml` for elements
0368 - materials and parameterizations relevent for the dRICH contain the
0369 substring `DRICH` in their name
0370 - materials etc. are referenced by name in `compact/drich.xml`
0371 - the full detector compact file is `$DETECTOR_PATH/epic.xml`, which is generated via
0372 Jinja during `cmake` (run `build.sh epic`), along with a dRICH-only
0373 compact file `$DETECTOR_PATH/epic_drich_only.xml`
0374 - these compact files are used by many scripts, such as `npsim`, whereas
0375 `compact/drich.xml` is *only* for the dRICH implementation itself
0376 - `build.sh epic` (`cmake`) will also copy local `epic/compact/*.xml`
0377 files to `$DETECTOR_PATH`, since the generated compact files (`$DETECTOR_PATH/epic*.xml`)
0378 reference compact files in `$DETECTOR_PATH`
0379 - `src/DRICH_geo.cpp` is the C++ source file for the dRICH
0380 - relies on constants from the compact files
0381 - builds the dRICH
0382 - placement algorithms
0383 - parameterizations (e.g., of the mirrors)
0384 - see comments within the code for documentation
0385
0386 ## Viewing the Geometry and Parameter Values
0387 - run `./geometry.sh` to produce the `TGeo` geometry ROOT file
0388 - follow the usage guide to specify whether to draw the full EPIC
0389 detector, or just the dRICH
0390 - output ROOT file will be in `geo/`, by default
0391 - open the resulting ROOT file in `jsroot` geoviewer, using either:
0392 - [CERN host](https://root.cern/js/) (recommended)
0393 - Local host (advanced, but offers better control) - see [setup guide](doc/jsroot.md)
0394 - [ANL hosted](https://eic.phy.anl.gov/geoviewer/)
0395 - alternatively, run `view.py` to use a `ROOT` `TGeoManager`
0396 - browse the ROOT file geometry tree in the sidebar on the left:
0397 ```
0398 detector_geometry.root
0399 └── default
0400 └── world_volume
0401 ├── ...
0402 ├── DRICH
0403 └── ...
0404 ```
0405 - right click on the desired component, then click `Draw`
0406 - the default projection is perspective, but if you need to check alignment,
0407 change to orthographic projection:
0408 - right click -> show controls -> advanced -> orthographic camera
0409 - square your browser window aspect ratio, since the default aspect ratio is
0410 whatever your browser window is
0411 - more documentation found on [jsroot website](https://root.cern/js/)
0412 - check for overlaps
0413 - typically more efficient to let the CI do this (in `epic`)
0414 - call `./overlap_check.sh` to run a local check
0415 - one check faster and less accurate, the other is slower and more accurate
0416 - use `./search_compact_params.sh [PATTERN]` to quickly obtain the value of any
0417 parameter in the compact files, rather than trying to "reverse" the formulas
0418 - for example, `./search_compact_params.sh DRICH` to get all dRICH variables
0419 - the search pattern is case sensitive
0420 - this script is just a wrapper for `npdet_info`, run `npdet_info -h` for
0421 further guidance
0422 - use `dawn.sh` to generate a PNG file showing a cross section of all detectors
0423
0424 ## GDML Output
0425 - currently we use the CI for this, from the `epic` repository
0426 (the `athena` repository has a dRICH specific GDML output CI job, but at the
0427 time of writing this, this automation is not yet present in `epic` CI)
0428 - TODO: add a local script to automate connection to Fun4all
0429
0430 ---
0431
0432 <a name="simulation"></a>
0433 # Simulation
0434 There are some local scripts to aid in simulation development. All compilable
0435 `src/.cpp` programs are compiled by running `make`, which will build
0436 corresponding executables and install them to `bin/`
0437
0438 - `simulate.py`: runs `npsim` with settings for the dRICH and pfRICH
0439 - run with no arguments for usage guidance
0440 - `npsim` is the main script for running Geant4 simulations with DD4hep; it
0441 wraps DD4hep's `ddsim` with some extra settings for Cherenkov detectors,
0442 such as the sensitive detector action
0443 - basically copied to `reconstruction_benchmarks`, but stored here as well for
0444 backup
0445 - example simulation analysis code is found in `src/examples`
0446 - see comments within each for more details
0447 - build with `make` (from the top-level directory); the corresponding executables
0448 will be installed to `bin/`
0449 - `src/draw_hits.cpp` (run with `bin/draw_hits`)
0450 - reads simulation output and draws raw hit positions and number of hits vs.
0451 momentum
0452 - build with `make`, execute as `bin/draw_hits [simulation_output_file]`
0453 - `src/event_display.cpp` (run with `bin/event_display`)
0454 - reads simulation output and draws the hits within sensor pixels, which is
0455 useful for checking mapping of sensor segmentation (pixels)
0456
0457 ## Automated Parameter Variation
0458 - use `scripts/vary_params.rb` to run simulation jobs while varying dRICH compact file parameters
0459 - Ruby gems (dependencies) are required to run this; see [doc/ruby.md](doc/ruby.md) for guidance
0460 - The input of this script is a configuration file, written as a class
0461 - This file includes:
0462 - Which parameters to vary, and how
0463 - Pipelines: shell commands to run on each variant, for example, `simulate.py`
0464 - See `ruby/variator/template.rb` for an example and more details
0465 - The class `Variator` inherits from the common superclass `VariatorBase`
0466 - Add your own `Variator` class in another file, then specify this file
0467 when you call `vary_params.rb`, so that it will use your `Variator` class
0468 rather than the default
0469 - The script runs multi-threaded: one thread per variant
0470 - Output `stdout` and `stderr` are logged, along with your shell command pipelines
0471
0472 ---
0473
0474 <a name="reconstruction"></a>
0475 # Reconstruction
0476
0477 ## IRT: Indirect Ray Tracing
0478
0479 To use reconstruction with IRT, you must be on the correct set of branches. See
0480 the [tables of branches](doc/branches.md) for guidance.
0481
0482 ### EICrecon
0483
0484 The EICrecon version will be better documented later, when at least a basic
0485 version is merged to `main`, but in the meantime, see
0486 [the README in EICrecon](https://github.com/eic/EICrecon/tree/main/src/detectors/DRICH)
0487 (if you see nothing there, change to the appropriate branch).
0488
0489 To run the reconstruction with EICrecon:
0490 ```bash
0491 recon.rb -h # see usage guide (run with no arguments to run with defaults)
0492 ```
0493
0494 There are various configuration files available in `config/`, which depends on which branch
0495 of EICrecon you are currently on.
0496
0497 ---
0498
0499 <a name="benchmarks"></a>
0500 # Benchmarks
0501
0502 The benchmarks run downstream of all other modules, and are useful for running
0503 tests. For example, automated checks of upstream geometry changes, to see what
0504 happens to performance plots.
0505
0506 - obtain and build the `reconstruction_benchmarks` repository (see above)
0507 - run `benchmark.rb` (a symlink to the main benchmark runner script) with no arguments
0508 to see the usage guide
0509
0510 ## `drich-dev` Continuous Integration (CI)
0511
0512 `drich-dev` includes a CI workflow, for rapid testing of changes to the ePIC dRICH
0513 - The CI workflow is triggered on every commit to a branch with an associated pull request
0514 - The workflow includes:
0515 - Build tests: all modules are built in order of dependence
0516 - Pipeline: simulation, reconstruction, benchmarks, plus some other local executables
0517 from `drich-dev`
0518 - Geometry generation: generate `TGeo` files and tables of constants
0519 - See [workflow file](.github/workflows/ci.yml) for more details
0520 - Edit [`scripts/configure_CI.sh`](scripts/configure_CI.sh) to select which branch each
0521 module should be on
0522 - this is useful if you have made changes to more than one repository
0523 - this _complements_ the CI workflows on each module, allowing dRICH developers to test the full
0524 simulation-reconstruction-benchmarks pipeline on any custom combination of `git` branches
0525
0526 ---
0527
0528 <a name="miscellaneous"></a>
0529 # Miscellaneous
0530 - the `math/` directory contains scripts and Mathematica notebooks used to
0531 perform miscellaneous calculations; many are "once and done" and don't really
0532 need to be implemented in the source code
0533 - the `scripts/` directory contains all other miscellaneous scripts;
0534 - some scripts are in Ruby; follow [this guide](doc/ruby.md) to install gems
0535 (dependencies)
0536 - `deprecated/` contains some old scripts which may also be helpful
0537
0538 ## Upstream Development Support
0539 This section contains notes for building upstream repositories. Clone the repositories
0540 that you want to test to this top-level directory. The general build procedure is:
0541 ```bash
0542 source environ.sh
0543 build.sh DD4hep
0544 source scripts/this_DD4hep.sh
0545 build.sh NPDet
0546 source scripts/this_NPDet.sh # note: you may prefer to directly call scripts in NPDet/install/bin
0547 rebuild_all.sh
0548 ```
0549 Only build these repositories if you want to override the versions installed in
0550 `eic-shell`. To revert back to the `eic-shell` versions, restart your
0551 `eic-shell` instance and run `source environ.sh`; you may also need to run
0552 `rebuild_all.sh` (or `rebuild_all.sh clean`).
