examples/bic/README.md

0001 # AID2E BIC Example
0002
0003 Run test BIC optimization with AID2E. Illustrates these
0004 points:
0005 - How to define design parameters inline;
0006 - How to run a single-objective optimization;
0007 - How to specify inputs/outputs from different stages,
0008   jobs, and layers.
0009
0010 ## Files
0011 - `workflow.yml`: example config parameters, optimizer, scheduler,
0012   and ePIC workflow.
0013 - `submit.sh`: small script to launch an optimization via
0014   slurm.
0015 - `scripts/bic_angular_reso.py`: analysis script to compute phi
0016   resolution
0017 - `scripts/extract_objective.py`: helper script to extract
0018   phi resolution from analysis output and return it to AID2E
0019   in the necessary format
0020 - `inputs/central_photons_bin*.py`: input DD4hep steering
0021   files defining the 3 kinematic bins used in the example.
0022
0023 ## ePIC Setup
0024 Works out-of-the-box with ePIC geometry. Install geometry with
0025 ```
0026 git clone git@github.com:eic/epic.git
0027 ```
0028 And set `epic_install` in `workflow.yml` to the relative path
0029 to the geometry installation.
0030
0031 ## Run
0032 To run locally via JobLib, edit `workflow.yml` as needed
0033 and then do:
0034 ```
0035 aid2e optimize examples/bic/workflow.yml
0036 ```
0037
0038 To run via Slurm, again edit `workflow.yml` as needed (including
0039 uncommenting the `SlurmRunner` options!) as well as `submit.sh` and
0040 then do:
0041 ```
0042 sbatch submit.sh
0043 ```
0044
0045 ## Workflow
0046 ```mermaid
0047 flowchart TB
0048   C["workflow.yml"] --> O["aid2e optimize"]
0049   O --> B["Schedule trial batch"]
0050
0051   subgraph T["Run one trial workflow"]
0052     G["geo"]
0053     G --> S0["sim 0"]
0054     G --> S1["sim 1"]
0055     G --> s2["sim 2"]
0056
0057     S0 --> M["merge sim output"]
0058     S1 --> M
0059     S2 --> M
0060     M  --> R["reco"]
0061     R  --> A["analysis"]
0062
0063     A --> E["collect objectives"]
0064   end
0065
0066   B --> T
0067   B --> N["Other trials<br/>same workflow"]
0068   M --> C["Collect batch results"]
0069   N --> C
0070   C --> U["Update optimizer"] --> O
0071 ```