Go Back to: C++ Manual General Site

LDMX.Framework package

Submodules

LDMX.Framework.EventTree module

LDMX.Framework.histogram module

Histogram configuration objects

These histogram objects are passed to the HistogramPool to be created for processors that they are grouped with.

class LDMX.Framework.histogram.histogram(name, xlabel, xbins, ylabel='', ybins=[])

Bases: object

Object to hold parameters for a one-dimensional root histogram

This histogram object will be passed to the HistogramPool and created, so that it is available to the processor who created it.

If the ybins member is empty, then the histogram is assumed to be a 1D histogram.

Parameters:

• name (str) – pointer name of histogram (like you are defining a variable)

• xlabel (str) – title of x-axis that this histogram represents

• xbins (list of floats) – bin edges along x-axis

• ylabel (str) – title of y-axis that this histogram represents

• ybins (list of floats) – bin edges along y-axis

LDMX.Framework.histogram.uniform_binning(nbins, minedge, maxedge)

Create a list of bin edges uniformly separated

Parameters:

• nbins (int) – Number of bins

• minedge (float) – Lower edge of binning

• maxedge (float) – Upper edge of binning

LDMX.Framework.ldmxcfg module

ldmxcfg

Basic python configuration for ldmx-sw application

class LDMX.Framework.ldmxcfg.Analyzer(instanceName, className, moduleName)

Bases: EventProcessor

A analyzer object.

This object contains the parameters that are necessary for a framework::Analyzer to be configured.

See also

LDMX.Framework.ldmxcfg.EventProcessor

base class

class LDMX.Framework.ldmxcfg.ConditionsObjectProvider(objectName, className, moduleName)

Bases: object

A ConditionsObjectProvider

This object contains the parameters that are necessary for a framework::ConditionsObjectProvider to be configured.

In this constructor we also do two helpful processes. 1. We append the module that this provider is in to the list of libraries to load 2. We declare this provider so that the Process “knows” it exists and will load it into the run

Parameters:

• objectName (str) – Name of the object this provider provides

• className (str) – Name (including namespace) of the C++ class of the provider

• moduleName (str) – Name of module that this COP is compiled into (e.g. Ecal or EventProc)

tagName

Tag which identifies the generation of information

Type:

str

setTag(newtag)

Set the tag generation of the Conditions

Parameters:

newtag (str) – Tag for generation of conditions

class LDMX.Framework.ldmxcfg.EventProcessor(instanceName, className, moduleName)

Bases: object

An EventProcessor object

This object contains the parameters that are necessary for a framework::EventProcessor to be configured.

You should NOT use this class directly. Use one of the derived classes Producer or Analyzer for clarity.

Parameters:

• instanceName (str) – Name of this copy of the producer object

• className (str) – Name (including namespace) of the C++ class that this processor should be

• moduleName (str) – Name of module the C++ class is in (e.g. Ecal or SimCore) or full path to the library that should be loaded

histograms

List of histogram configure objects for the HistogramPool to make for this processor

Type:

list of histogram1D objects

See also

LDMX.Framework.ldmxcfg.Producer

Producer configuration object

LDMX.Framework.ldmxcfg.Analyzer

Analyzer configuration object

LDMX.Framework.histogram.histogram

histogram configuration object

build1DHistogram(name, xlabel, bins, xmin=None, xmax=None)

Make a 1D histogram

If xmin and xmax are not provided, bins is assumed to be the bin edges on the x-axis. If they are both provided, bins is assumed to be the number of bins on the x-axis.

Parameters:

• name (str) – variable name of histogram

• xlabel (str) – title of x-axis of histogram

• bins (int OR list of floats) – Number of bins on x-axis OR bin edges on x-axis

• xmin (float) – Minimum edge of bins on x-axis

• xmax (float) – Maximum edge of bins on x-axis

See also

LDMX.Framework.histogram.histogram

histogram configuration object

build2DHistogram(name, xlabel='X Axis', xbins=1, xmin=None, xmax=None, ylabel='Y Axis', ybins=1, ymin=None, ymax=None)

Create a 2D histogram

If {x,y}min or {x,y}max are not provided, {x,y}bins is assumed to be the bin edges on the {x,y}-axis. If they are both provided, {x,y}-bins is assumed to be the number of bins on the {x,y}-axis.

Parameters:

• name (str) – variable name of histogram

• xlabel (str) – title of x-axis of histogram

• xbins (int OR list of floats) – Number of bins on x-axis OR list of bin edges on x-axis

• xmin (float) – Minimum edge of bins on x-axis

• xmax (float) – Maximum edge of bins on x-axis

• ylabel (str) – title of y-axis of histogram

• ybins (int OR list of floats) – Number of bins on y-axis OR list of bin edges on y-axis

• ymin (float) – Minimum edge of bins on y-axis

• ymay (float) – Mayimum edge of bins on y-axis

See also

LDMX.Framework.histogram.histogram

histogram configuration object

Examples

When doing all uniform binning, you can specify the arguments by position.

