theory package

Submodules

theory.analysis module

class EManalysis[source]

Bases: smodels.theory.printer.Printer

Class to store a efficiency map-type of analysis. Stores the basic analysis info and contains a method for obtaining the efficiency maps from the database.

Variables:
  • label – Analysis label/name
  • sqrts – Analysis center-of-mass energy
  • lum – Analysis luminosity
getEfficiencyFor(element)[source]

Get efficiency for element from the database. Returns zero if a efficiency is not found.

Warning

not implemented yet

Returns:efficiency value (float). zero, if element is not found
getLimitFor()[source]

Get experimental limit for a cross-section.

Warning

not implemented yet

Returns:experimental upper limit for cross-section (float with unit or Unum object)
class ULanalysis[source]

Bases: smodels.theory.printer.Printer

Class to store one upper limit-type analysis. Stores the conditions and the elements constrained by the analysis as well as basic analysis info.

Variables:
  • conditions – List of conditions strings
  • constraint – Constraint string
  • elementsEff – Dictionary with constrained elements as keys and efficiencies as values
  • label – Analysis label/name
  • sqrts – Analysis center-of-mass energy
  • lum – Analysis luminosity
formatData(outputLevel)[source]

Select data preparation method through dynamic binding.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...
getBranchCondition()[source]

Most analyses include assumptions about the masses of the elements appearing in their constraints. This method returns a string describing this condition

Returns:string describing branch condition (from the branchcondition field) or None if no condition is found
getEfficiencyFor(element)[source]

Get (trivial) efficiency for element. Returns zero if element is not constrained by the analysis or the element multiplicative factor if it is.

Returns:1 if element is in constraint, zero otherwise
getUpperLimitFor(mass)[source]

Get the experimental upper limit for a specific mass array.

Parameters:mass – mass vector for computing the upper limit
Returns:experimental upper limit for cross-section times BR (float with unit or Unum object)

theory.auxiliaryFunctions module

cGtr(weightA, weightB)[source]

Define the auxiliary greater function.

Return a number between 0 and 1 depending on how much it is violated (0 = A > B, 1 = A << B).

Returns:XSectioList object with the values for each label.
cSim(*weights)[source]

Define the auxiliar similar function.

Return the maximum relative difference between any element weights of the list, normalized to [0,1].

Returns:XSectionList object with the values for each label.
distance(xmass1, xmass2)[source]

Define distance between two mass positions in upper limit space. The distance is defined as d = 2*|xmass1-xmass2|/(xmass1+xmass2).

Parameters:
  • xmass1 – upper limit value (in fb) for the mass1
  • xmass2 – upper limit value (in fb) for the mass2
Returns:

relative mass distance in upper limit space

massAvg(massList, method='weighted', weights=None)[source]

Compute the average mass of massList according to method.

If method=weighted but weights were not properly defined, switch method to harmonic. If massList contains a zero mass, switch method to mean.

Parameters:
  • method – possible values: harmonic, mean, weighted
  • weights – weights of elements (only for weighted average)
massPosition(*args)[source]

Give mass position in upper limit space. Use the analysis experimental limit data.

theory.branch module

class Branch(info=None)[source]

Bases: object

