Logic tree module for openquake-hazard-risk calculators

------------------------------------------
What needs to be done
------------------------------------------
Implement a logic tree module allowing epistemic uncertainties definition in seismic hazard and risk models.

For each OpenQuake calculator, a user should be able to define multiple input
data (e.g. multiple PSHA source models, multiple PSHA source parameters, multiple GMPEs, multiple vulnerability models,.....),
each associated to a specific weight (to be interpreted as a probability, expressing the degree of belief on each input data set). For the different possible input data combinations, the user requested calculation must be performed and the results stored. Eventually, statistics on all the results produced must also be computed.

------------------------------------------
What is already existing
------------------------------------------

Currently, OpenQuake allows the definition of a logic tree for two hazard calculators (Classical, and Event Based). The definition of the input logic tree for the two calculators is actually decomposed into two sub-logic trees. The source model logic tree (which allows the definition of multiple PSHA source models and source model's parameters values), and the ground motion prediction equations (GMPEs) logic tree (which allow the definition of multiple GMPEs to be used in the calculation).
The source model and gmpe logic trees are provided as nrML files (references to these files are given in the SOURCE_MODEL_LOGIC_TREE_FILE and GMPE_LOGIC_TREE_FILE keys in the config.gem file).

- THE LOGIC TREE FILE DEFINITION

A logic tree schema definition exists in openquake/nrml/schema/nrml_seismic.xsd.
In the current schema the data model for a logic tree is defined by the logicTree element.
- A logicTree element is defined as a sequence of logicTreeBranchSet elements. It has an ID as required attribute and a tectonicRegionType as optional attribute.
- A logicTreeBranchSet is defined as a sequence of logicTreeBranch elements. It has two required attributes: branchingLevel and uncertaintyType. The branchingLevel represents the position of the branchSet inside the tree. The uncertaintyType is a string that can take one of the following values:
        - gmpeModel: identifies a branch set with branches that refer to GMPEs
        - sourceModel: identifies a branch set with branches that refer to PSHA source models
        - maxMagnitudeGutenbergRichterRelative: identifies a branch set with branches that refer to relative uncertainties on Gutenberg-Richter maximum magnitude
        - bValueGutenbergRichterRelative: identifies a branch set with branches that refer to relative uncertainties on Gutenberg-Richter b value
- A logicTreeBranch element is defined in terms of an uncertaintyModel and uncertaintyWeight elements.
The schema gives also the option to define multiple logicTree elements inside a logicTreeSet element.

In the current setting, a logic tree file (for both source model and GMPEs) contains the definition of a logicTreeSet element. The underlying assumption is that a source model logic tree file contains only one logic tree in the logicTreeSet element, while a GMPE logic tree file can contain one or more logicTree elements, each logic tree being associated to a particular tectonic region type (that's why the optional attribute 'tectonicRegionType' in the logicTree element has been defined.)

In the source model logic tree file it is currently assumed that the logicTree element must contain at least one branch set, and this branchSet should describe uncertainties in the source model (uncertaintyType='sourceModel'). In this branchSet, each logicTreeBranch contains a reference to a source model file in the uncertaintyModel element.
Example:
                <logicTreeBranchSet branchingLevel="1" uncertaintyType="sourceModel">

                    <logicTreeBranch>
                        <uncertaintyModel>source_model1.xml</uncertaintyModel>
                        <uncertaintyWeight>0.5</uncertaintyWeight>
                    </logicTreeBranch>

                    <logicTreeBranch>
                        <uncertaintyModel>source_model2.xml</uncertaintyModel>
                        <uncertaintyWeight>0.5</uncertaintyWeight>
                    </logicTreeBranch>

                </logicTreeBranchSet>

Subsequent branch sets can be defined and they can describe uncertainties of type 'maxMagnitudeGutenbergRichterRelative' and 'bValueGutenbergRichterRelative'. In both these two types of uncertainties the uncertaintyModel contains a double value which is interpreted as an increment to be added to the parameter the uncertaintyType is referring to (maxMagnitudeGutenbergRichterRelative refers to the Gutenberg-Richter maximum magnitude, bValueGutenbergRichterRelative refers to the Gutenberg-Richter b value).
Example:
                <logicTreeBranchSet branchingLevel="2" uncertaintyType="maxMagnitudeGutenbergRichterRelative">

                        <logicTreeBranch>
                            <uncertaintyModel>0.2</uncertaintyModel>
                            <uncertaintyWeight>0.2</uncertaintyWeight>
                        </logicTreeBranch>

                        <logicTreeBranch>
                            <uncertaintyModel>0.0</uncertaintyModel>
                            <uncertaintyWeight>0.6</uncertaintyWeight>
                        </logicTreeBranch>

                        <logicTreeBranch>
                            <uncertaintyModel>-0.2</uncertaintyModel>
                            <uncertaintyWeight>0.2</uncertaintyWeight>
                        </logicTreeBranch>

                </logicTreeBranchSet>

                <logicTreeBranchSet branchingLevel="3" uncertaintyType="bValueGutenbergRichterRelative">

                        <logicTreeBranch>
                            <uncertaintyModel>0.1</uncertaintyModel>
                            <uncertaintyWeight>0.2</uncertaintyWeight>
                        </logicTreeBranch>

                        <logicTreeBranch>
                            <uncertaintyModel>0.0</uncertaintyModel>
                            <uncertaintyWeight>0.6</uncertaintyWeight>
                        </logicTreeBranch>

                        <logicTreeBranch>
                            <uncertaintyModel>-0.1</uncertaintyModel>
                            <uncertaintyWeight>0.2</uncertaintyWeight>
                        </logicTreeBranch>

                </logicTreeBranchSet>

In the GMPE logic tree, one or more logicTree elements can be defined, each referring to a different tectonic region type. The current assumption is that each logicTree element can contain only one branchSet, and this branchSet should define uncertainties of type 'gmpeModel'.
Example:
    <logicTreeSet>

        <logicTree id="lt1" tectonicRegion="Active Shallow Crust">
            <logicTreeBranchSet branchingLevel="1" uncertaintyType="gmpeModel">
                <logicTreeBranch>
                    <uncertaintyModel>BA_2008_AttenRel</uncertaintyModel>
                    <uncertaintyWeight>0.5</uncertaintyWeight>
                </logicTreeBranch>
                <logicTreeBranch>
                    <uncertaintyModel>CB_2008_AttenRel</uncertaintyModel>
                    <uncertaintyWeight>0.5</uncertaintyWeight>
                </logicTreeBranch>
            </logicTreeBranchSet>
        </logicTree>

        <logicTree id="lt2" tectonicRegion="Stable Shallow Crust">
            <logicTreeBranchSet branchingLevel="1" uncertaintyType="gmpeModel">
                <logicTreeBranch>
                    <uncertaintyModel>CY_2008_AttenRel</uncertaintyModel>
                    <uncertaintyWeight>1.0</uncertaintyWeight>
                </logicTreeBranch>
            </logicTreeBranchSet>
        </logicTree>

    </logicTreeSet>

- THE LOGIC TREE OBJECT IMPLEMENTATION

The java/org/gem/engine/LogicTreeReader.java is responsible for reading logic tree data in nrML format. The LogicTreeReader returns (using the method read()), a Map<String, LogicTree>, where String is a string representation of an integer when reading a source model logic tree file (given that is assumed that there is only one logic tree, the string is always equal to '1'), while it's a string descriptive of a tectonic region type (as expressed by the simple type TectonicRegion defined in nrml_seismic.xsd, that is: 'Active Shallow Crust', 'Stable Shallow Crust','Subduction Interface','Subduction IntraSlab','Volcanic')

The LogicTree is implemented by the class java/org/gem/engine/logictree/LogicTree.java. The LogicTree class has two main private variables:
- Map<String, Element> ebMap : ebMap stands for end branch map. It was meant to store models (defined by the generic Element) associated to logic tree end-branches (that is models that are obtained after following all the tree paths, from the beginning to the end). The String represent the ID of an end-branch model.
- List<LogicTreeBranchingLevel> branchingLevels: this is a list of LogicTreeBranchingLevel objects meant to represent the different levels in the three.

A LogicTreeBranchingLevel (java/org/gem/engine/logictree/LogicTreeBranchingLevel.java) has the following private variables:
- ArrayList<LogicTreeBranch> treeBranchList: this a list of LogicTreeBranch objects each aiming at representing a logic tree branch
- int level: integer representing branching position inside the tree
- String branchingLabel: ID of the branching level
- int appliesTo: never used. In the original intention of the authors this param should have served to identify a logic tree branch to which the branching level is connected to.

A LogicTreeBranch (java/org/gem/engine/logictree/LogicTreeBranch.java) is described by the following variables:
 - int relativeID = ID of the logic tree branch
 - String branchingValue = string representing the uncertainty model
 - double weight = weight associated to the uncertainty model
 - String nameInputFile = variable used to represent uncertainty model in case it is defined as an external file
 - LogicTreeRule rule = object representing a logic tree epistemic uncertainties. A LogicTreeRule (java/org/gem/engine/logictree/LogicTreeRule.java) is defined by means of a LogicTreeRuleParam (java/org/gem/engine/logictree/LogicTreeRuleParam.java) which is an enum of predefined uncertainty types ('mMaxGRRelative','bGRRelative'), and a double value representing the weight associated to the uncertainty type. The object constructor allows to set only the relativeID, branchingValue, and the weight. The nameInputFile, and rule can be set using only public methods.

When reading a logic tree file, a LogicTreeBranchingLevel object is created for each logicTreeBranchSet element. For each logicTreeBranch in a logicTreeBranchSet element a LogicTreeBranch object is created, and the branchingValue is initialized with the value of the uncertaintyModel element, and the weigh is initialized with the value of the uncertaintyWeight element. In case of a source model logic tree file, if uncertaintyType="sourceModel" then nameInputFile is also set to contain the reference to the source model file, while if uncertaintyType="maxMagnitudeGutenbergRichterRelative" or uncertaintyType="bValueGutenbergRichterRelative", the LogicTreeRule rule variable is also set accordingly.

- THE LOGIC TREE PROCESSING

Currently, OpenQuake offers the possibility to process the information contained in a logic tree by performing a Monte Carlo sampling of both the source model and GMPE logic tree. 'Sampling a logic tree', means looping over the different branchSets defined in a tree, and for each branchSet, randomly selecting a branch with a probability equal to the branch weight.

The seed numbers for initializing the random number generator used to sample both the source model and GMPE logic trees are given in the configuration file (SOURCE_MODEL_LT_RANDOM_SEED and GMPE_LT_RANDOM_SEED). The actual processing is done by the java/org/gem/engine/LogicTreeProcessor.java class.
The number of models to be sampled is given by the NUMBER_OF_LOGIC_TREE_SAMPLES key.

In both the ClassicalMixin and EventBaseMixin (openquake/hazard/opensha.py) two main methods are called in order to sample and store in memory the source model and GMPEs needed for the subsequent calculation:
 - store_source_model: which calls the method sampleAndSaveERFTree from LogicTreeProcessor
- store_gmpe_map: which calls the method sampleAndSaveGMPETree from LogicTreeProcessor

When performing a Classical hazard calculation, hazard curves are calculated on the sites of interest for all the NUMBER_OF_LOGIC_TREE_SAMPLES generated. Mean and quantile hazard curves for each site can then be calculated from the full set of hazard curves computed. When performing a Classical Hazard + Risk calculation the mean hazard curves are passed to the risk engine to perform the risk analysis.

When performing a Even Based hazard calculation, ground motion fields are computed for all the NUMBER_OF_LOGIC_TREE_SAMPLES generated. When performing a Event Based Classical + Risk calculation, all the ground motion fields computed are passed to the risk engine with a corresponding time span equal to INVESTIGATION_TIME * NUMBER_OF_LOGIC_TREE_SAMPLES * NUMBER_OF_SEISMICITY_HISTORIES.

-------------------------------------------------------
Limitations of the current implementation
-------------------------------------------------------
- Complete lack of test coverage
- Unclear and inconsistent implementation of the LogicTree object. The logic tree package comes mostly from a GEM1 implementation, and has been badly adapted to accommodate some post-gem1 requirements.
- Difficult to extend in order to model more complex logic tree structures
- Java based, difficult to be used for Risk logic tree definition

--------------------------------------------------------------------
The need for a new OpenQuake logic tree module
--------------------------------------------------------------------
The new OpenQuake logic tree module should serve for the definition of logic trees for the hazard and risk engines. A python implementation is therefore required.

However, given that for now the need for using a logic tree is only for the hazard engine, the present blueprint describes only the definition and processing of logic tree utilized in the input for hazard calculations (Classical PSHA, Event Based, Disaggregation and UHS). The deterministic calculator does not currently requires a logic tree definition.

A new set of requirements has been identified, and a prototype showing the new requirements/ example files and algorithms for logic tree processing has been developed (https://github.com/monellid/logictree). The prototype is in Java but is meant for requirement explanation only. The prototype includes also tests aiming at validating the correctness of the logic tree processing.

- NEW SCHEMA FOR LOGIC TREE DEFINITION

A new schema accommodating more complex logic tree definition has been developed (https://github.com/monellid/logicTree/blob/master/docs/schema/nrml_seismic.xsd).
According to the new schema:

- a LogicTree is defined as a sequence of LogicTreeBranchingLevel elements. The position in the sequence specifies in which level of the tree the branching level is located. That is, the first LogicTreeBranchingLevel element in the sequence represents the first level in the tree, the second element the second level in the tree, and so on.

- a LogicTreeBranchingLevel is defined as a sequence of LogicTreeBranchSet elements. Each LogicTreeBranchSet defines a particular epistemic uncertainty inside a branching level (that is a set of input data/parameter values whose weights sum to 1).

- a LogicTreeBranchSet is defined as a sequence of LogicTreeBranch elements. A branch set has two required attributes (ID and uncertaintyType (defining the type of epistemic uncertainty the branch set is defining)). Optional attributes are:
           - applyToBranches: to be used to specify to which LogicTreeBranch elements (one or more), in the previous branching level, the branch set is linked to. The default is the keyword ALL, which means that a branch set is by default linked to all branches in the previous branching level.
           - applyToSources: it can be used in the Source Model Logic Tree definition, it allows to specify to which source in a source model the uncertainty applies to.
           - applyToSourceType: it can be used in the Source Model Logic Tree definition, it allows to specify to which source type (area, point, simple fault, complex fault) the uncertainty applies to.
            - applyToTectonicRegionType: it can be used in both the Source Model and GMPE Logic Tree definition, it allows to specify to which tectonic region type (Active Shallow Crust, Stable Shallow Crust, etc.) the uncertainty applies to.

The set of uncertaintyTypes has been extended and now considers:
- gmpeModel
- sourceModel
- maxMagGRRelative
- bGRRelative
- abGRAbsolute
- maxMagGRAbsolute

- a LogicTreeBranch is defined by the uncertainityModel element (a string identifying an uncertainty model; the content of the string varies with the uncertaintyType attribute value of the branchSet element) and the uncertaintyWeight element (specifying the probability associated to the uncertaintyModel).

if uncertaintyType == gmpeModel
then the uncertaintyModel element is expected to contain the class name of a GMPE implemented in the java/org/opensha/sha/imr/attenRelImpl package (e.g. BA_2008_AttenRel, CB_2008_AttenRel,....)

if uncertaintyType == sourceModel
then the uncertaintyModel element is expected to contain the path to a source model file (e.g. /home/damiano/source_model.xml)

if uncertaintyType == maxMagGRRelative
then the uncertaintyModel element is expected to contain one double value, that is interpreted as an increment to be added to the Gutenberg-Richeter (GR) maximum magnitude of seismic sources in the source model (keeping total moment rate constant).

if uncertaintyType == bGRRelative
then the uncertaintyModel element is expected to contain one double value, that is interpreted as an increment to be added to the GR b values of seismic sources in the source model (keeping total moment rate constant).

if uncertaintyType == abGRAbsolute
then the uncertaintyModel element is expected to contain one or more pairs of double values, each pair defining the GR a and b values used to substitute the GR a and b values of seismic source in the source model.

if uncertaintyType == maxMagGRAbsolute
then the uncertaintyModel element is expected to contain one or more double values, each value defining the GR maximum magnitude used to substitute the GR maximum magnitude of seismic sources in the source model.

The optional attributes in the LogicTreeBranchSet element specify to which sources the uncertainties must be applied:

- if applyToSources==ALL, then the uncertainty applies to all sources in the source model

- if applyToSources== ID1, ID2, ..., then the uncertainty applies only to sources with id equals to ID1, ID2

- if applyToSourceType==area, or fault,..., then the uncertainty applies only to sources which belong to a specific typology (area, or fault, ...).

- if applyToTectonicRegionType==Active Shallow Crust, or Subduction Interface,...., then the uncertainty applies only to sources belonging to a specific tectonic region type.

Examples of logic tree files according to the new schema can be found here (for source model: https://github.com/monellid/logicTree/blob/master/symmetric-logic-tree-source-model.xml and https://github.com/monellid/logicTree/blob/master/non-symmetric-logic-tree-source-model.xml, for gmpe logic tree: https://github.com/monellid/logicTree/blob/master/logic-tree-gmpe.xml)

- NEW LOGIC TREE OBJECT IMPLEMENTATION

To accommodate the new schema definition a logic tree is implemented by using a generic tree structure (https://github.com/monellid/logicTree/blob/master/src/tree/Tree.java) which basically extends the concept of a binary tree. In other words a logic tree is represented as a single rootElement which points to a List<Node<T>> of children. There is no restriction on the number of children that a particular node may have. A Node is just a container that contains data and a reference to a list of children.

A new version of the parser making use of the tree representation can be found here: https://github.com/monellid/logicTree/blob/master/src/parser/LogicTreeParser.java

- THE LOGIC TREE PROCESSING

With the new logic tree implementation, a new key LOGIC_TREE_PROCESSING_MODE must be defined. This key defines the way the logic tree must be processed.
Two options must be offered:

- MONTE CARLO SAMPLING: random sampling of the logic tree paths
- ENUMERATION: enumeration of all possible logic tree paths

if MONTE CARLO SAMPLING is chosen then NUMBER_OF_LOGIC_TREE_SAMPLES, and a new key (LOGIC_TREE_RANDOM_SEED, substituting the two keys SOURCE_MODEL_LT_RANDOM_SEED, and GMPE_LT_RANDOM_SEED) must be also defined.

For Classical PSHA/Disaggregation/UHS calculation:

- if MONTE CARLO SAMPLING is chosen, NUMBER_OF_LOGIC_TREE_SAMPLES hazard curves/disaggregation histograms/uhs' are calculated for each site. (Arithmetic) Mean and quantile hazard curves/histograms/uhs' are calculated for each site. If a classical hazard + risk calculation is requested, the mean hazard curves are passed to the risk engine.
- if ENUMERATION is chosen, a number of hazard curves/disaggregation histograms/uhs' equal to the number of enumerated logic tree paths is computed for each site. (Weighted) Mean and quantile hazard curves/disaggregation histograms/uhs' are calculated for each site. If a classical hazard + risk calculation is requested, the mean hazard curves are passed to the risk engine.

For Event Based calculation only MONTE CARLO SAMPLING is supported:

- in this case ground motion fields are calculated for ruptures in a number of stochastic event sets equal to NUMBER_OF_LOGIC_TREE_SAMPLES * NUMBER_OF_SEISMICITY_HISTORIES. If a hazard+risk calculation is requested, the full set of ground motion fields is passed to the risk engine, with an associated time span equal to INVESTIGATION_TIME * NUMBER_OF_LOGIC_TREE_SAMPLES * NUMBER_OF_SEISMICITY_HISTORIES.

 Examples of algorithms for the logic tree processing are given in: https://github.com/monellid/logicTree/blob/master/src/utils/LogicTreeUtils.java

The method sampleLogicTreePaths allows randomly sampling a tree object. This can be used if MONTE CARLO SAMPLING is chosen.

To enumerate all the possible logic tree paths, the method computeAllLogicTreePaths can be used. This method can be used if ENUMERATION is chosen.

Only one seed number is needed, because with the proposed tree object implementation, two trees can be easily joined together (see joinTrees method), and therefore only one seed number can be used for sampling the tree.

- PARSING THE SOURCE MODEL LOGIC TREE

When parsing the source model logic tree, the following checks must be performed:

- the logic tree must contain at least one branching level. Empty logic trees are not allowed.
- the first branching level can contain only one branch set. This branch set must define uncertainties in the source model (that is uncertaintyType==sourceModel).
- in the first branching level, the attributes: applyToSources, applyToSourceType, applyToTectonicRegionType, and correlation should not be defined (because they are not of use)
- subsequent branching levels can define uncertainties of type:
     - maxMagGRRelative
     - bGRRelative
     - abGRAbsolute
     - maxMagGRAbsolute
but NOT gmpeModel or sourceModel
- in all the branching levels (except the first), ONLY ONE optional attribute (applyToSources, applyToSourceType, applyToTectonicRegionType) can be defined.
- if in a branching level, a branch set has applyToBranches=ALL, then this branch set must be unique in the branching level. In other words, only one branch set with applyToBranches=ALL is allowed per branching level.
- if in a branching level, more than one branch sets are defined, the attribute applyToBranches must contain one or more branch IDs referring to branches that are only in the previous branching level and that are associated to leaf nodes, that is nodes that do not have already children.
- if in a branching level, more than one branch sets are defined, the attributes applyToBranches, of the two branch sets, must contain different sets of branch IDs (In other words, there cannot be two branch sets that links to the same branch)
- In all branch sets, branch weights must sum to 1.

- PARSING THE GMPE LOGIC TREE

When parsing the GMPE logic tree, the following checks must be performed:
- the logic tree must contain at least one branching level. Empty logic trees are not allowed.
- only one branch set can be defined for branching level.
- all branch sets must define uncertainties of type gmpeModel (uncertaintyType == gmpeModel). Other types of uncertainties are not allowed.
- all branch sets must define the applyToTectonicRegionType attribute. This is the only attribute allowed.
- in a logic tree, each branch set must refer to a different tectonic region type (In other words, is not possible to have two or more branch sets with applyToTectonicRegionType==to the same tectonic region type). This means that the maximum number of branching levels in a GMPE logic tree is equal to the number of currently supported tectonic region types.
- In all branch sets, branch weights must sum to 1.

- CONSISTENCY CHECK BETWEEN SOURCE MODEL AND GMPE LOGIC TREE

To check the consistency between the source model and GMPE logic trees, an extra check must be performed. The tectonic region types defined in the source models in the first branching level of the source model logic tree, must be defined also in the GMPE logic tree. In other words, if the source models in the source model logic tree define sources belonging to ACTIVE SHALLOW CRUST and SUBDUCTION INTERFACE, then the GMPE logic tree must contain branch sets for ACTIVE SHALLOW CRUST and SUBDUCTION INTERFACE. If there is not consistency between the tectonic region types defined in the two logic trees, an error should be thrown.

After the above checks are performed, the two logic tree can be joined, and logic tree paths can be selected according to the methodology chosen by the user.

- PARSING A LOGIC TREE PATH

A logic tree path can be defined as a sequence of logic tree branches. The processing of a path can be structured as follows:

1) read source model as defined in the first branch of the tree path

2) if present, apply uncertainties to source model.

  ------  if uncertaintyType == maxMagGRRelative ------

               loop over sources defined by the applyToSources/SourceType/TectonicRegionType attribute

                          For each source:

                           compute Total Moment Rate (TMR) for the current GR mfd using the following formula:

                                TMR = (10^(ai + 16.1) / (1.5 - b)) * ( 10^(1.5 - b)*Mmax - 10^(1.5 - b)*Mmin ), where ai = a + Log10(b)
                                a = GR a cumulative value
                                b = GR b value
                                Mmin = GR minimum magnitude
                                Mmax = GR maximum magnitude

                            update Mmax with Mmax + deltaMmax

                            recompute GR a value as:

                                a = Log10( (TMR * (1.5 - b)) / (10^(1.5 - b)*Mmax - 10^(1.5 - b)*Mmin) ) - 16.1 - Log10(b)

                             update GR mfd parameters with the updated values of Mmax and a.

------ if uncertaintyType == bGRRelative ------

               loop over sources defined by the applyToSources/SourceType/TectonicRegionType attribute

                          For each source:

                           compute Total Moment Rate (TMR) for the current GR mfd using the following formula:

                                TMR = (10^(ai + 16.1) / (1.5 - b)) * ( 10^(1.5 - b)*Mmax - 10^(1.5 - b)*Mmin ), where ai = a + Log10(b)
                                a = GR a cumulative value
                                b = GR b value
                                Mmin = GR minimum magnitude
                                Mmax = GR maximum magnitude

                            update b with b + deltab

                            recompute GR a value as:

                                a = Log10( (TMR * (1.5 - b)) / (10^(1.5 - b)*Mmax - 10^(1.5 - b)*Mmin) ) - 16.1 - Log10(b)

                             update GR mfd parameters with the updated values of b and a.

------ if uncertaintyType == abGRAbsolute ------

               loop over sources defined by the applyToSources/SourceType/TectonicRegionType attribute

                          For each source:

                         substitute the current a and b values with the new a and b values

------ if uncertaintyType == maxMagGRAbsolute ------

               loop over sources defined by the applyToSources/SourceType/TectonicRegionType attribute

                          For each source:

                         substitute the current Mmax values with the new Mmax values

After all the parameters uncertainties have been applied, a new source model is created that can be then used as input for calculation.

3) Remaining branches defines GMPEs per tectonic region types. Define map tectonic region type <--> GMPE that can then be used for calculation.