StrippingLine builder requirements

Stripping line builders

A stripping line builder is any kind of python code, in a module available at runtime when running under the DaVinci environment, that can provide a set of stripping lines given a set of configuration parameters. It is to be used by the stripping framework to construct all the streams to be run in a given stripping production. Rather than imposing constraints on the techniques and coding conventions and styles used to implement them, we provide a specification in the form of a set of stringent tests that the stripping line builder must pass. These are designed to minimise the chance of stripping lines interfering with each other, to allow for the testing of lines within and without a full stripping job, to allow for easy "cloning" of sets of lines with different configuration parameters, and to check and enforce a direct mapping between stripping line names and the output location of any data they may write to the transient event store and, more importantly, to a DST.

Requirements

These are the requirements for classes that should be used for building stripping lines, along the lines of what has been suggested in various public meetings for a while now. Anything stripping line builder that passes the tests is considered to be functionally OK. My requirements so far are (assume that the line builder class or callable is called LineBuilder:

  1. Instantiation from string and map: LineBuilder('TestLines', {.....})
  2. No default construction. LineBuilder() raises.
  3. No single parameter construction. LineBuilder('Fred'), LineBuilder(someConfigDict) raise.
  4. Support arbitrary number of instances, buildable as LineBuilder('name', config_dict)
  5. No duplicate names. LineBuilder('Fred', config) raises if LineBuilder('Fred', config) has already been instantiated.
  6. Bad configuration dictionary raises. LineBuilder('Fred', config) raises if config doesn't have the keys LineBuilder expects.
  7. LineBuilder.lines() returns iterable of StrippingLines only
  8. LineBuilder.lines() access does not allow modification of underlying member iterable. So x = b.lines(); x['bad']=99; does not modify b.lines().
  9. line output locations follow rule if line name = "StrippingXYZ", location ends with "/XYZ". We can review the specifics of the rule, but the same, direct name to location mapping must apply to all lines. The only allowable exception is when the output location is the empty string, for lines that do not "write" data.
  10. LineBuilder.lineNames() returns a sequence with names of the lines.
  11. LineBuilder.outputLocations() returns sequence with the TES locations of the output of the lines.
  12. LineBuilder.lineFromName(name) returns StrippingLine named name if it iexists, or None otherwise.

I have created a test suite that can be used to check this. It is in the new package Phys/StrippingUtils, module StrippingUtils.LineBuilderTests. I have also implelemted a base class StrippingUtils.Utils.LineBuilder, that makes it easier to write a builder that passes the tests, but it isn't necessary to use it. And i have re-implemented StrippingSelections.StrippingBs2JpsiPhiPrescaledAndDetatched to inherit from LineBuilder and pass all the tests (it was an insignificant effort). There is also a new example test, StrippingSelections/tests/test_bs2jpsiphi_prescaled_and_detatched.py This shows the easiest way to run the test suite.

Besides these testable requirements, there is the obvious requirement that the line builders should be well documented, with the general module documentation giving a good description of the use of the builder, the meaning of each parameter, as well as examples on how to use it. Needless to say, all classes and functions must be suitably documented. Unfortunately, this is not something that be tested automatically. But the objective is to be able to understand everything that a line builder (and that includes the particle selections within) is doing via the inbuild python help system. It should not be necessary for anybody to have to read the code, but the code should be readable in any case!

Bear in mind that no mention is made of the selection logic that goes on in the selections. The validity of cuts in a selection is the domain of the authors of the selections and their working groups. It is also worth noting that, while it is not explicitly forbidden to use ConfigurableUsers as line builders, these would fail most of the tests.

Testing a line builder.

Assuming the line builder is class X2YZLineBuilder in module SetrppingSelections.StrippingX2YZ, it is very simple to test for conformance. Currently, it is necessary to get and build Phys/StrippingUtils v1r0 first. Then, a simple test program like the following is all that is needed:

from StrippingSelections.StrippingX2YZ import X2YZLineBuilder

config_params = { ... } # dictionary of configuration parameters - values

from StrippingUtils import LineBuilderTests

def test_line_builder() :
    LineBuilderTests.test_line_builder(builder, config_params)

if __name__ == '__main__' :
    
    test_line_builder()

This test is written such that it can be executed directly or with py.test, but the important line is = LineBuilderTests.test_line_builder(builder, config_params)=. This runs a whole set of tests, all of which are individually available in the StrippingUtils.LineBuilderTests module.

Some hints

  • Use a string name in the constructor and use it in all Configurables, Selections and StrippingLines created by the builder. This way, you can avoid name duplication of Configurables when making many instances of the set of stripping lines.
  • Only instantiate Configurables, Selections, StrippingLines once and keep them as member data. This avoids name duplication by creating the same Configurables, Selections, StrippingLines more than once.
  • Use Selection-type objects from the particle selection toolkit to make StrippingLines instead of plain Configurables. This will automatically ensure line to location mapping and enforce the no name duplication requirement.
  • Consider using StrippingUtils.Utils.LineBuilder as a base class for your line builders. See StrippingSelections.StrippingBs2JpsiPhiPrescaledAndDetatched as an example of how to use it.

Using the LineBuilder base class

There are no requirements on the internal structure of the stripping line builders. As long as they pass the requirement test suite they can be considered as valid. The LineBuilder base class simply provides some functionality to make it easier to code conformant line builders, and provides some functionality to acces line names, output locations, and so on. In the future, this functionality might become part of the requirements, in which case it will be documented and added to the test suite.

-- JuanPalacios - 23-Nov-2010

Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r4 - 2011-01-31 - unknown
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    LHCb All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback