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