Add some documentation.

Hlt/Hlt1Conf/options/hlt1_example_throughput.py

@@ -8,12 +8,29 @@
 # granted to it by virtue of its status as an Intergovernmental Organization  #
 # or submit itself to any jurisdiction.                                       #
 ###############################################################################
+"""Run HLT1 configured for throughput tests.
+
+The differences with respect to hlt1_example.py are:
+
+* Assume the input files are available on a RAM disk `/run/swtest`, which
+  avoids the penalty of loading each file from disk.
+* Assumes the existance of a file 00067189.mdf on that RAM disk.
+* Uses the EvtStoreSvc to handle interactions with the TES, as this is faster
+  than the default HiveWhiteBoard (although doesn't work on DSTs).
+* Uses an alternative, faster IOSvc.
+
+The latter two points may be made defaults for all HLT1 execution in the
+future, but are not currently compatible with certain input types.
+"""
 from PyConf.environment import EverythingHandler, setupInputFromTestFileDB
 from PyConf.Algorithms import FTRawBankDecoder
 from RecoConf.hlt1_tracking import (require_gec, make_raw_data,
                                     make_RawData_IOSvc)
 from Hlt1Conf.lines.track_mva import (one_track_mva_line, two_track_mva_line)
 
+RAM_DISK = '/run/swtest'
+INPUT_FILE = '00067189.mdf'
+
 tes = 'EvtStoreSvc'
 env = EverythingHandler(
     threadPoolSize=1, nEventSlots=1, evtMax=100000, debug=True, TESName=tes)
@@ -21,7 +38,8 @@ env = EverythingHandler(
 ftdec_v = 4
 inputFiles = setupInputFromTestFileDB(
     'MiniBrunel_2018_MinBias_FTv4_MDF',
-    inputFiles=['/run/swtest/00067189.mdf'] * 50,
+    # Run over the single file 50 times to make sure we process lots of events
+    inputFiles=[os.path.join(RAM_DISK, INPUT_FILE)] * 50,
     TESName=tes,
     fileType='MDF',
     withEventSelector=False)

Hlt/Hlt1Conf/python/Hlt1Conf/algorithms.py

@@ -106,6 +106,38 @@ def CombineTracks(NBodies=2,
                   VertexDump=None,
                   PrTracks=False,
                   **kwargs):
+    """Return a configured CombineTracks instance.
+
+    If any of `ChildDump`, `CombinationDump`, or `VertexDump` are not None, a
+    version of the combiner is returned that will produce an ntuple. The ntuple
+    has one row for each combination, and is useful for inspecting values that
+    the combiner uses to evaluate selections. Each `Dump` argument is a
+    dictionary whose keys are strings, corresponding to the row in the ntuple
+    that will be filled with the functor value.
+
+    Parameters
+    ----------
+    NBodies : int
+        The number of tracks entering each combination. Currently only 2-track
+        combinations are supported.
+    CombinationCut : Functors.Functor
+        Functor to be applied to the N-track combination object.
+    VertexCut : Functors.Functor
+        Functor to be applied to the vertex object.
+    VoidDump : dict of str to Functors.Functor
+        Functors to be evaluated for each combination when creating an ntuple.
+    ChildDump : dict of str to Functors.Functor
+        Functors to be evaluated for each child in each combination when
+        creating an ntuple.
+    CombinationDump : dict of str to Functors.Functor
+        Functors to be evaluated for each combination when creating an ntuple.
+    VertexDump : dict of str to Functors.Functor
+        Functors to be evaluated for each combination when creating an ntuple.
+    PrTracks : bool
+        If True, a combiner algorithm instance that accepts
+        PrFittedForwardTrack objects is returned. Otherwise, an instance that
+        accepts Track::v2 objects is returned.
+    """
     assert NBodies == 2
 
     def parse(input_dict):