An instance of this class represents a branch. A branch-element can be constructed from a string (e.g., (‘[b,b],[W]’).

Variables:
  • masses – list of masses for the intermediate states
  • particles – list of particles (strings) for the final states
  • momID – PDG id for the primary (intermediate state) mother
  • daughterID – PDG id for the last intermediate state
  • maxWeight – weight of the branch (XSection object)
copy()[source]

Generate an independent copy of self. Faster than deepcopy.

Returns:Branch object
decayDaughter(brDictionary, massDictionary)[source]

Generate a list of all new branches generated by the 1-step cascade decay of the current branch daughter.

Parameters:
  • brDictionary – dictionary with the decay information for all intermediate states (values are br objects, see pyslha)
  • massDictionary – dictionary containing the masses for all intermediate states.
Returns:

list of extended branches (Branch objects). Empty list if daughter is stable or if daughterID was not defined.

getLength()[source]

Returns the branch length (= number of R-odd masses).

Returns:length of branch (number of cascade decay steps)
isEqual(other, useDict=True)[source]

Compares two branches. If particles are similar and masses are equal, return True. Otherwise, return False.

Parameters:
  • other – branch to be compared (Branch object)
  • useDict – if True, allow for inclusive particle labels
Returns:

True if branches are equal (particles and masses match); False otherwise.

decayBranches(branchList, brDictionary, massDictionary, sigcut=0.00E+00 [fb])[source]

Decay all branches from branchList until all unstable intermediate states have decayed.

Parameters:
  • branchList – list of Branch() objects containing the initial mothers
  • brDictionary – dictionary with the decay information for all intermediate states (values are br objects, see pyslha)
  • massDictionary – dictionary containing the masses for all intermediate states.
  • sigcut – minimum sigma*BR to be generated, by default sigcut = 0. (all branches are kept)
Returns:

list of branches (Branch objects)

theory.clusterTools module

class ElementCluster[source]

Bases: object

An instance of this class represents a cluster. This class is used to store the relevant information about a cluster of elements and to manipulate this information.

Variables:elements – list of elements in the cluster (Element objects)
getAvgMass()[source]

Return the average mass of all elements belonging to the cluster.

Returns:average mass array
getTotalXSec()[source]

Return the sum over the cross-sections of all elements belonging to the cluster.

Returns:sum of weights of all the elements in the cluster (XSectionList object)
class IndexCluster(massMap=None, posMap=None, wMap=None, indices=set([]), analysis=None)[source]

Bases: object

An instance of this class represents a cluster storing element indices. This auxiliary class is used to store element indices and positions in upper limit space. It is only used by the clustering algorithm.

Variables:
  • indices – list of integers mapping the cluster elements to their position in the list (1st element -> index 0, 2nd element -> index 1,...)
  • avgPosition – position in upper limit space for the cluster average mass
  • massMap – dictionary with indices as keys and the corresponding element mass as values
  • positionMap – dictionary with indices as keys and the corresponding element position in upper limit space as values
  • weightMap – dictionary with indices as keys and the corresponding element weight as values
  • analysis – analysis to which the cluster applies (ULanalysis object)
add(iels)[source]

Add an index or a list of indices to the list of indices and update the avgPosition value.

copy()[source]

Returns a copy of the index cluster (faster than deepcopy).

remove(iels)[source]

Remove an index or a list of indices to the list of indices and update the avgPosition value.

clusterElements(elements, analysis, maxDist)[source]

Cluster the original elements according to their mass distance.

Parameters:
  • elements – list of elements (Element objects)
  • analysis – analysis to be considered (must be a ULanalysis object)
Returns:

list of clusters (ElementCluster objects)

groupAll(elements)[source]

Create a single cluster containing all the elements.

theory.crossSection module

class XSection[source]

Bases: object

An instance of this class represents a cross-section.

This class is used to store the information of a single cross-section (value, paritcle ids, center of mass, order and label).

order = 0 (LO), 1 (NLO) or 2 (NLL).

copy()[source]

Generates an independent copy of self.

Faster than deepcopy.

niceStr()[source]

Generates a more human readable string. The string format is: Sqrts: self.info.sqrts, Weight: self.value

class XSectionInfo[source]

Bases: object

An instance of this class represents information regarding a cross-section.

This class is used to store information of a cross-section (center of mass, order and label).

copy()[source]

Generate an independent copy of self.

Faster than deepcopy.

class XSectionList(infoList=None)[source]

Bases: object

An instance of this class represents a list of cross-sections.

This class is used to store a list of cross-sections.

add(newxsec)[source]

Append a XSection object to the list.

combineWith(newXsecs)[source]

Add a new list of cross-sections.

If the new cross-sections already appear (have same order and sqrts), add its value to the original value, otherwise append it to the list. The particle IDs are ignored when adding cross-sections. Hence, they are set to (None, None) if any cross-sections are combined.

copy()[source]

Generates an independent copy of itself. Faster than deepcopy.

delete(xSec)[source]

Delete the cross-section entry from the list.

getDictionary(groupBy='pids')[source]

Convert the list of XSection objects to a nested dictionary.

First level keys are the particles IDs (if groupBy == pids) or labels (if groupBy == labels) and values are the cross-section labels or particle IDs and the cross-section value.

getInfo()[source]

Get basic info about the cross-sections appearing in the list (order, value and label).

Returns:list of XSectionInfo objects
getMaxXsec()[source]

Get the maximum cross-section value appearing in the list.

getMinXsec()[source]

Get minimum cross-section value appearing in the list.

getPIDpairs()[source]

Get all particle ID pairs appearing in the list.

getPIDs()[source]

Get all particle IDs appearing in the list.

getXsecsFor(item)[source]

Return a list of XSection objects for item (label, pid, sqrts).

niceStr()[source]
order()[source]

Order the cross-section in the list by their PDG pairs

removeLowerOrder()[source]

Keep only the highest order cross-section for each process in the list.

Remove order information and set default labels.

getXsecFromLHEFile(lhefile, addEvents=True)[source]

Obtain cross-sections from input LHE file.

Parameters:
  • lhefile – LHE input file with unweighted MC events
  • addEvents – if True, add cross-sections with the same mothers, otherwise return the event weight for each pair of mothers
Returns:

a XSectionList object

getXsecFromSLHAFile(slhafile, useXSecs=None, xsecUnit=1.00E+00 [pb])[source]

Obtain cross-sections for pair production of R-odd particles from input SLHA file. The default unit for cross-section is pb.

Parameters:
  • slhafile – SLHA input file with cross-sections
  • useXSecs – if defined enables the user to select cross-sections to use. Must be a XSecInfoList object
  • xsecUnit – cross-section unit in the input file (must be a Unum unit)
Returns:

a XSectionList object

theory.element module

class Element(info=None)[source]

Bases: smodels.theory.printer.Printer

An instance of this class represents an element. This class possesses a pair of branches and the element weight (cross-section * BR).

Variables:
  • branches – list of branches (Branch objects)
  • weight – element weight (cross-section * BR)
  • motherElements – only for elements generated from a parent element by mass compression, invisible compression,etc. Holds a pair of (whence, mother element), where whence describes what process generated the element
checkConsistency()[source]

Check if the particles defined in the element exist and are consistent with the element info.

Returns:True if the element is consistent. Print error message and exits otherwise.
combineMotherElements(el2)[source]

Combine mother elements from self and el2 into self

Parameters:el2 – element (Element Object)
compressElement(doCompress, doInvisible, minmassgap)[source]

Keep compressing the original element and the derived ones till they can be compressed no more.

Parameters:
  • doCompress – if True, perform mass compression
  • doInvisible – if True, perform invisible compression
  • minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap, perform mass compression)
