Instructions for running JiveXML
JiveXML is an Athena package that contains algorithms to convert event data to XML files. The XML files can then be read in by the Atlantis Event Display. Both fully reconstructed and fast simulated events (Atlfast) can be converted to XML and viewed with Atlantis.
To display the maximum information from your events, you need to run the full reconstruction on data after digitization (e.g. using RecExCommon, see below). But JiveXML runs also on ESD files (which contain most reconstructed information) and AODs. For details on the different running modes see the JiveXML TWiki page.
Since ATLAS offline release 13.0.0, the JiveXML package is split up into the following independent sub-packages (click on the link to be directed to the respective SVN repository):
All sub-system packages depend solely on the "master" package, JiveXML, and there is no further inter-dependency (e.g. the InDet package does not depend on the Muon package, etc).
Running with full reconstruction
Creating JiveXML files with RecExCommon is described in detail here. The following is just a brief overview.
In RecExCommon there is a special flag, doJiveXML (=False by default), for running JiveXML. So, you simply need to add in your command line:
> athena -c doJiveXML=True jobOptions.py
This will produce xml files (one per event for all the events processed by athena) which contain all the information that Atlantis can display and is available during athena running.
If you would like to produce xml files only for specific events, say events 12 and 13 of the file you are running, you have to follow the usual RecExCommon instructions:
> athena -c "doJiveXML=True; EvtMax=2; SkipEvents=11" jobOptions.py
See also the relevant section in the RecExCommon Wiki page.
Producing XML files for some events
As mentioned above, in "normal running" you would produce one XML per event processed by athena. However, it is ofter useful/necessary/sufficient to produce XML files only for a few pathological/interesting events out of the many (thousands) that you would process in an athena job.
This is possible to do with JiveXML because the generation of the XML files is done by a regular Athena Algorithm AlgoJiveXML. If you want to produce XML files for a few specific events out of the many that you process in your job, you simply need to add in your jobOptions the instruction to conditionally run that Algorithm. The recommended way to do this is using TAG-file information as described in the JiveXMLWithTag TWiki pages. On the same page there is also an example on how to do to generate XML files using your own custom filter algorithm.
If you have your own setup for running athena then you must add at the bottom of your jobOptions file the following lines:
include( "JiveXML/JiveXML_jobOptionBase.py" )
include( "JiveXML/DataTypes_All.py" )
The first include adds the JiveXML dll and the TopAlg (AlgoJiveXML); the second specifies all the DataTypes that will be searched for in StoreGate and will be included in the xml files, if found. The DataTypes are grouped per "sub-system". So, for example, if you are interested in displaying only on Inner Detector data, instead of the second line above you may just add:
include( "JiveXML/DataTypes_InDet.py" )
There are also the files DataTypes_AOD.py, DataTypes_Calos.py, DataTypes_Muons.py, DataTypes_Reco.py, DataTypes_Trig.py, DataTypes_Tracking.py and DataTypes_Truth.py to pick from, for specialised running.
Running with Atlfast
If you have a job running Atlfast and you would like to produce xml files to view with Atlantis, you have to include in your jobOptions file the following line:
include( "JiveXML/JiveXMLAtlfastAOD_jobOptionFragment.py" )
Generating the geometry files for Atlantis
All the geometry information for Atlantis is stored in two XML files, calledAGeometry.xml andAMuonGeometry.xml. These files are generated with info directly from GeoModel. By default they contain the final ATLAS geometry. For commissioning studies, you may need different geometry setups. To produce these files, you just need to add the following jobOption when running JiveXML:
topSequence.AlgoJiveXML.WriteGeometry = True
This will produce the above two files in your Athena run directory. You then need to copy the two new files under the geometry directory of your Atlantis distribution.
Name of XML files
You can control the names of the files that JiveXML will produce. For example if your data set is a Z to ee DC2 sample, then by adding in your jobOptions the following lines (after the lines mentioned above):
topSequence.AlgoJiveXML.StreamTools['StreamToFileTool'].FileNamePrefix = "Zee_DC2"
Your files will have names of the form: Zee_DC2_RunNumber_EventNumber.xml (where RunNumber and EventNumber are the actual numbers obtained in athena).