# ryan-rudd/dynamic-engine-efficiency architecture

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

- Interactive diagram: https://gitdiagram.com/ryan-rudd/dynamic-engine-efficiency
- Repository: https://github.com/ryan-rudd/dynamic-engine-efficiency

## Overview

##### Project Type and Purpose
- This is an open-source, modular Python engine-and-vehicle simulation platform (“Dynamic Engine Efficiency”) providing both CLI and GUI interfaces.
- Purpose: load engine/ECU/vehicle/environment configurations, run static or dynamic simulations, then export or plot results.

A. Entry Points
- main.py (CLI controller)
- gui_interface.py (Tkinter GUI controller)
- examples/run_examples.py (batch runner)
B. Configuration Layer
- config_loader (parses JSON/YAML)
- Config classes: EngineConfig, ECUConfig, VehicleConfig, EnvironmentConfig
- config/examples (pre-built JSON files)
C. Core Simulation Modules
1. Engine Modeling (`engine/`):
- thermodynamics.py, mechanical.py, airflow.py, friction_model.py
2. ECU Control (`ecu/`):
- fuel_control.py, ignition_control.py, boost_control.py, sensors.py, pid_controller.py, lookup_tables.py
3. Vehicle Dynamics (`vehicle/`):
- drivetrain.py, aerodynamics.py, acceleration.py, top_speed.py
D. Simulation Orchestration (`simulation/` and `engine_sim/`)
- StaticAnalyzer (discrete RPM sweep)
- DynamicSimulator (time-based transient)
- EngineSimulator (factory, coordinator)
E. Output Layer (`output/`)
- ConsoleOutput (tabulated CLI)
- Plotter (matplotlib graphs)
- DataExporter (CSV/JSON via pandas)
F. External Dependencies
- NumPy, SciPy, Matplotlib, Pandas, PyYAML

##### Relationships & Data Flow
1. User invokes CLI or GUI → Controller reads command/parameters.
2. Controller calls ConfigLoader → instantiates config objects.
3. Configs passed to EngineSimulator.from_config → returns a simulator instance.
4. User selects mode:
a. Static mode → `simulator.run_static_analysis()` → StaticAnalyzer uses Engine, ECU, Vehicle, Environment modules → returns results & summary.
b. Dynamic mode → `simulator.run_dynamic_simulation()` → DynamicSimulator & engine_sim internals → returns time series history & metrics.
5. Results handed to Output components → printed to console, exported to files, or plotted.
6. (Optional) examples/run_examples.py orchestrates multiple runs and generates standardized outputs.

