Dynamic Engine Efficiency - Engine Simulation Environment

A comprehensive Python-based engine simulation platform that models the interaction between internal combustion engine mechanical design, ECU control logic, and vehicle dynamics. This modular system enables accurate prediction of engine and vehicle performance through thermodynamic and kinematic calculations.

Features

• Comprehensive Engine Modeling: Mechanical architecture, thermodynamics, airflow, and friction
• ECU Control Simulation: Fuel, ignition, and boost control with 2D lookup tables
• Vehicle Dynamics: Drivetrain, aerodynamics, acceleration, and top speed calculations
• Dual Simulation Modes:
  • Static Analysis: Performance curves at discrete RPM points
  • Dynamic Simulation: Time-based transient effects and vehicle response
• Multiple Output Formats: Console output, CSV/JSON export, and matplotlib visualizations
• Configuration Flexibility: JSON/YAML files or programmatic Python API
• CLI and GUI Interfaces: Command-line tool and tkinter GUI for easy operation

Installation

Requirements

• Python 3.8+
• NumPy
• SciPy
• Matplotlib
• PyYAML
• Pandas
• Tabulate

Setup

1. Clone the repository:

git clone <repository-url>
cd Dynamic-Engine-Efficiency

2. Install dependencies:

pip install -r requirements.txt

Quick Start

CLI Usage

Run a static analysis on an example configuration:

python main.py config/examples/turbo_4cyl_engine.json --mode static

Run a dynamic simulation:

python main.py config/examples/turbo_4cyl_engine.json --mode dynamic --duration 30

Custom RPM range:

python main.py config/examples/na_4cyl_engine.json --rpm-min 2000 --rpm-max 6000 --rpm-step 50

GUI Usage

Launch the graphical interface:

python gui_interface.py

Programmatic API

from simulation import EngineSimulator
from output import Plotter, ConsoleOutput

# Load configuration
simulator = EngineSimulator.from_config_file("config/examples/turbo_4cyl_engine.json")

# Run static analysis
results, summary = simulator.run_static_analysis(min_rpm=1000, max_rpm=7000)

# Display results
console = ConsoleOutput()
console.print_static_results(results, summary)

# Generate plots
plotter = Plotter()
plotter.plot_performance_curves(results, show=True)

Configuration

Configuration File Format

Engines are configured using JSON or YAML files. Example structure:

{
  "engine": {
    "cylinder_count": 4,
    "bore_mm": 86.0,
    "stroke_mm": 86.0,
    "compression_ratio": 9.5,
    "valve_count_per_cylinder": 4,
    "cam_lift_mm": 9.5,
    "cam_duration_deg": 248,
    ...
  },
  "ecu": {
    "fuel": {
      "injector_flow_rate_ccmin": 440,
      "fuel_pressure_bar": 3.5,
      "afr_target_map": { ... }
    },
    "ignition": {
      "ignition_advance_map": { ... }
    },
    "boost": {
      "boost_target_psi": 18.0,
      "turbo_spool_rate_1s": 2.5,
      ...
    }
  },
  "vehicle": {
    "gear_ratios": [3.45, 2.10, 1.45, 1.10, 0.85, 0.68],
    "final_drive_ratio": 3.90,
    "drivetrain_loss_percent": 15,
    ...
  },
  "environment": {
    "ambient_temperature_c": 20,
    "barometric_pressure_kpa": 101.325,
    ...
  }
}

ECU Lookup Tables

ECU parameters (ignition timing, AFR, boost) use 2D lookup tables indexed by RPM and load:

{
  "afr_target_map": {
    "rpm_points": [1000, 2000, 3000, 4000, 5000, 6000, 7000],
    "load_points": [0.2, 0.4, 0.6, 0.8, 1.0],
    "values": [
      [14.7, 14.7, 14.5, 14.2, 13.8],
      [14.7, 14.5, 14.2, 13.8, 13.5],
      ...
    ]
  }
}

Bilinear interpolation is used for intermediate values.

Architecture

Core Modules

• Config (config/): Configuration classes and file loaders
• Engine (engine/): Thermodynamics, mechanical calculations, friction, airflow
• ECU (ecu/): Fuel control, ignition control, boost control, sensors, PID controllers
• Vehicle (vehicle/): Drivetrain, aerodynamics, acceleration, top speed
• Simulation (simulation/): Static analyzer, dynamic simulator, coordinator
• Output (output/): Plotting, data export, console output

