# marekwadinger/sippy architecture

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

- Interactive diagram: https://gitdiagram.com/marekwadinger/sippy
- Repository: https://github.com/marekwadinger/sippy

## Overview

##### Project type and purpose
- SIPPY is an open-source Python library for linear system identification of dynamical systems. It provides algorithms for input–output models (ARX, ARMAX, etc.) and state-space methods (N4SID, PARSIM, etc.).
- There is no client–server or GUI; the “system” is a modular library invoked via a Python API or Jupyter notebooks.

##### File structure
- Top-level artifacts:
- sippy_unipi/        ← core Python package
- docs/               ← documentation (MkDocs, examples, tutorials)
- benchmarks/         ← performance scripts
- CI/CD config: .github/, Dockerfile, Makefile, mkdocs.yml
- Core package submodules under sippy_unipi/:
- datasets/           ← data-loading and synthetic data generators
- io/                 ← import/export routines for different model types
- preprocessing.py    ← data pre-conditioning utilities
- tf2ss/              ← transfer-function-to-state-space conversion
- ss/                 ← state-space identification algorithms
- model_selection.py  ← selection of best model structure
- evaluate.py         ← metrics and result evaluation
- utils/              ← shared helpers, validation, base classes
- There is a single entry-point API function: system_identification (in __init__.py).

##### README for additional insights
- Lists supported algorithms and features (FIR, ARX, ARMAX… N4SID, MOESP… etc.)
- Quickstart demonstrates how the user calls system_identification() with data
- Installation and Dockerization indicate deployment contexts.

- User / Client Layer
- Data Sources
- User-provided time series (Y, U)
- Built-in sample datasets
- API Layer
- system_identification() entry point
- Core Processing Modules (layered):
1. Preprocessing Module
2. IO Module (format parsing, data interfacing)
3. Algorithm Modules
– Input–Output Algorithms (ARX, ARMAX, …)
– State–Space Algorithms (N4SID, PARSIM, …)
– Transfer-Function converters (tf2ss)
4. Model Selection Module
5. Evaluation Module
- Utilities Module (cross-cutting)
- External Integrations
- Jupyter Notebooks (docs/examples)
- Documentation (MkDocs site)
- CI/CD Pipelines (GitHub Actions, Docker)
- Packaging (PyPI)

b. Relationships and interactions
- The User invokes the system_identification API →
- Data flows from Data Sources → Preprocessing → IO Module →
- Processed data passed to the selected Algorithm Module →
- Output model passed to Model Selection →
- Final model evaluated by Evaluation Module →
- Results returned to User or passed to downstream analysis
- Utilities are invoked by all internal modules as needed
- Docs and examples reference the same API and modules
- CI/CD and Docker connect to the repo for testing, building, and publishing

c. Architectural patterns and design principles
- Layered architecture: clear separation between data ingestion, processing, algorithms, selection, and evaluation
- Modular design: each algorithm family lives in its own subpackage
- Single public entry point (system_identification) for consistent API
- Cross-cutting concerns handled by utils (validation, base classes)
- Decoupling of core library from documentation and CI