##### Architectural Patterns & Principles
- Modular Layering: clear separation of configuration, domain logic (engine/ECU/vehicle), orchestration, and presentation.
- Factory Method (EngineSimulator.from_config_file).
- Strategy Pattern: StaticAnalyzer vs DynamicSimulator for different simulation modes.
- Data-Driven Design: JSON/YAML config + 2D lookup tables for ECU maps → enables extensibility.
- Single Responsibility: each module has a focused purpose (e.g., friction_model only handles friction calculations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        CLI["main.py"]:::entry
        GUI["gui_interface.py"]:::entry
        EXAMPLES["examples/run_examples.py"]:::entry
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        ConfigLoader[(config_loader)]:::config
        EngConf[(EngineConfig)]:::config
        ECUConf[(ECUConfig)]:::config
        VehConf[(VehicleConfig)]:::config
        EnvConf[(EnvironmentConfig)]:::config
        Example1[(na_4cyl_engine.json)]:::config
        Example2[(turbo_4cyl_engine.json)]:::config
    end

    %% Core Simulation Modules
    subgraph "Core Simulation Modules"
        subgraph "Engine Modeling"
            thermo["thermodynamics.py"]:::core
            mech["mechanical.py"]:::core
            air["airflow.py"]:::core
            friction["friction_model.py"]:::core
        end
        subgraph "ECU Control"
            fuel["fuel_control.py"]:::core
            ign["ignition_control.py"]:::core
            boost["boost_control.py"]:::core
            sensors["sensors.py"]:::core
            pid["pid_controller.py"]:::core
            lt["lookup_tables.py"]:::core
        end
        subgraph "Vehicle Dynamics"
            drivetrain["drivetrain.py"]:::core
            aero["aerodynamics.py"]:::core
            accel["acceleration.py"]:::core
            top["top_speed.py"]:::core
        end
    end

    %% Simulation Orchestration
    subgraph "Simulation Orchestration"
        Static["static_analyzer.py"]:::orchestration
        Dynamic["dynamic_simulator.py"]:::orchestration
        EngineSim["engine_simulator.py"]:::orchestration
        Util["engine_sim/__init__.py"]:::orchestration
    end

    %% Output Layer
    subgraph "Output Layer"
        Console["console_output.py"]:::output
        Plotter["plotter.py"]:::output
        DataExp["data_exporter.py"]:::output
    end

    %% External Dependencies
    NumPy((NumPy)):::external
    SciPy((SciPy)):::external
    Matplotlib((Matplotlib)):::external
    Pandas((Pandas)):::external
    PyYAML((PyYAML)):::external

    %% Data Flows
    CLI -->|"commands"| ConfigLoader
    GUI -->|"commands"| ConfigLoader
    EXAMPLES -->|"batch commands"| ConfigLoader

    Example1 -->|"file input"| ConfigLoader
    Example2 -->|"file input"| ConfigLoader

    ConfigLoader -->|"Config Objects"| EngineSim
    EngConf -->|"config"| EngineSim
    ECUConf -->|"config"| EngineSim
    VehConf -->|"config"| EngineSim
    EnvConf -->|"config"| EngineSim

    EngineSim -->|"static_mode"| Static
    EngineSim -->|"dynamic_mode"| Dynamic
    Util -->|"utilities"| Dynamic

    Static -->|"Results & Summary"| Console
    Static -->|"Results & Summary"| DataExp
    Static -->|"Results & Summary"| Plotter

    Dynamic -->|"Time Series"| Console
    Dynamic -->|"Time Series"| DataExp
    Dynamic -->|"Time Series"| Plotter

    Static -->|"uses"| thermo
    Static -->|"uses"| mech
    Static -->|"uses"| air
    Static -->|"uses"| friction
    Static -->|"uses"| fuel
    Static -->|"uses"| ign
    Static -->|"uses"| boost
    Static -->|"uses"| sensors
    Static -->|"uses"| pid
    Static -->|"uses"| lt
    Static -->|"uses"| drivetrain
    Static -->|"uses"| aero
    Static -->|"uses"| accel
    Static -->|"uses"| top

    %% External Integrations
    thermo --> NumPy
    mech --> NumPy
    air --> SciPy
    friction --> NumPy
    pid --> NumPy
    lt --> PyYAML
    Plotter --> Matplotlib
    DataExp --> Pandas
    ConfigLoader --> PyYAML

    %% Click Events
    click CLI "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/main.py"
    click GUI "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/gui_interface.py"
    click EXAMPLES "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/examples/run_examples.py"
    click ConfigLoader "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/config_loader.py"
    click EngConf "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/engine_config.py"
    click ECUConf "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/ecu_config.py"
    click VehConf "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/vehicle_config.py"
    click EnvConf "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/environment_config.py"
    click Example1 "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/examples/na_4cyl_engine.json"
    click Example2 "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/config/examples/turbo_4cyl_engine.json"
    click thermo "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/engine/thermodynamics.py"
    click mech "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/engine/mechanical.py"
    click air "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/engine/airflow.py"
    click friction "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/engine/friction_model.py"
    click fuel "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/ecu/fuel_control.py"
    click ign "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/ecu/ignition_control.py"
    click boost "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/ecu/boost_control.py"
    click sensors "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/ecu/sensors.py"
    click pid "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/ecu/pid_controller.py"
    click lt "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/ecu/lookup_tables.py"
    click drivetrain "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/vehicle/drivetrain.py"
    click aero "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/vehicle/aerodynamics.py"
    click accel "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/vehicle/acceleration.py"
    click top "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/vehicle/top_speed.py"
    click Static "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/simulation/static_analyzer.py"
    click Dynamic "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/simulation/dynamic_simulator.py"
    click EngineSim "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/simulation/engine_simulator.py"
    click Util "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/engine_sim/__init__.py"
    click Console "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/output/console_output.py"
    click Plotter "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/output/plotter.py"
    click DataExp "https://github.com/ryan-rudd/dynamic-engine-efficiency/blob/main/output/data_exporter.py"

    %% Styles
    classDef entry fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:1px,shape:cylinder
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external stroke-dasharray: 5 5,fill:#fff,stroke:#333
```
