assets/docs/dd4hep-plugin.md

0001 # DD4Hep Plugin
0002
0003 Plugin for DD4Hep that allows to dump stepping action and then convert to Phoenix json format.
0004
0005 ## Usage
0006
0007 1. First one has to build DD4Hep plugin and ensure it is discoverable (e.g. `LD_LIBRARY_PATH` is pointing on it
0008    or it is installed in system libraries)
0009
0010     ```bash
0011     git clone https://github.com/eic/firebird.git
0012     cd dd4hep-plugin
0013     mkdir build && cd build
0014
0015     # This will create prefix/lib folder after the install
0016     cmake ..
0017
0018     make && make install
0019
0020     # Make sure the library and .components file are discoverable:
0021     export LD_LIBRARY_PATH="$(pwd)/prefix/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
0022     ```
0023
0024 2. Now you need to configure DD4Hep. The plugin comes with a stepping action `TextDumpingSteppingAction`
0025    The configuration is done like:
0026
0027    ```python
0028    # Instantiate the stepping action
0029    stepping = DDG4.SteppingAction(kernel, 'TextDumpingSteppingAction/MyStepper')
0030    stepping.OutputFileName = "my_output.txtevt"
0031    stepping.OnlyPrimary = False   # configure what to save (see below)
0032    # ...
0033    kernel.steppingAction().add(stepping)
0034    ```
0035
0036    For the convenience an example steering file is enclosed in this project.
0037    You can copy it, change the settings and use in simulations by `--steeringFile` flag:
0038
0039    ```bash
0040    cp phoenix-dd4hep/steering.py my_steering.py
0041    ddsim --steeringFile=my_steering.py --compactFile=geometry -N=100 --outputFile=sim_output.edm4hep.root --inputFiles sim_input.hepmc
0042    ```
0043
0044    This will produce `sim_output.txtevt` file with simple text file containing steps info
0045    > for large events or e.g. if optical photons are saved, such file could easily be gigabytes in size
0046
0047 3. Convert resulting text file to phoenix.json format. One can use a script `dd4hep_txt_to_phoenix.py` for that
0048
0049    ```bash
0050    python3 phoenix-dd4hep/dd4hep_txt_to_phoenix.py -o result.phoenix.json sim_output.txtevt
0051    ```
0052
0053    This will produce tracks file in phoenix json format
0054
0055 ## Configuration
0056
0057 So far the next parameters can be configured through python
0058
0059 ```bash
0060
0061
0062
0063 ```
0064
0065
0066
0067
0068 ### Run simulation for 10 events
0069 #### (!) Using *.edm4hep.root in the output is mandatory
0070
0071 ```bash
0072 ddsim --steeringFile=steering.py --compactFile=$DETECTOR_PATH/epic.xml -N=100 --outputFile=sim_output.edm4hep.root --inputFiles sim_input.hepmc
0073 ```
0074
0075 ***Example 10 events***
0076
0077 ```bash
0078 python3 test_stepping.py --compactFile=$DETECTOR_PATH/epic.xml -N=10 --outputFile=sim_output.edm4hep.root --inputFiles /mnt/d/data/firebird/pythia8CCDIS_18x275_minQ2-100_beamEffects_xAngle-0.025_hiDiv_1.hepmc
0079 ```
0080
0081 ## EIC specific example
0082
0083 EIC openly provides docker images as well as sample data. Docker/singularity images aka eic_shell
0084 ships all standard HENP stack, such as ROOT, Geant4, DD4Hep, Acts etc.
0085
0086 One can start this example simply by [eic_shell](https://eic.github.io/tutorial-setting-up-environment/index.html) or
0087 [eicweb/eic_xl](https://hub.docker.com/r/eicweb/eic_xl/tags) docker image:
0088
0089 ```bash
0090 docker pull eicweb/eic_xl:nightly
0091 docker run --rm -it -v /host/where/phoenix-dd4hep:/mnt/phoenix-dd4hep -v /host/place/with/data:/mnt/data eicweb/eic_xl:nightly
0092 ```
0093
0094 ```bash
0095 # Build dd4hep plugin and install to system root
0096 cd /mnt/phoenix-dd4hep
0097 mkdir build && cd build && cmake ..
0098 make && make install
0099 cd ..
0100
0101 # Make sure the library and .components file are discoverable:
0102 export LD_LIBRARY_PATH="/mnt/phoenix-dd4hep/prefix/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
0103
0104 # Use the default ePIC detector for DD4HEP
0105 source /opt/detector/epic-main/bin/thisepic.sh
0106
0107 # Copy example steering file
0108 cp /mnt/phoenix-dd4hep/steering.py /mnt/data/
0109 # edit parameters of /mnt/data/steering.py
0110
0111 # Copy example hepmc3 input file
0112 xrdcp root://dtn2001.jlab.org:1094//work/eic2/EPIC/EVGEN/CI/pythia8NCDIS_5x41_minQ2=1_beamEffects_xAngle=-0.025_hiDiv_1_20ev.hepmc3.tree.root /mnt/data/test.hepmc3.tree.root
0113
0114 # Run DDSIM 10 events
0115 ddsim --steeringFile=/mnt/data/steering.py --compactFile=$DETECTOR_PATH/epic.xml -N=10 --outputFile=/mnt/data/sim_output.edm4hep.root --inputFiles /mnt/data/test.hepmc3.tree.root
0116
0117 # Convert to phoenix
0118 python3 dd4hep_txt_to_phoenix.py -o /mnt/data/result.phoenix.json /mnt/data/sim_output.evt.txt
0119 ```
0120