Returns:

list with the compressed elements (Element objects)

copy()[source]

Create a copy of self. Faster than deepcopy.

Returns:copy of element (Element object)
formatData(outputLevel)[source]

Select data preparation method through dynamic binding.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...
getDaughters()[source]

Get a pair of daughter IDs (PDGs of the last intermediate state appearing the cascade decay). Can be None, if the element does not have a definite daughter.

Returns:list of PDG ids
getEinfo()[source]

Get topology info from particle string.

Returns:dictionary containing vertices and number of final states information
getMasses()[source]

Get the array of masses in the element.

Returns:list of masses (mass array)
getMothers()[source]

Get a pair of mother IDs (PDG ids of the primary mother intermediate state). Can be None, if the element does not have a definite mother.

Returns:list of PDG ids
getParticles()[source]

Get the array of particles in the element.

Returns:list of particle strings
hasTopInList(elementList)[source]

Check if the element topology matches any of the topologies in the element list.

Parameters:elementList – list of elements (Element objects)
Returns:True, if element topology has a match in the list, False otherwise.
invisibleCompress()[source]

Perform invisible compression.

Returns:compressed copy of the element, if element ends with invisible particles; None, if compression is not possible
isEqual(other, order=False, useDict=True)[source]

Compare two Elements for equality.

Parameters:
  • other – element to be compared (Element object)
  • order – if False, test both branch orderings.
  • useDict – if True, allow for inclusive particle labels.
Returns:

True, if all masses and particles are equal; False, else;

isInList(listOfElements, igmass=False, useDict=True)[source]

Check if the element is present in the element list.

:parameter If igmass == False also check if the analysis has the element mass array.

massCompress(minmassgap)[source]

Perform mass compression.

Parameters:minmassgap – value (in GeV) of the maximum mass difference for compression (if mass difference < minmassgap -> perform mass compression)
Returns:compressed copy of the element, if two masses in this element are degenerate; None, if compression is not possible;
particlesMatch(other, order=False, useDict=True)[source]

Compare two Elements for matching particles.

Parameters:
  • other – element to be compared (Element object)
  • order – if False, test both branch orderings.
  • useDict – if True, allow for inclusive particle labels.
Returns:

True, if particles match; False, else;

setMasses(mass, sameOrder=True, opposOrder=False)[source]

Set the element masses to the input mass array.

