# gemsciencetools/oq-vmtk architecture

> Architecture diagram of the GitHub repository gemsciencetools/oq-vmtk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gemsciencetools/oq-vmtk
- Repository: https://github.com/gemsciencetools/oq-vmtk

## Overview

##### Main Components
- Core Library (under “openquake/vmtk”): This is the heart of the toolkit. It includes modules such as:
- calibration.py: Likely manages the calibration of the models.
- im_calculator.py: Computes intensity measures.
- modeller.py: Constructs the single- or multi-degree-of-freedom system models.
- plotter.py: Provides visualization routines.
- postprocessor.py: Processes results from analyses.
- slf_generator.py: Creates storey loss function estimates.
- utilities.py and units.py: Support functions and unit conversions.
- Demo Scripts (under “demos” and “.virtual_documents/demos”):
- Input dataset directories (CSV files, pkl files) that simulate real-world inventories, ground motion records, and accelerations.
- Testing Suite:
- Located under “openquake/vmtk/tests” (and test data), ensuring each module’s functionality and validating the core processing routines.
- Documentation and CI/CD:
- The “docsrc” directory holds source files for documentation generation.
- GitHub workflows (in “.github/workflows”) for continuous integration across different operating system platforms.
- Configuration & Dependency Management:
- Multiple requirements files and the pyproject.toml are used to manage dependencies, hinting at different Python environments and platform-specific dependencies (Windows vs. Linux).

##### Relationships and Data Flow
- Input Layer:
- The demos/in directory contains CSV inputs, such as inventories (for structural properties) and records (seismic data – acceleration, DTS files). These are fed into the system.
- Core Processing:
- The data flows from the input files into the main library modules. For example, the modeller uses input parameters (storey count, force-deformation relationships) to establish system models.
- The IM Calculator and Calibration modules then process these models to compute key engineering measures.
- The Postprocessor and SLF Generator further analyze the output to derive fragility and vulnerability functions.
- Visualization:
- The Plotter module takes data from various analysis stages to generate graphs such as cloud analysis results, system response profiles, and fragility curves.
- Output Layer:
- Results are stored in the demos/out folder and can also be visualized via interactive notebooks.
- Testing and Documentation:
- Continuous tests (CI workflows) ensure that as the code base evolves, each module interacts correctly.
- Documentation is generated from the “docsrc” files, providing a user-friendly guide to using each component.

##### Architectural Patterns and Design Principles
- Modular Architecture:
- The system is split into distinct modules (calibration, modelling, analysis, plotting) that can be developed and tested independently.
- Separation of Concerns:
- Input/processing/output responsibilities are clearly separated, helping both in maintenance and in simplifying the demonstration workflows.
- Extensibility:
- By isolating core functionality in the “openquake/vmtk” package, new modules or enhancements (e.g., additional analysis methods) can be integrated without affecting existing features.
- Integration with External Dependencies:
- The toolkit leverages external libraries (such as OpenSeesPy) and is designed to run in a properly managed virtual environment to avoid dependency issues.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External and Input Layers
    ED["External Dependencies (OpenSeesPy, Python packages)"]:::external
    ID["Input Data (demos/in)"]:::io
    DS["Demo Scripts (demos/)"]:::demo
    DS2["Virtual Demo Scripts (.virtual_documents/demos)"]:::demo

    %% Auxiliary Nodes
    TS["Testing Suite (openquake/vmtk/tests)"]:::aux
    DOC["Documentation (docsrc)"]:::aux
    CI["CI/CD Workflows (.github/workflows)"]:::aux
    DEP["Dependencies (pyproject.toml)"]:::aux
    OD["Output Data (demos/out)"]:::io

    %% Core Library Subgraph
    subgraph "Core Library"
        M["Modeller"]:::core
        C["Calibration"]:::core
        I["IM Calculator"]:::core
        PP["Postprocessor"]:::core
        SL["SLF Generator"]:::core
        PL["Plotter"]:::core
        U["Utilities"]:::core
        UN["Units"]:::core
    end

    %% Data Flow Connections
    ED --> M
    ID --> M
    DS --> ID
    DS --> OD
    DS2 --> ID
    DS2 --> OD

    M -->|"feeds"| C
    M -->|"feeds"| I
    C -->|"processedTo"| PP
    I -->|"processedTo"| PP
    C -->|"dataTo"| SL
    I -->|"dataTo"| SL
    PP -->|"resultsTo"| PL
    SL -->|"resultsTo"| PL
    PL --> OD

    %% Supportive Modules
    U -.-> M
    UN -.-> M

    %% Auxiliary Connections to Core Library
    TS --- M
    DOC --- M
    CI --- M
    DEP --- M

    %% Click Events for Component Mapping
    click M "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/modeller.py"
    click C "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/calibration.py"
    click I "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/im_calculator.py"
    click PP "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/postprocessor.py"
    click SL "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/slf_generator.py"
    click PL "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/plotter.py"
    click U "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/utilities.py"
    click UN "https://github.com/gemsciencetools/oq-vmtk/blob/main/openquake/vmtk/units.py"
    click DS "https://github.com/gemsciencetools/oq-vmtk/tree/main/demos/"
    click DS2 "https://github.com/gemsciencetools/oq-vmtk/tree/main/.virtual_documents/demos/"
    click ID "https://github.com/gemsciencetools/oq-vmtk/tree/main/demos/in/"
    click TS "https://github.com/gemsciencetools/oq-vmtk/tree/main/openquake/vmtk/tests/"
    click DOC "https://github.com/gemsciencetools/oq-vmtk/tree/main/docsrc/"
    click CI "https://github.com/gemsciencetools/oq-vmtk/tree/main/.github/workflows/"
    click DEP "https://github.com/gemsciencetools/oq-vmtk/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef io fill:#FFFACD,stroke:#000,stroke-width:1px;
    classDef demo fill:#E6E6FA,stroke:#000,stroke-width:1px;
    classDef aux fill:#FFDAB9,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
