smodels 3.0.0__tar.gz → 3.0.2__tar.gz

{smodels-3.0.0/smodels.egg-info → smodels-3.0.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: smodels
-Version: 3.0.0
+Version: 3.0.2
 Summary: A tool for interpreting simplified-model results from the LHC
 Home-page: http://smodels.github.io/
-Author: The SModelS collaboration, smodels-users@lists.oeaw.ac.at Current members: Mohammad Mahdi Altakach, Sabine Kraml, Andre Lessa, Sahana Narashima, Timothee Pascal, Camila Ramos, Humberto Reyes-Gonzalez, Yoxara Villamizar, Wolfgang Waltenberger  Previously involved in SModelS: Gael Alguero, Federico Ambrogi, Juhi Dutta, Jan Heisig, Charanjit K. Khosa, Suchita Kulkarni, Ursula Laa, Veronika Magerl, Wolfgang Magerl, Philipp Neuhuber, Doris Proschofsky, Jory Sonneveld, Michael Traub, Matthias Wolf, Alicia Wongel
+Author: The SModelS collaboration, smodels-users@lists.oeaw.ac.at Current members: Mohammad Mahdi Altakach, Sabine Kraml, Andre Lessa, Sahana Narashima, Timothee Pascal, Camila Ramos, Humberto Reyes-Gonzalez, Theo Reymermier, Yoxara Villamizar, Wolfgang Waltenberger  Previously involved in SModelS: Gael Alguero, Federico Ambrogi, Juhi Dutta, Jan Heisig, Charanjit K. Khosa, Suchita Kulkarni, Ursula Laa, Veronika Magerl, Wolfgang Magerl, Philipp Neuhuber, Doris Proschofsky, Jory Sonneveld, Michael Traub, Matthias Wolf, Alicia Wongel
 Author-email: smodels-developers@lists.oeaw.ac.at 
 License: GPLv3
 Keywords: simplified models LHC BSM theories interpretation supersymmetry UEDs

{smodels-3.0.0 → smodels-3.0.2}/smodels/base/runtime.py

@@ -10,10 +10,13 @@
 
 """
 
+from typing import Union
+
 ## place to keep the pointer to the model file (default = mssm)
 modelFile="smodels.share.models.mssm"
 
-_experimental = False ## turn on experimental features
+_experimental = { "truncatedgaussians": False,
+                  "spey": False } ## experimental features
 
 _deltas_rel_default = .2 ## the default relative error on the signal strength
 
@@ -51,11 +54,16 @@ def filetype ( filename ):
     return None
 
 
-def experimentalFeatures():
-    """ a simple boolean flag to turn experimental features on/off,
+def experimentalFeature( feature : str ) -> Union[None,bool]:
+    """ method to check if a certain experimental feature is enabled.
     can be turned on and off via options:experimental in parameters.ini.
+    :param feature: ask for feature
+    
+    :returns: None if feature does not exist, else boolean
     """
-    return _experimental
+    if not feature in _experimental:
+        return None
+    return _experimental[feature]
 
 def nCPUs():
     """ obtain the number of *available* CPU cores on the machine, for several

{smodels-3.0.0 → smodels-3.0.2}/smodels/etc/parameters_default.ini

@@ -9,7 +9,6 @@ combineSRs = False
 model=share.models.mssm
 promptWidth = 1e-11
 stableWidth = 1e-25
-ignorePromptQNumbers = spin,eCharge,colordim
 [parameters]
 sigmacut = 0.005
 minmassgap = 5

{smodels-3.0.0 → smodels-3.0.2}/smodels/experiment/databaseObj.py

@@ -58,7 +58,7 @@ def _getSHA1(filename):
 
 # some mechanism to remove lock files if the download got interrupted
 import atexit
-lockfiles = set() 
+lockfiles = set()
 
 def removeLockFiles( lockfiles ):
     """ remove cruft lockfiles """
@@ -73,13 +73,13 @@ def removeLockFiles( lockfiles ):
 atexit.register ( removeLockFiles, lockfiles )
 
 class Database(object):
-    """ 
+    """
     Database object. Holds a list of SubDatabases and the ExpSMS map.
     Delegates all calls to SubDatabases.
     """
 
     def __init__(self, base=None, force_load=None,
-                 progressbar=False, subpickle=True, 
+                 progressbar=False, subpickle=True,
                  combinationsmatrix=None):
         """
         :param base: path to the database, or pickle file (string), or http
@@ -99,17 +99,15 @@ class Database(object):
                      optionally specifying signal regions, e.g. { "anaid1:SR1":
                      ( "anaid2:SR2", "anaid3" ) }
         """
-        
         self.subs = []
-        
         if "_fastlim" in base:  # for backwards compatibility
             base = base.replace("_fastlim", "+fastlim")
         sstrings = base.split("+")
         for ss in sstrings:
             self.subs.append(SubDatabase(ss, force_load,
-                                         progressbar, subpickle, 
+                                         progressbar, subpickle,
                                          combinationsmatrix))
-        
+
 
         # Compute SMS dict with all results
         self._allExpSMSDict = ExpSMSDict(self.expResultList)
@@ -120,7 +118,7 @@ class Database(object):
     @property
     def expResultList(self):
         """
-        The combined list of results, compiled from the 
+        The combined list of results, compiled from the
         the active results in each subdatabase.
         """
 
@@ -235,11 +233,11 @@ class Database(object):
         Select (filter) the results within the database satisfying the restrictions set by the arguments and returns the corresponding results.
         """
 
-        self.selectExpResults(analysisIDs=analysisIDs, datasetIDs=datasetIDs, 
-                             txnames=txnames, dataTypes=dataTypes, 
+        self.selectExpResults(analysisIDs=analysisIDs, datasetIDs=datasetIDs,
+                             txnames=txnames, dataTypes=dataTypes,
                              useNonValidated=useNonValidated,
                              onlyWithExpected=onlyWithExpected)
-        
+
         return self.expResultList[:]
 
     def selectExpResults(self, analysisIDs=['all'], datasetIDs=['all'], txnames=['all'],
@@ -420,8 +418,8 @@ class SubDatabase(object):
             self._setParticles()
             self.txt_meta.printFastlimBanner()
             return
-        logger.error("when initialising database: force_load=%s is not "
-                     "recognized. Valid values are: pcl, txt, None." % force_load)
+        logger.error( f"when initialising database: force_load={force_load} is not "
+                     "recognized. Valid values are: pcl, txt, None." )
         raise SModelSError()
 
     def __eq__(self, other):
@@ -462,16 +460,21 @@ class SubDatabase(object):
             it needs update, create new binary file, in
             case it does need an update.
         """
-        if not os.path.exists(self.pcl_meta.pathname):
-            logger.info("Creating binary database ")
-            logger.info("(this may take a few minutes, but it's done only once!)")
-            self.loadTextDatabase()
-            self.createBinaryFile()
-        else:
-            if self.needsUpdate():
+        try:
+            if not os.path.exists(self.pcl_meta.pathname):
+                logger.info("Creating binary database ")
+                logger.info("(this may take a few minutes, but it's done only once!)")
+                self.loadTextDatabase()
                 self.createBinaryFile()
             else:
-                self.loadBinaryFile(lastm_only=False)
+                if self.needsUpdate():
+                    self.createBinaryFile()
+                else:
+                    self.loadBinaryFile(lastm_only=False)
+        except Exception as e:
+            import traceback
+            logger.error ( "when loading database: {e}, {traceback.format_exc()}" )
+            sys.exit(-1)
 
     def loadTextDatabase(self):
         """ simply loads the textdabase """
@@ -557,7 +560,7 @@ class SubDatabase(object):
                     t1 = time.time()-t0
                     logger.info("Loaded database from %s in %.1f secs." %
                             (self.pcl_meta.pathname, t1))
-                    self.databaseParticles = None                    
+                    self.databaseParticles = None
                     try:
                         self.databaseParticles = serializer.load(f)
                     except EOFError as e:
@@ -669,7 +672,7 @@ class SubDatabase(object):
     def lockFile ( self, filename : os.PathLike ):
         """ lock the file <filename>
         """
-        lockfile = os.path.join ( os.path.dirname ( filename ), 
+        lockfile = os.path.join ( os.path.dirname ( filename ),
                                   ".lock_"+ os.path.basename ( filename ) )
         ctr = 0
         while ( ctr < 5 ):
@@ -700,7 +703,7 @@ class SubDatabase(object):
     def unlockFile ( self, filename : os.PathLike ):
         """ unlock the file <filename>
         """
-        lockfile = os.path.join ( os.path.dirname ( filename ), 
+        lockfile = os.path.join ( os.path.dirname ( filename ),
                                   ".lock_"+ os.path.basename ( filename ) )
         if lockfile in lockfiles:
             lockfiles.remove( lockfile )
@@ -1079,7 +1082,7 @@ class SubDatabase(object):
         """
 
         self._activeResults = self.getExpResults(analysisIDs, datasetIDs, txnames,
-                                                dataTypes, useNonValidated, 
+                                                dataTypes, useNonValidated,
                                                 onlyWithExpected)
 
     def getExpResults(self, analysisIDs=['all'], datasetIDs=['all'], txnames=['all'],

{smodels-3.0.0 → smodels-3.0.2}/smodels/experiment/infoObj.py

@@ -45,7 +45,7 @@ class Info(object):
             for i, tag in enumerate(tags):
                 if not tag:
                     continue
-                if tag.startswith("# "):  # a comment!
+                if tag.startswith("#"):  # a comment!
                     continue
                 line = content[i]
                 value = line.split(':', 1)[1].strip()

smodels-3.0.2/smodels/matching/clusterTools.py

@@ -0,0 +1,476 @@
+"""
+.. module:: clusterTools
+   :synopsis: Module holding the SMSCluster class and cluster methods used to combine similar SMS according
+      to the analysis.
+
+.. moduleauthor:: Andre Lessa <lessa.a.p@gmail.com>
+
+"""
+
+from smodels.base.particleNode import ParticleNode
+from smodels.base.particle import MultiParticle
+from smodels.base.physicsUnits import fb
+from smodels.decomposition.theorySMS import TheorySMS
+from smodels.experiment.datasetObj import DataSet, CombinedDataSet
+from smodels.matching.exceptions import SModelSMatcherError as SModelSError
+from smodels.matching.matcherAuxiliaryFuncs import average
+from smodels.base.smodelsLogging import logger
+import numpy as np
+
+
+
+class AverageSMS(TheorySMS):
+    """
+    Represents an SMS or list of SMS containing only
+    the basic attributes required for clustering or computing efficiencies/upper limits.
+    Its properties are given by the average properties of the SMS
+    it represents and its weight is given by the total weight of
+    all SMS.
+    """
+
+    def __init__(self, smsList=[]):
+        if any(not isinstance(sms, TheorySMS) for sms in smsList):
+            raise SModelSError("An AverageSMS must be created from a list of TheorySMS objects.")
+
+        TheorySMS.__init__(self)
+
+        # Get the relevant properties needed by the txnames
+        # (in addition to mass, totalwidth and isSM)
+        attrList = ['mass', 'totalwidth', 'isSM']
+        for sms in smsList:
+            dataMap = sms.txname.dataMap
+            attrList += [attr for _, attr,_ in dataMap.values()]
+        attrList = list(set(attrList))
+
+        # Define base SMS to copy (common) global properties from
+        smsBase = smsList[0]
+
+        #  Define relevant properties to be stored and averaged over:
+        self.properties = attrList
+        self.txname = smsBase.txname
+        #If the average corresponds to a single SMS, we
+        # can directly use its upperLimit value (if defined).
+        if (len(smsList) == 1) and hasattr(smsBase,'_upperLimit'):
+            self._upperLimit = smsBase._upperLimit
+
+        #  Consistency checks:
+        if any(sms.canonName != smsBase.canonName for sms in smsList):
+            logger.error("Can not build average SMS from SMS with distinct topologies.")
+            raise SModelSError()
+        if any(sms.txname != self.txname for sms in smsList):
+            logger.error("Can not build average SMS from SMS for distinct txnames.")
+            raise SModelSError()
+
+
+        # Create new node objects holding particles
+        # with the average attributes
+        avgNodesDict = {}
+        if len(smsList) == 1:
+            avgNodesDict = {n : node for n,node in zip(smsBase.nodeIndices,smsBase.nodes)}
+        else:
+            weights = [sms.weight.asNumber(fb) for sms in smsList]
+            for nodeIndex in smsBase.nodeIndices:
+                if nodeIndex == smsBase.rootIndex:
+                    # For the root node make a dummy copy:
+                    avgNode = smsBase.indexToNode(nodeIndex).copy()
+                else:
+                    # For all the other nodes compute the average
+                    allParticles = [sms.indexToNode(nodeIndex).particle for sms in smsList]
+                    attrDict = {}
+                    for attr in self.properties:
+                        values = [getattr(ptc, attr) for ptc in allParticles]
+                        avgAttr = average(values, weights, nround=5)
+                        attrDict[attr] = avgAttr
+                    mp = allParticles[0]
+                    for ptc in allParticles[1:]:
+                        mp = mp + ptc
+                    if isinstance(mp,MultiParticle):
+                        avgParticle = MultiParticle(particles=mp.particles,
+                                                attributesDict=attrDict)
+                    else:
+                        avgParticle = MultiParticle(particles=[mp],
+                                                attributesDict=attrDict)
+                    avgNode = ParticleNode(particle=avgParticle)
+                avgNodesDict[nodeIndex] = avgNode
+
+        # Copy the tree structure from smsBase,
+        # but replacing the node objects by the average nodes
+        self.copyTreeFrom(smsBase,nodesObjDict=avgNodesDict)
+        # Compute the weight
+        self.weight = smsBase.weight
+        for sms in smsList[1:]:
+            self.weight = self.weight + sms.weight
+
+    def __eq__(self, other):
+        """
+        Compares the SMS with other. Only the properties
+        defined in self.properties are used for comparison.
+        :param other:  SMS to be compared (SMS object)
+        :return: True/False.
+        """
+
+        if not isinstance(other, TheorySMS):
+            return False
+        
+        if self.canonName != other.canonName:
+            return False
+
+        for nodeIndex in self.nodeIndices:
+            nodeA = self.indexToNode(nodeIndex)
+            nodeB = other.indexToNode(nodeIndex)
+            if nodeA.isSM and nodeB.isSM:
+                continue
+            for attr in self.properties:
+                attrA = getattr(nodeA,attr)
+                attrB = getattr(nodeB,attr)
+                if attrA != attrB:
+                    return False
+        return True
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+class SMSCluster(object):
+    """
+    An instance of this class represents a cluster of SMS,
+    which holds the averageSMS.
+    This class is used to store the relevant information about a cluster of
+    SMS and to manipulate this information.
+    """
+
+    def __init__(self, smsList=[], dataset=None):
+
+        self.smsList = smsList[:]
+        self.dataset = dataset
+        # Compute average SMS
+        self.averageSMS = self.computeAverageSMS()
+        
+    def __str__(self):
+        return str(self.averageSMS)
+
+    def __repr__(self):
+        return str(self.averageSMS)
+
+    def getTotalXSec(self):
+        """
+        Return the sum over the cross sections of all SMS belonging to
+        the cluster.
+
+        :returns: sum of weights of all the SMS in the cluster (XSectionList object)
+        """
+        totxsec = 0.0*fb
+        for sms in self.smsList:
+            totxsec += sms.weight
+        return totxsec
+
+    def computeAverageSMS(self):
+        """
+        Computes the average SMS for the cluster.
+        The average SMS has generic ParticleNodes
+        with the attributes set to the average values of self.smsList.
+        It can only be defined if all SMS share the same canonical name
+        and the same txname. Otherwise, returns None
+
+        :return: AverageSMS object or None (if it can not be defined)
+        """
+
+        # Check if an average SMS can be defined:
+        cName = self.smsList[0].canonName
+        tx = self.smsList[0].txname
+        if any(sms.canonName != cName for sms in self.smsList):
+            avgSMS = None
+        elif any(sms.txname != tx for sms in self.smsList):
+            avgSMS = None
+        else:
+            # Define the average SMS with the required properties averaged over:
+            avgSMS = AverageSMS(self.smsList[:])
+
+        # If the averageSMS can be defined, 
+        # compute the averageSMS upper limit 
+        if avgSMS is not None and self.dataset is not None:
+            ul = self.dataset.getUpperLimitFor(avgSMS,txnames=tx)
+            avgSMS._upperLimit = ul
+
+        return avgSMS
+    
+    def distanceTo(self,sms):
+        """
+        Defines the relative distance between the cluster
+        and SMS object or another cluster.
+        The distance is computed using the upper limits for
+        the averageSMS (for cluster objects) or the SMS upper limit.
+        The distance is defined as d = 2*|ul1-ul2|/(ul1+ul2).
+
+        :parameter sms: SMS object or SMSCluster object
+
+        :returns: relative distance
+        """
+
+        sms1 = self.averageSMS
+
+        if isinstance(sms,SMSCluster):
+            sms2 = sms.averageSMS
+        else:
+            sms2 = sms
+
+        if not hasattr(sms2, '_upperLimit'):
+            sms2._upperLimit = self.dataset.getUpperLimitFor(sms2,
+                                                    txnames=sms2.txname)
+
+        ul1 = sms1._upperLimit
+        ul2 = sms2._upperLimit
+
+        if ul1 is None or ul2 is None:
+            return None
+        if (ul1+ul2).asNumber(fb) == 0.:
+            return 0.
+        ulDistance = 2.*abs(ul1 - ul2)/(ul1 + ul2)
+
+        return ulDistance
+
+    def isValid(self,maxDist):
+        """
+        Checks if the SMSCluster is a valid cluster,
+        i.e. if its AverageSMS has a well defined UL
+        and the distance between any SMS in the cluster
+        and the cluster AverageSMS  is smaller than maxDist.
+
+        :param dataset: Dataset object used to check the UL
+        :parameter maxDist: maximum distance between the averageSMS and
+                            all the SMS in the cluster
+
+        :return: True/False 
+        """
+
+        if self.averageSMS is None:
+            return False
+        if self.averageSMS._upperLimit is None:
+            return False
+      
+        # Compute distances between averageSMS and SMS in cluster
+        dists = [self.distanceTo(sms) for sms in self.smsList]
+        
+        # Check if any distance could not be computed:
+        if any(d is None for d in dists):
+            return False
+        
+        # Compute maximal distance between averageSMS and SMS
+        dist = max(dists,default=0.0)
+        if dist > maxDist:
+            return False
+        
+        return True
+
+
+
+def clusterSMS(smsList, maxDist, dataset):
+    """
+    Cluster the original SMS according to their distance in upper limit space.
+
+    :parameter smsList: list of sms (TheorySMS objects)
+    :parameter dataset: Dataset object to be used when computing distances in upper limit space
+    :parameter maxDist: maximum distance for clustering two SMS
+
+    :returns: list of clusters (SMSCluster objects)
+    """
+    if len(smsList) == 0:
+        return []
+
+    if any(not isinstance(sms, TheorySMS) for sms in smsList):
+        raise SModelSError("Asked to cluster non TheorySMS objects")
+    if not isinstance(dataset, (DataSet, CombinedDataSet)):
+        raise SModelSError("A dataset object must be defined for clustering")
+
+    # Make sure only unique SMS are clustered together (avoids double counting weights)
+    # Sort SMS, so the ones with highest contribution (weight) come first:
+    smsList = sorted(smsList, key=lambda sms: sms.weight, reverse=True)
+
+    # Remove duplicated SMS:
+    smsUnique = []
+    for sms in smsList:
+        # Skip the SMS if it is related to any another SMS in the list
+        if any(sms.isRelatedTo(smsB) for smsB in smsUnique):
+            continue
+        smsUnique.append(sms)
+
+    # Get txname list only with the txnames from unique SMS used for clustering
+    txnames = list(set([sms.txname for sms in smsUnique]))
+    if dataset.getType() == 'upperLimit' and len(txnames) != 1:
+        logger.error("Clustering SMS with different Txnames for an UL result.")
+        raise SModelSError()
+
+    if dataset.getType() == 'upperLimit':  # Group according to upper limit values
+        clusters = doCluster(smsUnique, dataset, maxDist)
+    elif dataset.getType() == 'efficiencyMap':  # Group all SMS together
+        cluster = SMSCluster(smsUnique)
+        clusters = [cluster]
+
+    for cluster in clusters:
+        cluster.txnames = txnames
+    return clusters
+
+
+def doCluster(smsList, dataset, maxDist):
+    """
+    Cluster algorithm to cluster SMS using a modified minimal spanning tree method.
+
+    :parameter smsList: list of all SMS to be clustered
+    :parameter dataset: Dataset object to be used when computing distances in upper limit space
+    :parameter maxDist: maximum distance for clustering two SMS
+
+    :returns: a list of SMSCluster objects containing the SMS
+              belonging to the cluster
+    """
+
+
+    #  First make sure all SMS contain their upper limits
+    for sms in smsList:
+        if not hasattr(sms, '._upperLimit'):
+            sms._upperLimit = dataset.getUpperLimitFor(sms, txnames=sms.txname)
+        if sms._upperLimit is None:
+            raise SModelSError("Trying to cluster SMS (id = %i, txname = %s) outside the grid for dataset %s." 
+                                %(sms.smsID,sms.txname,dataset.longStr()))
+
+    # Sort SMS by upperLimit 
+    sortedSMSList = sorted(smsList, key = lambda sms: sms._upperLimit)
+
+    # Cluster all identical SMS into clusters
+    clusterList = groupSMS(sortedSMSList,dataset)
+
+    # Sort clusters by proximity in upperLimit 
+    clusterList = sorted(clusterList, 
+                         key=lambda cluster: cluster.averageSMS._upperLimit)
+
+    # Compute the distance matrix for the clusters:
+    # (diagonal entries are set to None)
+    dMatrix = np.full((len(clusterList),len(clusterList)),fill_value=None)
+    for iA,clusterA in enumerate(clusterList):
+        for iB,clusterB in enumerate(clusterList):
+            if iA >= iB: continue
+            dMatrix[iA,iB] = clusterA.distanceTo(clusterB)
+            dMatrix[iB,iA] = dMatrix[iA,iB] # the matrix is symmetric
+    
+    # Check minimal distance between two distinct clusters
+    # (set default to 2*maxDist in case len(clusterList) == 1, i.e. dMatrix is empty)
+    minDist = min([d for d in dMatrix.flatten() if d is not None], 
+                  default=2*maxDist)
+    # Merge closest cluster up to the point when
+    # no more merges are possible (all clusters have distances larger than maxDist)
+    while (len(clusterList) > 1) and (minDist < maxDist):
+        # Get indices of first pair of clusters with minimum distance
+        mergeIndices = np.argwhere(dMatrix == minDist)[0]
+        # Merge clusters with indices in mergeIndices
+        newCluster = mergeClusters(np.take(clusterList,mergeIndices))
+        # If new cluster is valid (averageSMS is close to the cluster's SMS),
+        # replace the two orignal clusters by it. 
+        if newCluster.isValid(maxDist):
+            # Update cluster list:
+            # Remove cluster with largest index
+            # and replace cluster with smallest index by new cluster
+            delete_index = max(mergeIndices)
+            replace_index = min(mergeIndices)
+            clusterList.pop(delete_index)
+            clusterList[replace_index] = newCluster 
+            # Remove row and column for cluster with largest index
+            dMatrix = np.delete(dMatrix,delete_index,0)
+            dMatrix = np.delete(dMatrix,delete_index,1)
+            # Compute the distances between the new cluster and all the
+            # other ones.
+            # Recompute distances using the new cluster:
+            for iA,clusterA in enumerate(clusterList):
+                if iA >= replace_index: continue
+                dMatrix[iA,replace_index] = clusterA.distanceTo(newCluster)
+                dMatrix[replace_index,iA] = dMatrix[iA,replace_index] # the matrix is symmetric
+        
+        # Otherwise keep the original clusters, but set 
+        # their distance above maxDist, so they will no longer be allowed to merge
+        else:
+            dMatrix[mergeIndices] = 2*maxDist
+            dMatrix[np.flip(mergeIndices)] = 2*maxDist
+
+
+        minDist = min([d for d in dMatrix.flatten() if d is not None], 
+                  default=2*maxDist)
+        
+
+    # Finally sort clusters by total xsection and length
+    clusters = sorted(clusterList, 
+                      key = lambda c: (c.getTotalXSec(),len(c.smsList)),
+                      reverse=True)
+
+    return clusters
+
+
+def groupSMS(smsList,dataset):
+    """
+    Group SMS into clusters where the average SMS is
+    identical to all the SMS in cluster.
+    Each cluster contains all SMS which share the same mass,width and upper limit
+    and can be replaced by their average SMS.
+
+    :parameter smsList: list of all SMS to be grouped
+
+    :returns: a list of SMSCluster objects
+              which represents a group of SMS with same mass, width and upper limit.
+    """
+
+    # Group SMS if they have the same UL
+    # and give the same average SMS (same BSM attributes)
+    smsClusterList = []
+    nonClusteredSMS = smsList[:]
+    while nonClusteredSMS:
+        smsA = nonClusteredSMS.pop(0)
+        smsCluster = SMSCluster([smsA],dataset=dataset)
+        # Keep track of the SMS which could not
+        # be clustered with smsA to use in the next iteration
+        notClustered = []
+        while nonClusteredSMS:
+            smsB = nonClusteredSMS.pop(0)
+            # If it can not be clustered with smsA, add to notClustered list
+            if (smsA._upperLimit != smsB._upperLimit) or (smsCluster.averageSMS != smsB):
+                notClustered.append(smsB)
+                continue
+            smsCluster.smsList.append(smsB)
+            smsCluster.averageSMS.weight += smsB.weight
+        
+        smsClusterList.append(smsCluster)
+        nonClusteredSMS = notClustered[:]
+
+    # Make sure each SMS belongs to a cluster:
+    nclustered = sum([len(c.smsList) for c in smsClusterList])
+    nsms = len(smsList)
+    if nclustered != nsms:
+        raise SModelSError(f"Error grouping SMS. {nclustered}/{nsms} SMS were clustered")
+    
+    return smsClusterList
+
+def mergeClusters(clusterList,useAverage=False):
+    """
+    Merge a list of SMSCluster objects using
+    the averageSMS of each cluster if useAverage is True.
+    Otherwise cluster the list of all SMS from all clusters.
+
+    :param clusterList: List of SMSCluster objects
+    :param useAverage: True/False. If True, 
+                       will cluster the averageSMS in each cluster.
+    """
+        
+    if len(clusterList) == 0:
+        return None
+    
+    smsList = []
+    for cluster in clusterList:
+        smsList += cluster.smsList[:]
+        
+    if not useAverage:
+        newCluster = SMSCluster(smsList,
+                                clusterList[0].dataset)
+    else:
+        avgSMSList = [cluster.averageSMS 
+                   for cluster in clusterList]
+        newCluster = SMSCluster(avgSMSList,
+                                clusterList[0].dataset)
+        # Make sure the cluster SMS list contains the original SMS
+        newCluster.smsList = smsList[:]
+
+    return newCluster