Parameters:
  • mass – list of masses ([[masses for branch1],[masses for branch2]])
  • sameOrder – if True, set the masses to the same branch ordering If True and opposOrder=True, set the masses to the smaller of the two orderings.
  • opposOrder – if True, set the masses to the opposite branch ordering. If True and sameOrder=True, set the masses to the smaller of the two orderings.
switchBranches()[source]

Switch branches, if the element contains a pair of them.

Returns:element with switched branches (Element object)

theory.lheDecomposer module

decompose(lhefile, inputXsecs=None, nevts=None, doCompress=False, doInvisible=False, minmassgap=-1.00E+00 [GeV])[source]

Perform LHE-based decomposition.

Parameters:
  • lhefile – LHE file with e.g. pythia events
  • inputXsecs – xSectionList object with cross-sections for the mothers appearing in the LHE file. If None, use information from file.
  • nevts – (maximum) number of events used in the decomposition. If None, all events from file are processed.
  • doCompress – mass compression option (True/False)
  • doInvisible – invisible compression option (True/False)
  • minmassgap – minimum mass gap for mass compression (only used if doCompress=True)
Returns:

list of topologies (TopologyList object)

elementFromEvent(event, weight=None)[source]

Creates an element from a LHE event and the corresponding event weight.

Parameters:
  • event – LHE event
  • weight – event weight. Must be a XSectionList object (usually with a single entry) or None if not specified.
Returns:

element

theory.lheReader module

class LheReader(filename, nmax=None)[source]

Bases: object

An instance of this class represents a reader for LHE files.

close()[source]

Close the lhe file, if open.

event()[source]

Get next event.

Returns:SmsEvent; None if no event is left to be read.
next()[source]

Get next element in iteration.

Needed for the iterator.

class Particle[source]

Bases: object

An instance of this class represents a particle.

class SmsEvent(eventnr=None)[source]

Bases: object

Event class featuring a list of particles and some convenience functions.

add(particle)[source]

Add particle to the event.

getMom()[source]

Return the pdgs of the mothers, None if a problem occurs.

metaInfo(key)[source]

Return the meta information of ‘key’, None if info does not exist.

theory.particleNames module

elementsInStr(instring)[source]

Parse instring and return a list of elements appearing in instring.

instring can also be a list of strings.

Returns:list of elements appearing in instring in string format
getName(pdg)[source]

Convert pdg number to particle name according to the dictionaries rOdd and rEven.

Returns:particle name (e.g. gluino, mu-, ...)
getPdg(name)[source]

Convert a name to the pdg number according to the dictionaries rOdd and rEven.

Returns:particle pdg; None, if name could not be resolved
simParticles(ptype1, ptype2, useDict=True)[source]

Compares 2 particle names or 2 nested name arrays. Allows for dictionary labels (Ex: L = l, l+ = l, l = l-,...). For the last nested level ignore particle ordering.

Parameters:
  • ptype1 – first (nested) list of particle names, e.g. [‘l’,’jet’]
  • ptype2 – second (nested) list of particle names
  • useDict – use the translation dictionary, i.e. allow e to stand for e+ or e-, l+ to stand for e+ or mu+, etc
Returns:

boolean

vertInStr(instring)[source]

Parses instring (or a list of strings) and returns the list of particle vertices appearing in instring.

theory.printer module

class Printer[source]

Bases: object

Printer class for defining specific print options and format for objects.

formatData(outputLevel)[source]

Format data of the derived object.

Has to be implemented in the derived object. The real implementation is selected through dynamic binding.

Raises:NotImplementedError
formatElementData(outputLevel)[source]

Format data of to print an element object.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
formatMissingData(outputLevel)[source]

Format data of missing topology list.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
formatResultsData(outputLevel)[source]

Format data of the final output object.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
formatStatusData(outputLevel)[source]

Format data of the output status object.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
formatTheoryPredictionData(outputLevel)[source]

Format data of a TheoryPrediction object.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
formatTopologyListData(outputLevel)[source]

Format data of to print Global topologies object.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
formatULanalysisData(outputLevel)[source]

Format data for a ULanalysis object.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
printout(target='stdout', filename='', outputLevel=1)[source]

Print the content of the data structure to the target.

Parameters:
  • target – The target to print to. Possible values: stdout, file. Default: stdout.
  • filename – Filename to which the output is written
  • outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...)
Returns:

None

theory.slhaDecomposer module

