How ryan-rudd/dynamic-engine-efficiency works
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).