myProcessor.build2DHistogram( ‘dummy’ ,

‘My X Axis’ , 20 , 0. , 1. , ‘My Y Axis’ , 60 , 0. , 10. )

When using variable binning, you have to use the parameter names.

myProcessor.build2DHistogram( ‘dummy2’ ,

xlabel=’My X Axis’, xbins=[0.,1.,2.], ylabel=’My Y Axis’, ybins=60, ymin=0., ymax=10. )

classmethod from_file(source_file, class_name=None, needs=[], instance_name=None, compile_notice=True, **config_kwargs)

Construct an event processor “in place” from the passed source file

Since Framework dynamically loads libraries containing processors after the python script has been fully run, we can compile a single-file processor into its own library that can then be loaded and run. This function puts the library next to the source file and only re-compiles if the source file’s last modified time is newer than the library (or the library does not exist).

Note

Developing processors in this way is incredible inefficient, especially since it does not allow for code to be well organized and split across many files nor does it allow for two processors to share common code. If you find yourself defining more than one class within your new C++ processor, it is highly recommended to transition your workflow to including your processor as a part of ldmx-sw so that it can fully benefit from a build system.

Parameters:

• source_file (str | Path) – path to source file to build into a processor (can be relative to where config is being run)

• class_name (str, default is name of source file) – name of C++ class that is the processor defaults to the name of the source file without an extension

• needs (list[str]) – Names of libraries that should be linked to the compiled processor in addition to ‘Framework’ which is linked be default. For example, one can gain access to the detector ID infrastructure with ‘DetDescr’.

• instance_name (str, default is class_name) – name to give to instance of this C++ processor

• compile_notice (bool, default is True) – print a notice when compilation is triggered

• config_kwargs (dict[str, Any]) – configuration parameters to give to the processor

Examples

A basic walkthrough is available online. https://ldmx-software.github.io/analysis/ldmx-sw.html

If MyAnalyzer.cxx contains the class MyAnalyzer, then we can put

p.sequence = [ ldmxcfg.Analyzer.from_file(‘MyAnalyzer.cxx’) ]

In our config script to run the analyzer on its own in the sequence. This default configuration only links the Framework library and so the analyzer would only be able to access the Framework and event objects. If you needed another library (for example, the ‘DetDescr’ library has the ID classes), one can also

p.sequence = [ ldmxcfg.Analyzer.from_file(‘MyAnalyzer.cxx’, needs = [‘DetDescr’]) ]

To inform the compiler that it should link your analyzer with the ‘DetDescr’ library. No removal of the library is done so if you change the needs or some other parameter to from_file you should also remove the library file (*.so) before attempting to re-run.

Returns:

built from the C++ source file and configured with the passed arguments

Return type:

EventProcessor

class LDMX.Framework.ldmxcfg.Logger

Bases: object

Configure the logging infrastructure of ldmx-sw

The “severity level” of messages correspond to the following integers.

• 0 : Debug

• 1 : Information

• 2 : Warning

• 3 : Error

• 4 : Fatal (reserved for program-ending exceptions)

Whenever a level is specified, messages for that level and any level above it (corresponding to a larger integer) are including when printing out the messages.

Paramters

termLevel: int

minimum severity level to print to the terminal

fileLevel: int

minimum severity level to print to the file

filePath: str

path to file to direct logging to (if not provided, don’t open a file for logging)

logRules: List[_LogRule]

list of custom logging rules that override the default terminal and file levels

custom(name, level)

Add a new custom logging rule to the logger

We automatically get the event processor’s instance name if an instance of an event processor is passed.

Parameters:

• name (str|EventProcessor) – identification of the logging channel to customize

• level (int) – level (and above) messages to print for that channel

debug(name)

drop the input channel to the debug level

silence(name)

raise the input channel to the error-only level

class LDMX.Framework.ldmxcfg.Process(passName)

Bases: object

Process configuration object

The python object that stores the necessary parameters for configuring a Process for ldmx-app to execute.

Upon construction, the class-wide reference lastProcess is set and the rest of the attributes are set to sensible defaults.

Parameters:

passName (str) – Short reference name for this run of the process

lastProcess

Class-wide reference to the last Process object to be constructed

Type:

Process

maxEvents

Maximum number events to process. If totalEvents is set, this will be ignored.

Type:

int

maxTriesPerEvent

Maximum number of attempts to make in a row before giving up on an event Only used in Production Mode (no input files) If totalEvents is set, this will be ignored.

Type:

int

totalEvents

Number of events we’d like to produce independetly of the number of tries it would take. Both maxEvents and maxTriesPerEvent will be ignored. Be warned about infinite loops!

Type:

int

run

Run number for this process

Type:

int

inputFiles

Input files to read in event data from and process

Type:

list of strings

outputFiles

Output files to write out event data to after processing

Type:

list of strings

sequence

List of event processors to pass the event bus objects to

Type:

list of Producers and Analyzers

keep

List of rules to keep or drop objects from the event bus

Type:

list of strings

libraries

List of libraries to load before attempting to build any processors

Type:

list of strings

skimDefaultIsKeep

