# 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_

- THE LOGIC TREE FILE DEFINITION

A logic tree schema definition exists in openquake/

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

- maxMagnitudeGut

- bValueGutenberg

- 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 'tectonicRegion

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 (uncertaintyTyp

Example:

Subsequent branch sets can be defined and they can describe uncertainties of type 'maxMagnitudeGu

Example:

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=

<logicTree id="lt2" tectonicRegion=

</logicTreeSet>

- THE LOGIC TREE OBJECT IMPLEMENTATION

The java/org/

The LogicTree is implemented by the class java/org/

- 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<LogicTreeB

A LogicTreeBranch

- ArrayList<

- 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/

- 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/

When reading a logic tree file, a LogicTreeBranch

- 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_

The number of models to be sampled is given by the NUMBER_

In both the ClassicalMixin and EventBaseMixin (openquake/

- store_source_model: which calls the method sampleAndSaveER

- store_gmpe_map: which calls the method sampleAndSaveGM

When performing a Classical hazard calculation, hazard curves are calculated on the sites of interest for all the NUMBER_

When performing a Even Based hazard calculation, ground motion fields are computed for all the NUMBER_

-------

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:/

- NEW SCHEMA FOR LOGIC TREE DEFINITION

A new schema accommodating more complex logic tree definition has been developed (https:/

According to the new schema:

- a LogicTree is defined as a sequence of LogicTreeBranch

- a LogicTreeBranch

- 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.

- applyToTectonic

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/

if uncertaintyType == sourceModel

then the uncertaintyModel element is expected to contain the path to a source model file (e.g. /home/damiano/

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=

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

- if applyToSourceTy

- if applyToTectonic

Examples of logic tree files according to the new schema can be found here (for source model: https:/

- NEW LOGIC TREE OBJECT IMPLEMENTATION

To accommodate the new schema definition a logic tree is implemented by using a generic tree structure (https:/

A new version of the parser making use of the tree representation can be found here: https:/

- THE LOGIC TREE PROCESSING

With the new logic tree implementation, a new key LOGIC_TREE_

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_

For Classical PSHA/Disaggrega

- if MONTE CARLO SAMPLING is chosen, NUMBER_

- if ENUMERATION is chosen, a number of hazard curves/

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_

Examples of algorithms for the logic tree processing are given in: https:/

The method sampleLogicTree

To enumerate all the possible logic tree paths, the method computeAllLogic

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

- in the first branching level, the attributes: applyToSources, applyToSourceType, applyToTectonic

- 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, applyToTectonic

- if in a branching level, a branch set has applyToBranches

- 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 applyToTectonic

- 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 applyToTectonic

- 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/

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

loop over sources defined by the applyToSources/

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

loop over sources defined by the applyToSources/

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

loop over sources defined by the applyToSources/

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.

## Blueprint information

- Status:
- Started

- Approver:
- John Tarter

- Priority:
- Medium

- Drafter:
- None

- Direction:
- Needs approval

- Assignee:
- None

- Definition:
- Approved

- Series goal:
- None

- Implementation:
- Good progress

- Milestone target:
- 0.4.5

- Started by
- John Tarter

- Completed by

### Related branches

### Related bugs

### Sprints

### Whiteboard

This looks like a very comprehensive and flexible logic tree analysis tool. For the options where the user can specify an increment to characterise the uncertainty in maxMag or bGR, then should this attribute be defined in the source model seismic schema (i.e. as the uncertainty on maxMag or b value respectively)?

The idea is to define the increments in the uncertaintyModel field, in the logic tree file. So that people can try with different values without changing the source model file.

The 1st 60% of the logic tree application was done in 0.4.4. The balance of the work is slated for completion in 0.4.5.