examples/drich/README.md

0001 # AID2E dRICH Example
0002
0003 Run dRICH detector-design optimization with AID2E. The main flow is:
0004
0005 ```
0006 drich_optimize.py -> drich_eval.py -> out-{trial}.json -> Ax update
0007 ```
0008
0009 ## Files
0010 - `workflow.yml`: example config optimizer, scheduler, and epic workflow
0011 - `design.params`: geometry parameters and XML edit targets
0012 - `drich_optimize.py`: builds optimizer/scheduler, submits trial jobs, runs one-trial DAGs, updates Ax, writes results
0013 - `drich_eval.py`: launched by DAG stages; runs ePIC stack layers
0014 - `drich_utils.py`: dRICH-specific utilities
0015 - `script/dRICHAna_bootstrap.cpp`: dRICH per-scan analysis code used by the `ana` stage
0016
0017 ## ePIC Setup
0018 It is recommended to use the branch of the fork containing a single-mirror dRICH, which is then compatible with the already built versions of EICrecon and IRT available in eic-shell:24.11.1-stable.
0019
0020 The following repository and branch hold the recommended default geometry for the optimization of the dRICH and will need to be downloaded and built prior to running.
0021
0022 Additionally, the dRICH analysis script will need to be built from within eic-shell prior to running the optimization, located in examples/drich/script
0023
0024 ```
0025 git clone -b 24.11.1-drich-singlemirror https://github.com/cpecar/epic-geom-drich-mobo.git
0026 ./build_epic.sh epic-geom-drich-mobo "$EIC_SOFTWARE"
0027 cd examples/drich/script && make
0028 ```
0029
0030 ## Run
0031 ```
0032 python examples/drich/drich_optimize.py --config examples/drich/workflow.yml
0033 ```
0034
0035 ```mermaid
0036 flowchart TB
0037   C["workflow.yml<br/>config + stages"]
0038   O["drich_optimize.py<br/>optimizer + trial DAG runner"]
0039   E["drich_eval.py<br/>run stage; EpicStack"]
0040   R["out-{trial_index}.json<br/>output objectives + errors"]
0041
0042   C --> O
0043   O -->|"trial config; DAGExecutor"| E
0044   E --> R
0045   R -->|"update Ax"| O
0046 ```