d. Key technologies, frameworks, libraries
- Python 3.10+
- NumPy/SciPy (implied by algorithms)
- MkDocs for documentation
- Jupyter for interactive examples
- Docker for environment reproducibility
- GitHub Actions for CI/CD
- Poetry (pyproject.toml) for packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User / Client"]:::api

    %% Data Sources Layer
    subgraph "Data Sources" 
        direction TB
        BaseDataset["_base.py"]:::data
        InputGenerator["_input_generator.py"]:::data
        SystemsGenerator["_systems_generator.py"]:::data
    end

    %% API Layer
    sysID["system_identification()"]:::api

    %% Core Processing Modules
    subgraph "Core Library (sippy_unipi)" 
        direction TB

        %% Preprocessing
        Preprocessing["preprocessing.py"]:::data

        %% IO Module
        subgraph "IO Module" 
            direction TB
            BaseIO["base.py"]:::data
            ARX["arx.py"]:::data
            ARMAX["armax.py"]:::data
            OPT["opt.py"]:::data
            RLS["rls.py"]:::data
        end

        %% Algorithm Modules
        subgraph "State‐Space Algorithms" 
            direction TB
            SSBase["base.py"]:::algo
            OLSIM["olsim.py"]:::algo
            PARSIM["parsim.py"]:::algo
        end

        %% Transfer-Function Converter
        subgraph "tf2ss Converter" 
            direction TB
            TF2SS["tf2ss.py"]:::algo
            TimeResp["timeresp.py"]:::algo
            TestTF["test_tf2ss.py"]:::algo
        end

        %% Model Selection & Evaluation
        ModelSelection["model_selection.py"]:::me
        Evaluation["evaluate.py"]:::me

        %% Utilities
        subgraph "Utilities" 
            direction TB
            BaseUtils["base.py"]:::utils
            Validation["validation.py"]:::utils
        end
    end

    %% External Integrations
    subgraph "External Services" 
        direction TB
        Jupyter["Jupyter Notebooks"]:::ext
        DocsSite["MkDocs Documentation"]:::ext
        CI_CD["CI/CD & Docker"]:::ext
        PyPI["PyPI Packaging"]:::ext
    end

    %% Benchmarks
    Benchmarks["benchmark_tf2ss.py"]:::ext

    %% Connections - Data Flow
    User -->|invokes| sysID
    sysID --> BaseDataset
    sysID --> InputGenerator
    sysID --> SystemsGenerator
    BaseDataset --> Preprocessing
    InputGenerator --> Preprocessing
    SystemsGenerator --> Preprocessing
    Preprocessing --> BaseIO
    BaseIO --> ARX
    BaseIO --> ARMAX
    BaseIO --> OPT
    BaseIO --> RLS
    ARX --> SSBase
    ARMAX --> SSBase
    RLS --> SSBase
    OPT --> SSBase
    SSBase --> OLSIM
    SSBase --> PARSIM
    OLSIM --> ModelSelection
    PARSIM --> ModelSelection
    TF2SS --> ModelSelection
    ModelSelection --> Evaluation
    Evaluation --> User

    %% Dependencies
    Preprocessing -.-> Validation
    BaseIO -.-> BaseUtils
    SSBase -.-> BaseUtils
    OLSIM -.-> Validation
    PARSIM -.-> Validation
    TF2SS -.-> BaseUtils
    ModelSelection -.-> BaseUtils
    Evaluation -.-> Validation

    %% External Integrations Links
    sysID --> Jupyter
    sysID --> DocsSite
    CI_CD --> Benchmarks
    CI_CD --> DocsSite
    CI_CD --> sysID
    CI_CD --> PyPI

    %% Click Events
    click sysID "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/__init__.py"
    click Preprocessing "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/preprocessing.py"
    click BaseDataset "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/datasets/_base.py"
    click InputGenerator "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/datasets/_input_generator.py"
    click SystemsGenerator "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/datasets/_systems_generator.py"
    click BaseIO "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/io/base.py"
    click ARX "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/io/arx.py"
    click ARMAX "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/io/armax.py"
    click OPT "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/io/opt.py"
    click RLS "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/io/rls.py"
    click SSBase "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/ss/base.py"
    click OLSIM "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/ss/olsim.py"
    click PARSIM "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/ss/parsim.py"
    click TF2SS "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/tf2ss/tf2ss.py"
    click TimeResp "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/tf2ss/timeresp.py"
    click TestTF "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/tf2ss/test_tf2ss.py"
    click ModelSelection "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/model_selection.py"
    click Evaluation "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/evaluate.py"
    click BaseUtils "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/utils/base.py"
    click Validation "https://github.com/marekwadinger/sippy/blob/main/sippy_unipi/utils/validation.py"
    click DocsSite "https://github.com/marekwadinger/sippy/blob/main/docs/index.md"
    click Jupyter "https://github.com/marekwadinger/sippy/tree/main/docs/examples/"
    click CI_CD "https://github.com/marekwadinger/sippy/tree/main/.github/workflows/"
    click Benchmarks "https://github.com/marekwadinger/sippy/blob/main/benchmarks/benchmark_tf2ss.py"
    click PyPI "https://github.com/marekwadinger/sippy/blob/main/pyproject.toml"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef data fill:#E0F7E9,stroke:#1B7A44,color:#1B7A44,stroke-width:1px;
    classDef algo fill:#FFE5B4,stroke:#D2691E,color:#D2691E,stroke-width:1px;
    classDef me fill:#F3E5F5,stroke:#8E44AD,color:#8E44AD,stroke-width:1px;
    classDef utils fill:#F2F2F2,stroke:#555555,color:#555555,stroke-width:1px;
    classDef ext fill:#FBFBFB,stroke:#999999,color:#333333,stroke-width:1px;
```