Key Formulas

The system implements formulas from the reference documentation (Section 6):

• Indicated Torque: (IMEP × Displacement × Cylinders) / (4π)
• Brake Torque: Indicated Torque × (1 - Friction Loss)
• Power: Torque × RPM × (2π / 60)
• BSFC: Fuel Flow / Power
• Volumetric Efficiency: Actual Airflow / Theoretical Airflow
• Boost Pressure: MAP - Ambient Pressure
• Drag Force: 0.5 × ρ × Cd × A × v²
• Wheel Torque: Engine Torque × Gear × Final Drive × (1 - Loss)
• Acceleration: (Wheel Torque / Tire Radius) / Mass - (Drag + Rolling) / Mass
• Top Speed: Solve Power = Drag × Velocity

Examples

Pre-configured examples are available in config/examples/:

• turbo_4cyl_engine.json: Turbocharged 4-cylinder engine
• na_4cyl_engine.json: Naturally aspirated 4-cylinder engine

Run examples:

python examples/run_examples.py

Output

Static Analysis

• Console: Formatted tables and performance summary
• Plots:
  • Torque and power curves
  • Efficiency metrics (BSFC, thermal efficiency, VE)
  • ECU control parameters (AFR, ignition timing, boost)
• Data Export: CSV and JSON files with all calculated parameters

Dynamic Simulation

• Console: Time series summary and key metrics
• Plots:
  • RPM, vehicle speed, boost pressure vs time
  • Power, acceleration vs time
  • AFR and knock vs time
• Data Export: CSV time series data

Advanced Features

Transient Effects

Dynamic simulations model:

• Turbo spool rate and boost response
• Thermal buildup (coolant, intake temperature)
• Closed-loop AFR correction
• Knock detection and retard

Vehicle Dynamics

• Multi-gear acceleration analysis
• Optimal shift RPM calculation
• Top speed equilibrium solver
• Rolling resistance and aerodynamic drag

ECU Logic

• 2D lookup table interpolation (bilinear)
• Knock threshold and retard mapping
• Wastegate control
• Closed-loop PID control (extensible)

API Reference

Main Classes

EngineSimulator

Main simulation coordinator.

# Load from file
simulator = EngineSimulator.from_config_file("config.json")

# Run static analysis
results, summary = simulator.run_static_analysis(min_rpm=1000, max_rpm=7000)

# Run dynamic simulation
history, metrics = simulator.run_dynamic_simulation(mode="full_throttle_pull", duration_s=30)

StaticAnalyzer

Performance analysis at discrete RPM points.

analyzer = StaticAnalyzer(engine_config, ecu_config, vehicle_config, environment_config)

# Analyze single RPM point
result = analyzer.analyze_rpm_point(rpm=5000, throttle_position=1.0, gear=3)

# Sweep RPM range
results = analyzer.sweep_rpm_range(min_rpm=1000, max_rpm=7000, rpm_step=100)

DynamicSimulator

Time-based simulation with transient effects.

simulator = DynamicSimulator(static_analyzer)

# Full throttle pull
history = simulator.simulate_scenario(SimulationMode.FULL_THROTTLE_PULL, duration_s=30)

# Launch control
history = simulator.simulate_launch_control(hold_rpm=3500, duration_s=5)

Configuration Classes

All configurations are dataclasses with validation:

• EngineConfig: Mechanical parameters
• ECUConfig: Control parameters
• VehicleConfig: Drivetrain and vehicle specs
• EnvironmentConfig: Ambient conditions

Contributing

Contributions welcome! Please ensure:

• Code follows PEP 8 style guidelines
• New features include tests
• Documentation is updated
• Changes are backward compatible where possible

License

[Add license information]

References

This simulation system implements formulas and relationships from:

• Internal combustion engine thermodynamics
• ECU control strategy principles
• Vehicle dynamics and aerodynamics
• Reference documentation: documentation/ECU/README.md

Acknowledgements

• Classic engine simulation principles
• Modern ECU tuning practices
• Thermodynamic modeling research