# hallvar-h/tops architecture

> Architecture diagram of the GitHub repository hallvar-h/tops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hallvar-h/tops
- Repository: https://github.com/hallvar-h/tops

## Overview

##### Main Components
- Simulator Core: Represent the engine that handles the dynamic simulation routines (e.g., src/tops/dynamic.py, src/tops/simulator.py).
- Dynamic Models Module: Highlight the collection of power system component models used in dynamic simulations. This includes the models for generators, loads, governors, exciters, etc. – found under src/tops/dyn_models.
- Power System Models (ps_models): A separate set of exemplary power system network models (such as IEEE 39, IEEE 68, k2a, etc.) located in src/tops/ps_models, used for simulation scenarios.
- Solvers: Include both the standard solvers (src/tops/solvers.py) and the SDE (stochastic differential equation) solvers (src/tops/solvers_sde.py), which are key to time stepping and solution of simulation equations.
- Data Handling & Utility Modules: Components for plotting (src/tops/plotting.py), utility functions, and any other helper routines.
- Testing Framework: Although not part of the runtime architecture, illustrating the tests subdirectory helps capture the project’s focus on validation and quality, reflecting its research orientation.
- CI/CD Components: Optionally include the GitHub workflows shown under .github/workflows as part of the overall development infrastructure.

##### Component Relationships and Flow
- Data/Input Flow: Show how simulation parameters, network topologies, and initial conditions (possibly described in the examples or passed during runtime) feed into the simulator core.
- Solver Integration: Demonstrate the connection between the simulator core and the numerical solvers – indicating data exchange during timestep resolution.
- Output/Visualization: Represent the plotting functions and interfaces (examples/interfaces, plotting.py) that transform simulation outputs into visualizations, handled also by example notebooks.
- Extensibility via User Models: Outline how user-extended models (found in examples/user_models) plug into the simulation framework.
- Testing & Validation Loop: Optionally, include a separate testing block that validates simulation outcomes using provided test data (from tests/test_validation).

##### Architectural Patterns & Essential Design Elements
- Modular Design: The project is organized into clearly separated modules (dynamic, models, solvers, etc.). Emphasize these modules as independent components that interact through well-defined interfaces.
- Research and Experimentation Flexibility: Since the README notes experimental features, highlight extension points such as user models and experimental solvers.
- Technology Stack: Note that lightweight Python libraries (numpy, scipy, pandas, matplotlib) are used throughout.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces & Examples
    subgraph "External Interfaces & Examples"
        EX["Examples"]:::external
    end

    %% Simulation Engine
    subgraph "Simulation Engine"
        DYN["dynamic.py"]:::core
        SIM["simulator.py"]:::core
    end

    %% Dynamic Models Module
    subgraph "Dynamic Models Module"
        DM["dyn_models"]:::models
    end

    %% Power System Models
    subgraph "Power System Models"
        PS["ps_models"]:::models
    end

    %% Solvers
    subgraph "Solvers"
        SOL["solvers.py"]:::solvers
        SDE["solvers_sde.py"]:::solvers
    end

    %% Data Handling & Utilities
    subgraph "Data Handling & Utilities"
        PLOT["plotting.py"]:::utils
        UTIL["utility_functions.py"]:::utils
        MODAL["modal_analysis.py"]:::utils
    end

    %% Support Components
    subgraph "Support"
        TEST["Testing Framework"]:::support
        CI["CI/CD"]:::support
    end

    %% Flow Connections
    EX -->|"feeds"| SIM
    SIM -->|"calls"| DM
    SIM -->|"integrates"| PS
    SIM -->|"invokes"| SOL
    SIM -->|"invokes"| SDE
    SIM -->|"outputs"| PLOT
    SIM -->|"utilizes"| UTIL
    SIM -->|"analyzes"| MODAL
    PLOT -->|"visualizes"| EX
    TEST -->|"validates"| SIM
    CI -->|"supports"| SIM

    %% Click Events
    click DYN "https://github.com/hallvar-h/tops/blob/main/src/tops/dynamic.py"
    click SIM "https://github.com/hallvar-h/tops/blob/main/src/tops/simulator.py"
    click DM "https://github.com/hallvar-h/tops/tree/main/src/tops/dyn_models"
    click PS "https://github.com/hallvar-h/tops/tree/main/src/tops/ps_models"
    click SOL "https://github.com/hallvar-h/tops/blob/main/src/tops/solvers.py"
    click SDE "https://github.com/hallvar-h/tops/blob/main/src/tops/solvers_sde.py"
    click PLOT "https://github.com/hallvar-h/tops/blob/main/src/tops/plotting.py"
    click UTIL "https://github.com/hallvar-h/tops/blob/main/src/tops/utility_functions.py"
    click MODAL "https://github.com/hallvar-h/tops/blob/main/src/tops/modal_analysis.py"
    click EX "https://github.com/hallvar-h/tops/tree/main/examples"
    click TEST "https://github.com/hallvar-h/tops/tree/main/tests"
    click CI "https://github.com/hallvar-h/tops/tree/main/.github/workflows"

    %% Styles
    classDef external fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef models fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef solvers fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef utils fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef support fill:#d1ecf1,stroke:#333,stroke-width:2px;
```