decompose(slhafile, sigcut=1.00E-01 [fb], doCompress=False, doInvisible=False, minmassgap=-1.00E+00 [GeV], useXSecs=None)[source]

Perform SLHA-based decomposition.

Parameters:
  • sigcut – minimum sigma*BR to be generated, by default sigcut = 0.1 fb
  • doCompress – turn mass compression on/off
  • doInvisible – turn invisible compression on/off
  • minmassgap – maximum value (in GeV) for considering two R-odd particles degenerate (only revelant for doCompress=True )
  • useXSecs – optionally a dictionary with cross-sections for pair production, by default reading the cross sections from the SLHA file.
Returns:

list of topologies (TopologyList object)

theory.theoryPrediction module

class TheoryPrediction[source]

Bases: object

An instance of this class represents the results of the theory prediction for an analysis.

Variables:
  • analysis – holds the analysis (ULanalysis or EManalysis object) to which the prediction refers to
  • value – value of the theory prediction (relevant cross-section to be compared with the experimental limits). It is a XSection object.
  • conditions – list of values for the analysis conditions (only for upper limit-type analysis, e.g. analysis=ULanalysis)
  • mass – mass of the cluster to which the theory prediction refers to (only for upper limit-type analysis, e.g. analysis=ULanalysis)
getmaxCondition()[source]

Returns the maximum value from the list conditions

Returns:maximum condition value (float)
class TheoryPredictionList(theoryPredictions)[source]

Bases: smodels.theory.printer.Printer

An instance of this class represents a collection of theory prediction objects.

Variables:_theoryPredictions – list of TheoryPrediction objects
formatData(outputLevel)[source]

Select data preparation method through dynamic binding.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...
theoryPredictionFor(analysis, smsTopList, maxMassDist=0.2)[source]

Compute theory predictions for the given analysis, using the list of elements in smsTopList. Collect elements and efficiencies, combine the masses (if needed) and compute the conditions (if existing).

Parameters:
  • analysis – analysis to be considered (ULanalysis or EManalysis object)
  • smsTopList – list of topologies containing elements (TopologyList object)
  • maxMassDist – maximum mass distance for clustering elements (float)
Returns:

list of TheoryPrediction objects

theory.topology module

class Topology(elements=None)[source]

Bases: object

An instance of this class represents a topology.

Variables:
  • vertnumb – list with number of vertices in each branch
  • verparts – list with number of final states in each branch
  • elementList – list of Element objects with this common topology
addElement(newelement)[source]

Add an Element object to the elementList.

For all the pre-existing elements, which match the new element, add weight. If no pre-existing elements match the new one, add it to the list. When comparing elements, try both branch orderings.

Parameters:newelement – element to be added (Element object)
Returns:True, if the element was added. False, otherwise
checkConsistency()[source]

Check if the all the elements in elementList are consistent with the topology (same number of vertices and final states)

Returns:True if all the elements are consistent. Print error message and exits otherwise.
describe()[source]

Create a detailed description of the topology.

Returns:list of strings with a description of the topology
getElements()[source]

Get list of elements of the topology.

Returns:elementList (list of Element objects)
getTotalWeight()[source]

Return the sum of all elements weights.

Returns:sum of weights of all elements (XSection object)
isEqual(other, order=False)[source]

Compare two topologies. Two topologies are equal if they have the same number of vertices and final states (in each vertex).

Parameters:
  • other – topology to be compared (Topology object)
  • order – if False, compare the two possible branch orderings. If True, compare the two topologies assuming the same branch ordering.
Returns:

True, if both topologies equal; False, otherwise

class TopologyList(topologies=[])[source]

Bases: smodels.theory.printer.Printer

An instance of this class represents an iterable collection of topologies.

Variables:topos – list of topologies (Topology objects)
add(newTopology)[source]

Check if elements in newTopology matches an entry in self.topos.

If it does, add weight. If the same topology exists, but not the same element, add element. If neither element nor topology exist, add the new topology and all its elements.

addList(topoList)[source]

Adds topologies in topoList using the add method.

describe()[source]

Returns string with basic information about the topology list.

formatData(outputLevel)[source]

Select data preparation method through dynamic binding.

Parameters:outputLevel – general control for the output depth to be printed (0 = no output, 1 = basic output, 2 = detailed output,...
getElements()[source]

Return a list with all the elements in all the topologies.

getTotalWeight()[source]

Return the sum of all topologies total weights.

Module contents