# modelon-community/pyfmi architecture

> Architecture diagram of the GitHub repository modelon-community/pyfmi, 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/modelon-community/pyfmi
- Repository: https://github.com/modelon-community/pyfmi

## Overview

##### Main Components
- Core Library Modules:
- The “src/pyfmi” directory contains the heart of the package. Identify submodules that deal with different FMI standards (e.g., fmi.pyx, fmi1.pyx, fmi2.pyx, fmi3.pyx) and FMU import functionality (fmil*_import.pxd files).
- The “src/pyfmi/simulation” module manages simulation routines and provides an interface to simulation tools (e.g., Assimulo integration).
- The “src/pyfmi/debug.py”, “src/pyfmi/fmi_algorithm_drivers.py”, etc., are integrated parts that drive the algorithmic aspect of FMU simulation.

- Common Utilities:
- “src/common” holds shared functionality such as algorithm drivers, I/O handling, logging (with submodules for parsing, pretty printing, and tree views), and plotting (e.g., the plot_gui module).

- Example and Demonstration Components:
- “src/pyfmi/examples” contains sample scripts and FMU files for demonstrating capabilities (including native simulation examples and FMU-based examples).

- Testing Infrastructure:
- The “tests” directory provides unit tests along with sample FMUs and auxiliary files to verify that the package complies with the FMI standard.

- Documentation:
- The Sphinx documentation in the “doc” folder shows that there's an organized effort for technical documentation and user guidance.

##### Relationships and Interactions
- FMU Loading and Parsing:
- How a client (or user script) interacts with the PyFMI API (in “src/pyfmi”) to load an FMU. This component then delegates to lower-level routines (possibly c or cython code given the .pyx and .pxd files) for interfacing with the native FMU binary.

- Simulation Flow:
- After loading, the FMU instance is managed by simulation modules which provide support for both Model Exchange and Co-Simulation. Include how simulation configuration, time-stepping, and state updates occur.

- Utilities & Support Features:

- External Dependencies / Integration:
- External engines such as Assimulo (required for some simulation aspects) and FMU SDK/FMI Library (which is required during installation). Show their interaction with PyFMI’s core simulation layer.

- Testing & Continuous Integration:
- Test suite in “tests” which verifies the functionality of all these components using various FMU samples, ensuring compliance with FMI standards and even working with external tools like the Optimica Compiler Toolkit.

##### Architectural Patterns and Design Principles
- Modularization & Separation of Concerns:
- The package cleanly separates core simulation functionality from utility functions, testing, examples, and documentation.

- Interface Abstraction:
- Notice the usage of Cython (.pyx and .pxd files), which suggests that performance-critical parts have a clear interface with Python—and may interface with native libraries. Represent this boundary with a clear “Native Interface” or “Cython Wrapper” layer.

- Extensibility:
- That new FMU types or simulation strategies can be added by extending the respective submodules in the “src/pyfmi” and “src/common” directories.

##### Including Relevant Technologies
- Python and Cython:
- That the package is implemented in Python with performance-sensitive parts in Cython.

- External Libraries:
- Assimulo, FMI Library, wxPython, and matplotlib (the latter two being optional for certain examples) should be indicated as interacting with PyFMI.

- Documentation Tools:
- The use of Sphinx (in the “doc/sphinx” directory) should be noted as part of the development and user documentation ecosystem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Interaction (API Calls)"]:::api

    subgraph "Core PyFMI Modules"
        C1["FMU Standard Handlers"]:::core
        FS1["fmi.pyx"]:::core
        FS2["fmi1.pyx"]:::core
        FS3["fmi2.pyx"]:::core
        FS4["fmi3.pyx"]:::core
        C2["Simulation Engine & Assimulo Integration"]:::core
        C3["Debug Module"]:::core
        C4["FMU Algorithm Drivers"]:::core
    end

    subgraph "Common Utilities"
        U1["General Utilities"]:::util
        U2["Logging Subsystem"]:::util
        U3["Plotting Tools"]:::util
    end

    subgraph "Example Scripts"
        E1["Examples & Demos"]:::util
    end

    subgraph "External Dependencies"
        X1["Assimulo"]:::ext
        X2["FMI Library"]:::ext
        X3["wxPython"]:::ext
        X4["matplotlib"]:::ext
    end

    T["Testing Framework"]:::test
    D["Documentation (Sphinx)"]:::doc

    %% Connections between components
    U -->|"calls"| C1
    C1 -->|"loads FMU"| C2
    C1 -->|"defines"| FS1
    C1 -->|"defines"| FS2
    C1 -->|"defines"| FS3
    C1 -->|"defines"| FS4
    C3 -->|"assists"| C2
    C4 -->|"drives"| C2
    C2 -->|"logs output"| U2
    C2 -->|"visualizes"| U3
    X1 -->|"integrates"| C2
    X2 -->|"integrates"| C2
    U -->|"triggers"| E1
    C2 -->|"verified by"| T
    E1 -->|"demonstrates"| D
    C2 -->|"documented in"| D

    %% Styles
    classDef api fill:#f7ccad,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef util fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef ext fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef test fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef doc fill:#d1c4e9,stroke:#333,stroke-width:2px;

    %% Click Events
    click C1 "https://github.com/modelon-community/pyfmi/tree/master/src/pyfmi"
    click FS1 "https://github.com/modelon-community/pyfmi/blob/master/src/pyfmi/fmi.pyx"
    click FS2 "https://github.com/modelon-community/pyfmi/blob/master/src/pyfmi/fmi1.pyx"
    click FS3 "https://github.com/modelon-community/pyfmi/blob/master/src/pyfmi/fmi2.pyx"
    click FS4 "https://github.com/modelon-community/pyfmi/blob/master/src/pyfmi/fmi3.pyx"
    click C2 "https://github.com/modelon-community/pyfmi/tree/master/src/pyfmi/simulation"
    click C3 "https://github.com/modelon-community/pyfmi/blob/master/src/pyfmi/debug.py"
    click C4 "https://github.com/modelon-community/pyfmi/blob/master/src/pyfmi/fmi_algorithm_drivers.py"
    click U1 "https://github.com/modelon-community/pyfmi/tree/master/src/common"
    click U2 "https://github.com/modelon-community/pyfmi/tree/master/src/common/log"
    click U3 "https://github.com/modelon-community/pyfmi/blob/master/src/common/plotting/plot_gui.py"
    click E1 "https://github.com/modelon-community/pyfmi/tree/master/src/pyfmi/examples"
    click T "https://github.com/modelon-community/pyfmi/tree/master/tests"
    click D "https://github.com/modelon-community/pyfmi/tree/master/doc/sphinx"
```
