GEMScienceTools · kurannn · Jul 27, 2026
diff --git a/README.md b/README.md
@@ -1,3 +1,36 @@
-# QuakeT
-Repository containing the documentation for QuakeT, a project carried out in the context of the SIGMA3 project.
+# quakeT: Simulation Platform
+
+<p align="center">
+  <img src="quaket_logo.png" alt="Logo" width="200">
+</p>
+
+## Description
+QuakeT is an initiative of the **[SIGMA3 project](https://sigma-programs.com/)**, jointly conducted by the **[Électricité de France (EDF)](https://www.edf.fr/en/the-edf-group/innovating-for-the-future/rd-global-expertise)** and the **[Global Earthquake Model Foundation (GEM)](http://gem.foundation)**. Its goal is to collect a set of tools for building components of a probabilistic seismic hazard model, generating synthetic datasets, and checking the compatibility between observations and models.
+
+QuakeT is hosted on github at the following link: https://github.com/GEMScienceTools/quakeT. 
+It is developed in close connection with the **[OpenQuake engine](https://github.com/gem/oq-engine)** and other toolkits in **[GEMScienceTools](https://github.com/GEMScienceTools)**, 
+the open-source hazard and risk calculation engine developed primarily by the **[GEM Foundation](http://gem.foundation)**.
+
+Currently the QuakeT includes four main sub-modules:
+
+* **[Auxiliary module](https://gemsciencetools.github.io/quakeT/contents/auxiliary.html)** contains corollary functionalities that support the capabilities of the platform’s core modules;
+
+* **[Seismic source module](https://gemsciencetools.github.io/quakeT/contents/ssc.html)** contains tools for producing models related to seismic sources;
+
+* **[Ground motion module](https://gemsciencetools.github.io/quakeT/contents/gmc.html)** will contain functionalities for computing ground motion intensity measures (IMs);
+
+* **[Site and site-effects module](https://gemsciencetools.github.io/quakeT/contents/site.html)** will be developed for modelling the site response;
+
+## Documentation
 Documentation available at https://GEMScienceTools.github.io/quakeT/
+
+## Project Status & Active Development
+Simulation Platform (**quakeT**) is an toolkit developed under the **[Work Package-5 of SIGMA3 project](https://sigma-programs.com/sigma-3/sigma-3-technical-program/)**. **[SIGMA3 project](https://sigma-programs.com/)** is an ongoing project scheduled for completion by the end of 2028. As a result, this repository will remain under active development. Expect continuous updates, including new features, refactoring, and codebase modifications until the final release.
+
+## License
+The quakeT is released under the **GNU Affero Public License 3**.
+
+## Contacts
+* Support forum: https://groups.google.com/forum/#!forum/openquake-users
+
+## Thanks
diff --git a/doc/conf.py b/doc/conf.py
@@ -19,6 +19,8 @@
 import shutil
 
 extensions = [
+  'sphinx.ext.autodoc',
+  'sphinx.ext.intersphinx',
   'sphinx.ext.todo',
   'sphinx.ext.coverage',
   'sphinx.ext.mathjax',
@@ -27,11 +29,12 @@
   'sphinx_rtd_theme',
   'myst_parser',
   'nbsphinx',
-  'nbsphinx_link',
+  'nbsphinx_link'
 ]
 
 nbsphinx_allow_errors = True
 nbsphinx_execute = 'never'
+default_role = 'term'
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']

diff --git a/doc/contents/auxiliary.rst b/doc/contents/auxiliary.rst
@@ -1,27 +1,28 @@
 Auxiliary Module
 ################################
 
-The :index:`auxiliary` module contains corollary functions that support the capabilities of the 
-platform's core modules (e.g., the source, ground-motion, and site-response modules).
-This module, therefore, acts as a bridge between raw data and the functions available in the simulation platform 
-by supporting I/O tools, statistical analysis, visualisation, and data management.
+The *auxiliary module* contains corollary notebooks that support the capabilities of the 
+platform's core modules (e.g., the source, ground-motion, and site/site-effects modules).
 
-Currently, the Auxiliary Module includes functions underpinning the Seismic Source Module 
-and its associated case study. 
+Currently, the Auxiliary Module includes tools underpinning the Seismic Source Module 
+and its associated case study.
 
 However, as the project will progress to ground motion and site modules, new functionalities 
 will be integrated into this framework. Consequently, this task will remain active throughout 
 the project, enabling continuous updates and refinements in response to the platform's evolving 
 requirements.
 
-To ensure a structured development process, the module is, for time being, subdivided into 
-three primary sub-sections: catalogue processing, statistical tools - plotting, and spatial 
-distributions.
-
-Tutorial Contents
------------------
+SSM Tutorial Contents
+---------------------
 
 .. toctree::
    :maxdepth: 1
 
-   ses_processing
+   ses
+   catalogue
+   homogenising
+   completeness
+   declustering
+   interevent
+   mfd
+
diff --git a/doc/contents/catalogue.nblink b/doc/contents/catalogue.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../openquake/quaket/auxiliary/catalogue.ipynb"
+}
diff --git a/doc/contents/completeness.nblink b/doc/contents/completeness.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../openquake/quaket/auxiliary/completeness.ipynb"
+}
diff --git a/doc/contents/data_formats.rst b/doc/contents/data_formats.rst
@@ -0,0 +1,181 @@
+Data Formats
+################################
+
+The *Data Formats* section provides supported input formats and their descriptions that will be used in the simulation platform.
+
+Stochastic Event Set
+========================
+The event output generated by the `OpenQuake (OQ) Engine event-based PSHA calculation workflow <https://docs.openquake.org/oq-engine/manual/latest/user-guide/workflows/event-based-psha.html>`_ includes the following columns:
+
+*List of columns in the event set*
+
++-------------+----------------------------------------------------------------------------------------------------+
+| Attribute   | Description                                                                                        |
++=============+====================================================================================================+
+| event_id    | A unique identifier (integer) for each earthquake in the catalogue                                 |
++-------------+----------------------------------------------------------------------------------------------------+
+| rup_id      | Incremental number identifying the rupture                                                         |
++-------------+----------------------------------------------------------------------------------------------------+
+| rlz_id      | A unique identifier (integer) for the logic-tree realization associated with the event             |
++-------------+----------------------------------------------------------------------------------------------------+
+| year        | Year of event (integer)                                                                            |
++-------------+----------------------------------------------------------------------------------------------------+
+| ses_id      | A unique identifier (integer) for the stochastic event set simulation to which the event belongs   |
++-------------+----------------------------------------------------------------------------------------------------+
+
+Stochastic Rupture Set
+========================
+The rupture output generated by the `OpenQuake (OQ) Engine event-based PSHA calculation workflow <https://docs.openquake.org/oq-engine/manual/latest/user-guide/workflows/event-based-psha.html>`_ includes the following columns:
+
+*List of columns in the rupture set*
+
++------------------+------------------------------------------------------------------------------------------+
+| Attribute        | Description                                                                              |
++==================+==========================================================================================+
+| rup_id           | A unique identifier (integer) for each rupture                                           |
++------------------+------------------------------------------------------------------------------------------+
+| source_id        | A unique identifier (integer or string) for the seismic source generating the rupture    |
++------------------+------------------------------------------------------------------------------------------+
+| multiplicity     | How many times the rupture occurs in the effective investigation time                    |
++------------------+------------------------------------------------------------------------------------------+
+| mag              | Float specifying the magnitude of the rupture                                            |
++------------------+------------------------------------------------------------------------------------------+
+| centroid_lon     | Longitude of the centroid of the rupture                                                 |
++------------------+------------------------------------------------------------------------------------------+
+| centroid_lat     | Latitude of the centroid of the rupture                                                  |
++------------------+------------------------------------------------------------------------------------------+
+| centroid_depth   | Depth (in km) of the centroid of the rupture                                             |
++------------------+------------------------------------------------------------------------------------------+
+| trt              | String specifying the tectonic region type                                               |
++------------------+------------------------------------------------------------------------------------------+
+| strike           | Strike angle of the rupture surface                                                      |
++------------------+------------------------------------------------------------------------------------------+
+| dip              | Dip angle of the rupture surface                                                         |
++------------------+------------------------------------------------------------------------------------------+
+| rake             | Rake angle of the rupture surface                                                        |
++------------------+------------------------------------------------------------------------------------------+
+
+
+Catalogue
+========================
+GEM Hazard Modeller’s Tookit (hmtk) .csv format :ref:`[1] <ref-weatherill-2014>` is the main catalogue format used in the simulation platform. It includes the following columns:
+
+*List of Attributes in the Earthquake Catalogue File (\* Indicates Essential)*
+
++----------------------+-----------------------------------------------------------------------------------------------+
+| Attribute            | Description                                                                                   |
++======================+===============================================================================================+
+| eventID\*            | A unique identifier (integer) for each earthquake in the catalogue                            |
++----------------------+-----------------------------------------------------------------------------------------------+
+| Agency               | The code (string) of the recording agency for the event solution                              |
++----------------------+-----------------------------------------------------------------------------------------------+
+| year\*               | Year of event (integer) in the range -10000 to present                                        |
+|                      | (events before common era (BCE) should have a negative value)                                 |
++----------------------+-----------------------------------------------------------------------------------------------+
+| month\*              | Month of event (integer)                                                                      |
++----------------------+-----------------------------------------------------------------------------------------------+
+| day\*                | Day of event (integer)                                                                        |
++----------------------+-----------------------------------------------------------------------------------------------+
+| hour\*               | Hour of event (integer) - if unknown then set to 0                                            |
++----------------------+-----------------------------------------------------------------------------------------------+
+| minute\*             | Minute of event (integer) - if unknown then set to 0                                          |
++----------------------+-----------------------------------------------------------------------------------------------+
+| second\*             | Second of event (float) - if unknown set to 0.0                                               |
++----------------------+-----------------------------------------------------------------------------------------------+
+| timeError            | Error in event time (float)                                                                   |
++----------------------+-----------------------------------------------------------------------------------------------+
+| longitude\*          | Longitude of event, in decimal degrees (float)                                                |
++----------------------+-----------------------------------------------------------------------------------------------+
+| latitude\*           | Latitude of event, in decimal degrees (float)                                                 |
++----------------------+-----------------------------------------------------------------------------------------------+
+| SemiMajor90          | Length (km) of the semi-major axis of the 90 % confidence ellipsoid for location error (float)|
++----------------------+-----------------------------------------------------------------------------------------------+
+| SemiMinor90          | Length (km) of the semi-minor axis of the 90 % confidence ellipsoid for location error (float)|
++----------------------+-----------------------------------------------------------------------------------------------+
+| ErrorStrike          | Azimuth (in degrees) of the 90 % confidence ellipsoid for location error (float)              |
++----------------------+-----------------------------------------------------------------------------------------------+
+| depth\*              | Depth (km) of earthquake (float)                                                              |
++----------------------+-----------------------------------------------------------------------------------------------+
+| depthError           | Uncertainty (as standard deviation) in earthquake depth (km) (float)                          |
++----------------------+-----------------------------------------------------------------------------------------------+
+| magnitude\*          | Homogenised magnitude of the event (float) - typically Mw                                     |
++----------------------+-----------------------------------------------------------------------------------------------+
+| sigmaMagnitude       | Uncertainty on the homogenised magnitude (float) typically Mw                                 |
++----------------------+-----------------------------------------------------------------------------------------------+
+
+
+Source Polygon
+========================
+Standard GeoJSON format is used to define source zones or study areas. The example below shows a polygon structure used to represent a tectonic or seismic zone.
+
+
+.. code-block:: json
+   :caption: Example GeoJSON Polygon Structure
+   :name: geojson-polygon
+
+   {
+     "name": "sample",
+     "features": [
+       {
+         "type": "Feature",
+         "properties": {
+           "id": "id"
+         },
+         "geometry": {
+           "type": "Polygon",
+           "coordinates": [
+             [
+               [
+                 [-3.9115, 43.5650],
+                 [-3.8500, 43.5650],
+                 [-3.8500, 43.5200],
+                 [-3.9115, 43.5200],
+                 [-3.9115, 43.5650]
+               ]
+             ]
+           ]
+         }
+       }
+     ]
+   }
+
+
+Completeness Configuration
+===========================
+A completeness parameter configuration file supplied as a .toml file. The toml file will set up parameters 
+for completeness step and be modified while running the code. The configuration toml is created by the modeller.
+
+
+.. code-block:: toml
+   :caption: Example toml configuration for completeness
+
+   [completeness]
+   num_steps = 0
+   step = 8
+   mags = [ 4.5, 5.0, 5.5, 6.0, 6.5, 7.0, 7.5,]
+   years = [ 1905, 1920, 1940, 1960, 1980, 2000, 2020,]
+   ref_mag = 4.5
+   ref_upp_mag = 10.0
+   bmin = 0.5
+   bmax = 1.5
+   last_year = 2020
+   optimization_criterion = "optimize"
+
+   [sources.id]
+
+Underneath these settings, we have headers for the source. By running the workflow, 
+we will add information of completeness and MFD parameters. The parameters inside the toml file 
+are described below.
+
+
+- ``num_steps``: Sets preferred number of steps in window.
+- ``step``: Steps is used for parallelisation. 
+- ``mags``: List of candidate completeness magnitudes considered in the analysis.
+- ``years``: List of candidate years at which catalogue completeness may have changed.
+- ``ref_mag``: Reference minimum magnitude used in the Gutenberg–Richter analysis.
+- ``ref_upp_mag``: Upper reference magnitude limit considered in the analysis.
+- ``bmin``: Minimum allowable Gutenberg–Richter b-value during optimization.
+- ``bmax``: Maximum allowable Gutenberg–Richter b-value during optimization.
+- ``last_year``: Final year of the catalogue used in the completeness analysis.
+- ``optimization_criterion``: Options for norm (e.g., “Optimize” or “Poisson”)
+
diff --git a/doc/contents/declustering.nblink b/doc/contents/declustering.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../openquake/quaket/auxiliary/declustering.ipynb"
+}