Doc/nshm model relational.md

docs/domain_model/hazard_realisation_model.md

@@ -0,0 +1,37 @@
+???+ warning "Nov 2023 - this is model under active revision !!"
+
+## Introduction
+
+These are databases of related hazard curves each associated with a specific combination of Sources and GMMs.
+
+
+## Seismic Hazard Model diagram
+
+
+
+```mermaid
+classDiagram
+direction LR
+
+class HazardModelRealisation {
+    vs30s() integer
+    LocationList() string[]
+    IMTList() string[]
+    hazardCurve(vs30, IMT, Location)
+}
+
+class HazardCurveResult {
+    vs30() string
+    Location() string
+    IMT() string
+    curves() float[]
+}
+
+SeismicHazardModel -- "0..*" HazardModelRealisation
+HazardModelRealisation -- "0..*" HazardCurveResult
+```
+
+???+ "Accessing the NSHM hazard realisations" 
+
+    The NZ NSHM project makes Hazard Model Realisations available via a graphql web API. There is also a python client library that wraps the web API and also allows the user to cache results locally for better performance in many situations.
+

docs/domain_model/index.md

@@ -0,0 +1,11 @@
+# NSHM Domain Model
+
+Diagrams depicting the Conceptual model of the NSHM project including  both behavior and data. See also [Wikipedia](https://en.wikipedia.org/wiki/Domain_model).
+
+We use UML Class modelling techniques to explaing the Information used within the NZ NSHM ecosystem. Our diagrams use Mermaid, whcih makes them diagram-as-code
+
+## Table of contents
+
+ - [Seismic Hazard Model](./seismic_hazard_model.md)
+ - [Hazard Realisations](./hazard_realisation_model.md)
+ - [Misc](./relational.md) working stuff 

docs/domain_model/relational.md

@@ -0,0 +1,115 @@
+# NZSHM-Model relationships
+
+This is parked, it contains some developmental diagrams used to infotm the wider class modelling.
+
+## Toshi Hazard objects (Task + Solution + Config)
+
+```mermaid
+classDiagram
+
+    %% direction LR
+    class OpenquakeHazardSolution {
+        <<Node>>
+        String id: 
+        String produced_by:
+        config
+        template
+        File hazard_solution_csv_archive
+        File hazard_solution_hdf5_archive
+
+    }
+
+    class OpenquakeHazardTask {
+        <<Node>>
+        String id: 
+        node hazard_solution
+        model_type
+        logic_tree_permutations
+        intensity_spec
+        vs30
+        String[] location_list
+        node template_archive
+        hazard_config
+        source_models
+    }
+
+    class OpenquakeHazardConfig {
+        <<Node>>
+        Node[] source_models 
+        template_archive
+    }
+
+    OpenquakeHazardTask "*" -- "1" OpenquakeHazardConfig
+    OpenquakeHazardTask "1" -- "0..1" OpenquakeHazardSolution
+
+    note for OpenquakeHazardSolution "T3BlbnF1YWtlSGF6YXJkU29sdXRpb246NjUzNjk0MQ=="
+    note for OpenquakeHazardTask "T3BlbnF1YWtlSGF6YXJkVGFzazo2NTM2ODgx"
+
+```
+
+## OQ hazard processing
+
+```mermaid
+classDiagram
+
+    direction TB
+
+    class SourceLogicTreeBranch
+    class GroundMotionLogicTreeBranch
+
+    class OpenquakeHazardSolution {
+        vs30
+    }
+
+    class THS_OpenquakeMeta {
+        <<DynamoDB Row>>
+        String toshi_hazard_solution_id
+        etc
+    }
+
+    class THS_OpenquakeRealization {
+        <<DynamoDB Row>>
+        toshi_hazard_solution_id
+        location_code
+        rlz_id
+        vs30
+        hazard_curves
+    }
+
+    class Realization {
+        Integer id
+        string[] imts
+        float[] poes
+    }
+
+
+
+    THS_OpenquakeRealization -- THS_OpenquakeMeta
+    THS_OpenquakeRealization *-- Realization
+
+    Realization "1" -- "1..*" OpenquakeHazardSolution
+
+    SourceLogicTreeBranch -- Realization
+    GroundMotionLogicTreeBranch -- Realization
+
+
+```
+
+## Not needed
+
+```
+    %% HDF5 -- THS_meta
+    %% HDF5 "1" -- "*" RLZ
+
+    %% OHT --|> "produces" HDF5
+    class HDF5["Openquake_HDF5"] {
+        <<File>>
+        realizations
+        hazard_curves
+    }
+    class SLTC_VL["SLTC_VS30_Location"] {
+        +Int vs30
+        +String location_code
+    }
+
+```

docs/domain_model/seismic_hazard_model.md

@@ -0,0 +1,119 @@
+## Introduction 
+
+The NZ NSHM project publishes **Seismic Hazard Model** versions in the [GNS_Science/nzshm-model]() github repository.
+
+Models may be Published or Partial.
+
+ - Published models are for use by 3rd parties e.g. `NSHM_v1.0.4`.
+ - Partial/Unpublished models are typically used for comparisons against complete models, e.g sensitivity tests. They usually are most informative when compared to a published model.
+
+## Seismic Hazard Model diagram
+
+```mermaid
+classDiagram
+direction LR
+
+SeismicHazardModel *-- "1" SourceLogicTree
+SeismicHazardModel *-- "1" GroundMotionModelLogicTree
+
+class SeismicHazardModel {
+    version() string a unique string identifying the model
+    notes() string   more details on this particular model
+}
+
+class HazardModelRealisation {
+    vs30s() integer
+    LocationList() string[]
+    IMTList() string[]
+    hazardCurve(vs30, IMT, Location)
+}
+
+class HazardCurveResult {
+    vs30() string
+    Location() string
+    IMT() string
+    curves() float[]
+}
+
+SeismicHazardModel -- "0..*" HazardModelRealisation
+HazardModelRealisation -- "0..*" HazardCurveResult
+```
+
+## The Source Logic Tree hierarchy
+
+A SourceLogicTree structure describes the 'source' components of the model. Each **SeismicHazardModel** must contain a fully populated **SourceLogicTree**.
+
+A **SourceLogicTree** is further composed of a hierarchy of **SourceLogicTreeGroup**, **SourceLogicTreeBranch** and **SourceLogicTreeSource** objects. 
+
+
+```mermaid
+classDiagram
+direction LR
+
+SourceLogicTree *-- "1..*" SourceLogicTreeGroup
+SourceLogicTreeGroup *-- "1..*" SourceLogicTreeBranch
+SourceLogicTreeBranch "0..*" -- "1..*" SourceLogicTreeSource
+
+class SourceLogicTree {
+    version() string 
+    notes() string
+}
+
+class SourceLogicTreeGroup {
+    group() string e.g `Hik, Puy`
+    tectonic_region() string e.g. `Slab, Crustal`
+    check_branch_weights() boolean
+}
+
+class SourceLogicTreeBranch {
+    weight() float 
+    tag() string  e.g. `Hik TL, N16.5, b0.95, C4, s0.42`
+}
+
+class SourceLogicTreeSource {
+    tag() string  e.g. `Hik TL, N16.5, b0.95, C4, s0.42, IFM`
+}
+```
+
+???+ note "NSHM SourceLogicTreeGroups"
+
+    In `NSHM_v1.0.4` the model contains 4 SourceLogicTreeGroups: one each for Crustal, Hikurangi, Puysegur and Slab sources.
+
+Each SourceLogicTreeSource is a re-useable arrangment of fault sources, so these are uniquely identified to support reuse in independent **Seismic Hazard Models**.
+
+
+## Types of Source Logic Tree Source.
+
+NSHM and many other SeismicHazardModels will include different types of SourceLogicTreeSource model. 
+
+In NZ NSHM we have three ...
+
+ - Crustal sources usually contain a fault source model NRML and a distributed/gridded source  NRML.
+   For NSHM Crustal sources it is helpful to know both the RuptureSet and the inversoin source model as well.
+ - Subduction sources contain a single fault source describing the ruptures that can occur across the subduction fault system.
+ - A single Slab source that describes source rates occuring in the interface region (25-) 
+
+We use the NRML (XML) file format for SourceLogicTreeSource sources. This format is required to run hazard calculation in Openquake, and it's well known throughout our user community.
+
+???+ warning "Nov 2023 - this is model under active revision !!"
+
+```mermaid
+classDiagram 
+
+direction TB
+
+SourceLogicTreeSource <|-- SubductionSource
+SourceLogicTreeSource <|-- SlabSource 
+SourceLogicTreeSource <|-- CrustalSource
+
+class SourceLogicTreeSource {
+    tag() string  e.g. Hik TL, N16.5, b0.95, C4, s0.42, IFM
+}
+
+class CrustalSource {
+    source_id() string get the source identifier
+    on_fault_nrml() string get the on_fault_source NRML
+    gridded_nrml() string get the gridded source NRML
+}
+
+```

docs/science_process/toshi_schema.md

@@ -0,0 +1,64 @@
+
+## Toshi Hazard objects (Task + Solution + Config)
+```mermaid
+
+classDiagram
+
+
+    class OHT["Openquake Hazard Task"] {
+        <<AutomationTaskInterface, Node>>
+        config "The task configuration"
+        hazard_solution "The openquake solution"
+
+        model_type enum CRUSTAL, SUBDUCTION, COMPOSITE
+        task_type enum HAZARD, DISAGG, UNDEFINED
+    }
+
+    class OHS["Openquake Hazard Solution"] {
+        <<PredecessorsInterface, Node>>
+        created "When it was created UTZ"
+        metrics "result metrics ...  a list of Key Value pairs."
+        meta "metadata... a list of Key Value pairs."
+        produced_by  "The task that produced this solution"
+        task_args = "task arguments json file."
+
+        config "the template configuration used to produce this solution"
+        modified_config = "a zip archive containing modified config files."
+        csv_archive = "zip archive containing hazard csv outputs `oq engine --export-outputs ....`"
+        hdf5_archive "a zip of the raw hdf5"
+
+
+    }
+
+
+    class OHC["Openquake Hazard Config"] {
+        <<Node>>
+        nodeId[] source_models "List of Source NRML files"
+        nodeId   template_archive "archive of all the additional config files"
+    }
+
+    OHT "*" -- "1" OHC
+    OHS "*" -- "1" OHC
+    OHT "1" -- "0..1" OHS
+
+    note for OHS "T3BlbnF1YWtlSGF6YXJkU29sdXRpb246NjUzNjk0MQ=="
+    note for OHT "T3BlbnF1YWtlSGF6YXJkVGFzazo2NTM2ODgx"
+
+```
+
+### crumbs
+```
+    class OHT1["Openquake Hazard Task from pres"] {
+        <<Node>>
+        String id: 
+        node hazard_solution
+        model_type
+        logic_tree_permutations
+        intensity_spec
+        vs30
+        String[] location_list
+        node template_archive
+        hazard_config
+        source_models
+    }
+```

mkdocs.yml

@@ -5,6 +5,12 @@ repo_name: gns-science/nzshm-documentation
 
 nav:
   - About: index.md
+
+  - Domain Model:
+      - domain_model/index.md
+      - Seismic Hazard Model:  domain_model/seismic_hazard_model.md
+      - Hazard Realisation: domain_model/hazard_realisation_model.md
+
   - Science Processes:
       - science_process/index.md
       - Source models: science_process/source_models.md