Differences

This shows you the differences between two versions of the page.

--- hepsim:dev_tags [2017/08/30 16:17]
hepsim17 [How to submit detector tags]
+++ hepsim:dev_tags [2017/09/13 21:22] (current)
hepsim17
@@ Line 4: / Line 4: @@
 ====== Submitting tags ======
+As a HepSim user, you can submit your detector description and the simulation/reconstruction chain to HepSim using "tag" files.
-===== Reconstruction tags =====
+All detector simulations in HepSim are created using the concept of tags, which are
+small (<5 MB) files that include necessary information to convert truth-level files to final reconstructed events. All tags
+can be found in [[http://atlaswww.hep.anl.gov/hepsim/recotags.php|this page]].
+In many cases we call them "reconstruction" tags, but, generally, they include Geant4 simulation and reconstruction steps.
+A reconstruction tag is associated with the file with the name **rfull[XXX].tgz**, where **[XXX]** is a number.
+Fast simulations have tags with the name **rfast[XXX].tgz**.
-Full detector simulations are created using the concept of tags, which are
+The tag files are used for:
-small (<3MB) files that include necessary information to convert truth-level files to final reconstructed events. All tags
-can be found in [[http://atlaswww.hep.anl.gov/hepsim/recotags.php|this page]].
-In many cases we call them "reconstruction" tags, but, generally, include both Geant4  simulation and reconstruction steps.
-The reconstruction tag is associated with a file with the name "rfull[XXX].tgz", where [XXX] is a number
+  * archiving the detector geometry
-(fast simulations have the files "rfast[XXX].tgz").
+  * creating the web page with the detector description
+  * archiving calibration files etc.
+  * defining the used software
+  * defining the tag name to be used for downloading events
+  * defining the workflow of the simulation-reconstruction steps
+  * creating the necessary files for event visualization using Jas4pp (only for slic/lcsim complied software)
+  * feeding the HPC and grid jobs for simulation and reconstruction (for dockers & singularity images).
-The goal of the tag files:
+Reconstruction tags have unique names. There can be several reconstruction tags corresponding to a single detector, since simulation and reconstruction can be done using different software.
+They are small files that are sourced by reconstruction software on grid or HPC. A file **rfull[XXX].tgz**
+has everything you need to create LCIO/ROOT files with reconstructed events.
-  * archive the detector geometry
-  * create a web page for HepSim with the detector description
-  * archive calibration files etc.
-  * define the used software
-  * define the tag name to be used for downloading events
-  * define the workflow of the simulation-reconstruction steps
-  * create the necessary files for event visualization using Jas4pp
+====== Structure of tags ======
+In most cases, the directory inside rfull[XXX].tgz has this structure (for a detector called "sifcch7"):
-Reconstruction tags have unique names. There can be several reconstruction tags corresponding to a single detector, since simulation and reconstruction can be done using different software.
-They are small files that are sourced by reconstruction software on grid or HPC. A file "rfull[XXX].tgz"
-has everything you need to create LCIO/ROOT files with reconstructed events. Such files include the detector geometry,  configuration scripts, setup files etc. In most cases, the directory inside rfull[XXX].tgz has this structure (for a detector called "sifcch7"):
 <code bash>
@@ Line 38: / Line 40: @@
 .....     # other required files if needed
 sifcch7   # the directory with detector geometry    (always required!)
-    - compact.xml     # main detector geometry file (always required, but can be a dummy!)
+    - compact.xml     # main detector geometry file (always required, but can be a dummy)
-    - other.xml ...   # some other XML files with detector (optional)
+    - other.xml ...   # some other XML files with detector components -> optional
-    - sifcch7.heprep  # some converted files, if needed
+    - sifcch7.heprep  # some converted files, if needed -> optional file
-    - sifcch7.lcdd    # optional file for event displays
+    - sifcch7.lcdd    # file for event displays -> optional file
-    - sifcch7.pandora # optional file for Pandora
+    - sifcch7.pandora # file for Pandora        -> optional file
-    - sifcch7.json    # optional geometry file
+    - sifcch7.json    # geometry JSON file      -> optional file
-    - sifcch7.root    # optional geometry file (use to make 3D display)
+    - sifcch7.root    # geometry file (use to make 3D display) -> optional file
-    - sifcch7.html    # HTML description (required)
+    - sifcch7.html    # HTML description                       -> required file
-    - view1.png       # main image to view the detector (440x480 px, Y-Z)
+    - view1.png       # main image to view the detector (440x480 px, Y-Z) -> required for HepSim page
-    - view2.png       # 2nd image to view the detector (440x480 px, X-Y)
+    - view2.png       # 2nd image to view the detector (440x480 px, X-Y)  -> optional file
     - some config files
 </code>
 To see what is inside, download "rful009.tgz" from [[http://atlaswww.hep.anl.gov/hepsim/taginfo.php?id=rfull009]].
-In addition to the detector geometry, the tag files include all settings needed for successful creation of events.
+Such files include the detector geometry.
+In addition to the detector geometry, the tag files include the settings needed for creation of events.
 Generally, the form of this file is free, as long as it includes sufficient information
 to create reconstructed events. In many cases, the tag file has several scripts : A_RUN (to make a complete reconstruction chain) and TEST (to test on a few events). The software to run these scripts should be fully specified, and it is up to the author to make sure that one can use such files to run over events on a dedicated computing resource.
-<note important>Note that the simulation and reconstruction software should not be put inside rfullXXX.tgz files. This file size limit of 3MB is important to keep a low network bandwidth
+<note important>Note that the simulation and reconstruction software should not be put inside **rfull[XXX].tgz** files. This file size limit of 5 MB is important to keep a low network bandwidth
 when the tag files are sourced by reconstruction software on each node on HPC or grid,
-which are assumed to contain the needed software used in combination with rfullXXX.tgz files.
+which are assumed to contain the needed software used in combination with **rfull[XXX].tgz** files.
 </note>
 You should create the reconstruction tag if:
-  * detector geometry has changed. In this case, use a different detector name inside rfullXXX.tgz
+  * detector geometry was changed. In this case, use a different detector name inside **rfull[XXX].tgz**
-  * detector geometry is the same, but configuration files and setup scripts have changed.
+  * detector geometry is the same, but configuration files and setup scripts were changed.
-HepSim provides a mechanism to upload rfull[XXX].tgz. After upload, HepSim extracts the
+HepSim provides a mechanism for uploading **rfull[XXX].tgz** files. After upload, HepSim automatically extracts the
-detector from rfull[XXX].tgz and builds an information detector page. Then you will see two entries:
+detector from **rfull[XXX].tgz** and builds an information detector page. Then you will see two entries:
   * [[http://atlaswww.hep.anl.gov/hepsim/detectors.php]]
   * [[http://atlaswww.hep.anl.gov/hepsim/recotags.php]]
-As mentioned before, we leave the authors with the liberty to design rfull[XXX].tgz files. The only strict requirement is that they should have the directory with the detector, its PNG image and the  HTML description, since this populates  the information page with the detector in HepSim.
+As mentioned before, we leave the authors with the liberty to design the **rfull[XXX].tgz** files. The only strict requirement is that they should have the directory with the detector description, a PNG image and the  HTML description, since such populate  the information page with the detector in HepSim.
 The simulation and reconstruction scripts can include all the required
 workflow to work together with the installed software (git, makefiles, wget commands etc).
 <note tip>
-A tag file should have a directory with the detector name, and the "compact.xml" file inside this directory. This structure helps automatically extract the detector for inclusion in HepSim
+A tag file should have a directory with the detector name, and the **compact.xml** file inside this directory. This structure helps automatically extract the detector for inclusion in HepSim.
-Please add compact.xml even if it is a dummy file not used for detector description.</note>
+Please add **compact.xml** even if it is a dummy file not used for detector description.</note>
 After a tag file is uploaded, HepSim performs the following operations with this file:
@@ Line 90: / Line 93: @@
 First, request the account [[https://atlaswww.hep.anl.gov/hepsim/users/selock/user/login.php|HepSim login page]].
-Then, go to [[http://atlaswww.hep.anl.gov/hepsim/|HepSim]] and look at the yellow menu "Admin info" and then "Tag manager". The use the submit panel to upload the tag file. It does some very basic checks that your tag file has necessary structure, and updates the tag description and the detector page.
+Then, go to [[http://atlaswww.hep.anl.gov/hepsim/|HepSim]] and look at the yellow menu "Admin info" and then "Tag manager". Use the submit panel to upload the tag file. HepSim does some basic checks that your tag file has the required structure, and updates the tag description and the detector page.
  --- //[[[email protected]|Sergei Chekanov]] 2017/08/12 21:58//