Warning, /EICrecon/docs/howto/visualize_callgraph.md is written in an unsupported language. File is not indexed.
0001 # Visualizing Calllgraphs
0002
0003 ## Overview
0004 JANA2 has a built-in feature to help visualize the callgraph of a job.
0005 This is most easily activated by adding the `janadot` plugin to the
0006 job. It will automatically turn on JANA's call stack recording which
0007 keeps track of the call dependencies between factories, processors, and
0008 sources in the event. It also times how long it takes each factory
0009 to run, integrating it over all calls so that one can see the relative
0010 time spent in each factory.
0011
0012 *Note that this requires JANA2 v2.0.8 or later and EICrecon v0.3.6 or
0013 later.*
0014
0015 ## How to run
0016 To make an image of the call graph of a job, one just needs to add
0017 the `janadot` plugin like this:
0018 ~~~bash
0019 eicrecon -Pplugins=janadot sim_file.edm4hep.root
0020 ~~~
0021
0022 This will create a file at the end of the job called "jana.dot"
0023 which contains the relevant information in a form that the
0024 *dot* program can read. (*dot comes in the graphviz package
0025 on most Linux distributions*). At the end of the job, a
0026 message like the following is printed:
0027
0028 ~~~bash
0029 Opening output file "jana.dot"
0030
0031 Factory calling information written to "jana.dot". To create a graphic
0032 from this, use the dot program. For example, to make a PDF file do the following:
0033
0034 dot -Tpdf jana.dot -o jana.pdf
0035
0036 This should give you a file named "jana.pdf".
0037 ~~~
0038
0039 You can use dot to make either a PDF or PNG formatted file. To make a PNG file
0040 you would run:
0041
0042 ~~~bash
0043 dot -Tpng jana.dot -o jana.png
0044 ~~~
0045
0046 ### Running for a single detector
0047 By default `eicrecon` activates the full reconstruction. This will
0048 result in a very busy callgraph that can be hard to read if you
0049 are only interested in one detector. (See [here](https://eic.github.io/EICrecon/howto/callgraphs/all.png).)
0050 To activate for a specific factory, you can specify the relevant output
0051 collection using the `podio:output_collections` parameter.
0052 Here is an example for the *EcalEndcapN*:
0053
0054 ~~~bash
0055 eicrecon -Pplugins=janadot \
0056 -Ppodio:output_collections=EcalEndcapNMergedClusters \
0057 sim_file.edm4hep.root
0058 ~~~
0059
0060 The above will produce something like the following:
0061 
0062
0063 In the plot, the oval at the top is the JEventProcessor making the
0064 initial request for objects. (This is where the *podio:output_collections*
0065 parameter is used). The rectangles in the middle represent factories (i.e. algorithms).
0066 The green trapezoid at the bottom is the object read from the input file.
0067 This is representative of the flow JANA implements. Namely, the requests for
0068 data objects flow from top to bottom and the data objects themselves are
0069 actually created in the order going from bottom to top.
0070
0071 The arrows point in the direction of the request and the numbers next to
0072 them indicate 1.) how many times that request was made, 2.) the total amount of time
0073 spent satisfying the request, and 3.) the fraction of the overall job time
0074 that represents. In this example, 100 events were processed and so the request
0075 was made 100 times at each stage. Similarly, the numbers in the boxes indicate
0076 the total time spent in that factory, integrated over all calls, and the total
0077 job fraction it represents.
0078
0079 Note that the only factory specified in the above example was for the
0080 `EcalEndcapNMergedClusters` collection. All of the other factories shown
0081 were activated in order to satisfy the request for the `EcalEndcapNMergedClusters`
0082 objects. If instead we would have specified only the `EcalEndcapNRecHits`, then
0083 only the `EcalEndcapNRecHits` and `EcalEndcapNRawHits` factories would have shown
0084 up in the plot.
0085
0086
0087 ## Examples
0088 Below are some example images produced for 100 DIS events. The events were
0089 simulated using the following on the JLab ifarm:
0090
0091 ~~~bash
0092 cp /work/eic2/EPIC/MC_input/SIDIS/Lambda_ABCONV/hepmc_Lambda1_ab_hiAcc_18x275_00.hepmc.gz .
0093 tar xzf hepmc_Lambda1_ab_hiAcc_18x275_00.hepmc.gz
0094 ddsim --compactFile $DETECTOR_PATH/epic_arches.xml --numberOfEvents 100 --inputFiles hepmc_Lambda1_ab_hiAcc_18x275_00.hepmc --outputFile sim_hepmc3_Lambda1_ab_hiAcc_18x275_00.edm4hep.root
0095 ~~~
0096
0097 Note that in these examples a relatively small number of events was processed
0098 and the startup time which included reading in the geometry from DD4Hep is
0099 included. Thus, it is often the case that the factory indicating the largest
0100 time is just the first place where the geometry was read in.
0101
0102 | Example images |
0103 |------------------------------------------------------------------------------------------------|
0104 |  |
0105 |  |
0106 |  |
0107 |  |
0108 |  |
0109 |  |
0110 |  |
0111 |  |
0112 |  |
0113 |  |
0114 |  |
0115 |  |
0116 |  |
0117 |  |
0118 |  |