Flag to say whether to process should by default keep the event or not

Type:

bool

skimRules

List of skimming rules for which processors the process should listen to when deciding whether to keep an event

Type:

list of strings

logFrequency

Print the event number whenever its modulus with this frequency is zero

Type:

int

logger

configuration for logging system in ldmx-sw

Type:

Logger

conditionsGlobalTag

Global tag for the current generation of conditions

Type:

str

conditionsObjectProviders

List of the sources of calibration and conditions information

Type:

list of ConditionsObjectProviders

randomNumberSeedService

conditions object that provides random number seeds in a deterministic way

Type:

RandomNumberSeedService

See also

Producer

one type of event processor

Analyzer

the other type of event processor

addLibrary()

Add a library to the list of dynamically loaded libraries

A process object must already have been created.

Parameters:

lib (str) – name of library to load

Warning

• Will exit the script if a process object hasn’t been defined yet.

Examples

addLibrary( ‘libSimCore.so’ )

addModule()

Add a module to the list of dynamically loaded libraries

A process object must already have been created.

Parameters:

module (str) – Name of module to load as a library

See also

Process.addLibrary

Examples

You can use this function to load a general module

addModule(‘SimCore’)

With the string substitutions that are made, you can refer to submodules with cmake, C++, or the library syntax. The following calls are all equivalent.

addModule(‘Ecal/Event’) addModule(‘Ecal::Event’) addModule(‘Ecal_Event’)

declareConditionsObjectProvider()

Declare a conditions object provider to be loaded with the process

A process object must already have been created.

Parameters:

cop (ConditionsObjectProvider) – provider to load with the process

Warning

• Will exit the script if a process object hasn’t been defined yet.

• Overrides an already declared COP with the passed COP if they are equal

inputDir(indir)

Scan the input directory and make a list of input root files to read from it

Lists all files ending in ‘.root’ in the input directory (not recursive). Extends the inputFiles list by these files.

Parameters:

indir (str) – Path to directory of event files to read in

lastProcess = None

parameterDump()

Recursively extract all configuration parameters for this process

Only includes objects somehow attached to the process.

pause()

Print this Process and wait for user confirmation to continue

Prints the process through the print function, and then waits for the user to press Enter to continue.

setCompression(algorithm, level=9)

set the compression settings for any output files in this process

We combine the compression settings here in the same way that ROOT does. This allows the compression settings to be passed along as one integer rather than two without any loss of generality.

Look at ROOT’s documentation for TFile to learn more about the different compression algorithms and levels available (as well as what integers to use). There is a summary table below.

Algorithm | int | root version ——————- | — | ———— ROOT global default | 0 | root-6.16 ZLIB | 1 | root-6.16 LZMA | 2 | root-6.16 Old (ROOT 5) | 3 | root-6.16 LZ4 | 4 | root-6.16 ZSTD | 5 | root-6.20

Level 0 : no compression is applied Level 9 : maximum amount of compression available from algorithm

Parameters:

• algorithm (int) – flag for the algorithm to use

• level (int) – flag for the level of compression to use

setConditionsGlobalTag(tag)

Set the global tag for all the ConditionsObjectProviders

Parameters:

tag (str) – Global generation tag to pass to all COPs

skimConsider(namePat)

Configure the process to listen to processors matching input.

The list of skim rules has a rather complicated form, so it is better to use this helper function.

Parameters:

namePat (str) – Pattern for the processor instanceNames to match for the Process to listen

Example

ecalVeto = ldmxcfg.Producer( ‘ecalVeto’ , ‘EcalVetoProcessor’ ) # Setup of other parameters for the veto p.skimConsider( ‘ecalVeto’ )

See also

skimConsiderLabelled

skimConsiderLabelled(namePat, labelPat)

Configure the process to listen to processors matching input.

The list of skim rules has a rather complicated form, so it is better to use this helper function.

Some uses of setStorageHint in processors include a “reason” for the given storage hint. The input label pattern is check on matching this “reason” for the storage hint.

Parameters:

• namePat (str) – Pattern for the processor instanceNames to match for the Process to listen

• labelPat (str) – Pattern for the storage hint reason to match for the Process to listen

See also

skimConsider

skimDefaultIsDrop()

Configure the process to by default drop (not save) every event.

skimDefaultIsSave()

Configure the process to by default keep every event.

class LDMX.Framework.ldmxcfg.Producer(instanceName, className, moduleName)

Bases: EventProcessor

A producer object.

This object contains the parameters that are necessary for a framework::Producer to be configured.

See also

LDMX.Framwork.ldmxcfg.EventProcessor

base class

class LDMX.Framework.ldmxcfg.RandomNumberSeedService

Bases: ConditionsObjectProvider

The random number seed service

This object registers the random number seed service with the process and gives some helper functions for configuration.

seedMode

Name of mode of getting random seeds

Type:

str

external(seed)

Input the master random number seed

Parameters:

seed (int) – Integer to use as master random number seed

run()

Base random number seeds off of the run number

time()

Set master random seed based off of time

Module contents