# uw-ctrl/stlcg-plus-plus architecture

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

- Interactive diagram: https://gitdiagram.com/uw-ctrl/stlcg-plus-plus
- Repository: https://github.com/uw-ctrl/stlcg-plus-plus

## Overview

##### Project type and purpose
- Type: Python library / toolbox for computing robustness of Signal Temporal Logic (STL) formulas.
- Purpose: Given time‐series signals and STL formulas, build a PyTorch computation graph to compute robustness values and support visualization.

##### File structure
- Top‐level files:
– setup.py: packaging/build script.
– demo.ipynb: usage example & notebook‐style tutorial.
– README.md: high‐level overview and installation.
- Package directory “stlcgpp”:
– formula.py: definitions and constructors for STL formulas and predicates.
– utils.py: helper routines (e.g., signal formatting, tensor conversions).
– viz.py: plotting and visualization utilities for formulas and robustness traces.
– tests.py: unit tests for formula evaluation and utility correctness.

##### README for additional insights
- Dependencies: Python 3.10+, PyTorch.

##### Main components & their interactions
a. Components
1. User Interface (demo.ipynb / client code)
2. Formula Builder (stlcgpp/formula.py)
3. Utilities (stlcgpp/utils.py)
4. Computation Engine (PyTorch)
5. Visualization Module (stlcgpp/viz.py)
6. Distribution & Packaging (setup.py, PyPI)
7. Tests (stlcgpp/tests.py)
b. Relationships & data flow
- Client supplies input signals → Utils preprocess into PyTorch tensors.
- Formula Builder constructs a computation graph using PyTorch operators.
- PyTorch engine executes the graph → outputs robustness scores and traces.
- Visualization Module consumes the numeric results → renders plots.
- Tests validate each step by invoking utils, formula, and viz in isolation.
c. Architectural patterns / principles
– Modular layering: clear separation of formula logic, tensor utilities, and visualization.
– Pipeline pattern: linear data processing from input → graph construction → evaluation → output.
– Dependency injection: client code orchestrates modules without tight coupling.
d. Key technologies & libraries
– Python 3.10+
– PyTorch (computation graphs)
– Matplotlib / Plotly (via viz.py for plotting)
– Jupyter Notebook for demo/ipynb usage

##### Elements
– Input signals → Utils → Formula Builder → PyTorch Engine → Visualization → Output.
- Annotations for key interfaces (e.g., “.to_tensor()”, “build_graph()”, “plot_trace()”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Library"
        Utils["Utilities\n(stlcgpp/utils.py)"]:::core
        Formula["Formula Builder\n(stlcgpp/formula.py)"]:::core
        Viz["Visualization Module\n(stlcgpp/viz.py)"]:::core
    end

    Client["User Interface\ndemo.ipynb"]:::client
    PyTorch["PyTorch Engine"]:::external
    Matplotlib["Matplotlib/Plotly"]:::external
    Packaging["Distribution & Packaging\nsetup.py"]:::packaging
    README["README.md"]:::documentation
    Tests["Tests\n(stlcgpp/tests.py)"]:::tests

    Client -->|"load signals"| Utils
    Utils -->|"to_tensor()"| Formula
    Formula -->|"build_graph()"| PyTorch
    PyTorch -->|"robustness scores"| Viz
    Viz -->|"plot_trace()"| Client

    Viz -->|"uses plotting"| Matplotlib
    Formula -->|"relies on"| PyTorch

    Tests -->|validates| Utils
    Tests -->|validates| Formula
    Tests -->|validates| Viz

    Packaging -->|packages| Utils
    Packaging -->|packages| Formula
    Packaging -->|packages| Viz
    Packaging -->|packages| Tests

    README -.->|describes| Client
    README -.->|describes| Utils
    README -.->|describes| Formula
    README -.->|describes| Viz

    click Client "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/demo.ipynb"
    click Utils "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/stlcgpp/utils.py"
    click Formula "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/stlcgpp/formula.py"
    click Viz "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/stlcgpp/viz.py"
    click Packaging "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/setup.py"
    click Tests "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/stlcgpp/tests.py"
    click README "https://github.com/uw-ctrl/stlcg-plus-plus/blob/main/README.md"

    classDef core fill:#AED6F1,stroke:#1B4F72
    classDef external fill:#A9DFBF,stroke:#145A32
    classDef client fill:#F9E79F,stroke:#B9770E
    classDef packaging fill:#F5B7B1,stroke:#943126
    classDef documentation fill:#D7BDE2,stroke:#512E5F
    classDef tests fill:#D5DBDB,stroke:#626567
```
