# m0in92/ev_sim architecture

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

- Interactive diagram: https://gitdiagram.com/m0in92/ev_sim
- Repository: https://github.com/m0in92/ev_sim

## Overview

##### Main Components
- Core Simulation Engine (EV_sim)
- Contains the simulation classes (such as EV, DriveCycle, ExternalConditions, and VehicleDynamics) along with the simulation engine logic.
- Manages the computational methods derived from Gillespie and Plett for calculating motor power and vehicle dynamics.
- Data Management
- EV and drive cycle data are stored in CSV and text files under the EV_sim/data directory.
- A separate “reference” folder stores additional vehicle parameter reference data.
- Configuration and Utilities
- The EV_sim/config directory provides necessary configuration definitions.
- Utility modules (e.g., EV_sim/utils) include helper functions for timing, constants, and getting database info.
- Graphical User Interfaces
- Tkinter-based GUIs are provided in EV_sim/tkinter_gui (and the depreciated version, EV_sim/tkinter_gui_depreciated).
- Web Application (Django)
- The django_app and django_project directories host a Django application with models, views, and templates to provide an alternative web-accessible interface.
- Testing and Examples
- The tests directory has unit tests to verify simulation correctness.
- The examples directory shows use-case scripts demonstrating how to run simulations using different EVs and drive cycles.

##### Relationships and Interactions
- The user (or an API consumer) will interact with the simulation engine via one of several frontends:
- For desktop GUI interactions, the Tkinter GUI interfaces since invoked by “python -m EV_sim”.
- For web interactions, the Django app serves front-end requests.
- For programmatic use, users import the EV_sim package directly.
- Each of these interfaces triggers the simulation process, which involves:
a. Instantiating core classes (EV, DriveCycle, ExternalConditions).
b. Fetching necessary data from CSV files and reference directories.
c. Running simulation logic in the VehicleDynamics (or similar) module to compute model outputs.
- Utility modules and configuration files support every stage by providing common constants, settings, and helper functionalities.

##### Architectural Patterns and Design Principles
- Modularity: The project is organized into self-contained modules (simulation engine, data handling, GUIs, and Django) that interact via clearly defined interfaces.
- Separation of Concerns: Data handling, computational simulation logic, and user interface code are well separated to facilitate maintainability and extensibility.
- Multi-front-end Support: The design allows for multiple UIs (Graphical desktop via Tkinter and web via Django) to invoke the same core simulation logic.
- Extensibility: Examples and tests indicate the design is structured to allow easy addition of new drive cycles, vehicle types, or even a new user interface.

##### Relevant Technologies, Frameworks, and Libraries
- Python as the core language.
- Tkinter for the desktop GUI.
- Django for the web application.
- CSV file processing for loading drive cycle and vehicle data.
- Standard libraries for configuration and utilities.
- Testing frameworks as shown in the tests directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User/API Consumer"]:::user
    DesktopGUI["Desktop GUI (Tkinter)"]:::gui
    WebFrontend["Web Frontend (Django)"]:::web
    ProgrammaticAPI["Programmatic API"]:::api

    %% User Interfaces and their interactions with Simulation Engine
    User -->|"interacts"| DesktopGUI
    User -->|"interacts"| WebFrontend
    User -->|"calls"| ProgrammaticAPI

    DesktopGUI -->|"triggers"| EVCore["EV_sim Core"]:::core
    WebFrontend -->|"triggers"| EVCore
    ProgrammaticAPI -->|"accesses"| EVCore

    %% Core Simulation Components
    subgraph "Core Simulation Components"
        direction TB
        EV["EV Class"]:::coreFile
        DriveCycle["DriveCycle Module"]:::coreFile
        ExtCond["ExternalConditions Module"]:::coreFile
        Model["VehicleDynamics/Model"]:::coreFile
        Sol["Solution Module"]:::coreFile
    end
    %% Link Core Simulation Components to Main Core Node
    EVCore -->|"includes"| EV
    EVCore -->|"includes"| DriveCycle
    EVCore -->|"includes"| ExtCond
    EVCore -->|"includes"| Model
    EVCore -->|"includes"| Sol

    %% Data Management
    subgraph "Data Management"
        direction TB
        EVData["EV Data (CSV)"]:::dataFile
        DCData["Drive Cycle Data"]:::dataFile
        RefData["Reference Data"]:::dataFile
    end
    EVCore -->|"loads"| EVData
    EVCore -->|"loads"| DCData
    EVCore -->|"loads"| RefData

    %% Configuration and Utilities
    subgraph "Configuration & Utilities"
        direction TB
        ConfigDef["Configuration (definitions)"]:::config
        Utilities["Utilities Module"]:::utils
        subgraph "Utilities Details"
            direction TB
            Constants["Constants"]:::utilsFile
            GetDB["GetDB Info"]:::utilsFile
            Timer["Timer"]:::utilsFile
        end
    end
    EVCore -->|"uses"| ConfigDef
    EVCore -->|"uses"| Utilities

    %% Desktop GUI Components (Tkinter)
    subgraph "Desktop GUI Components"
        direction TB
        TkinterMain["Main Tkinter GUI"]:::guiFile
        TkinterLegacy["Legacy Tkinter GUI"]:::guiFile
    end
    DesktopGUI -->|"comprises"| TkinterMain
    DesktopGUI -->|"comprises"| TkinterLegacy

    %% Web Application Components (Django)
    subgraph "Django Components"
        direction TB
        DjangoApp["Django App"]:::webFile
        DjangoProject["Django Project"]:::webFile
    end
    WebFrontend -->|"comprises"| DjangoApp
    WebFrontend -->|"comprises"| DjangoProject

    %% Testing and Examples
    subgraph "Testing & Examples"
        direction TB
        Testing["Unit Tests"]:::testFile
        Examples["Example Scripts"]:::testFile
    end
    EVCore -->|"validated_by"| Testing
    EVCore -->|"demonstrated_by"| Examples

    %% Click Events for Core Simulation Engine Files
    click EV "https://github.com/m0in92/ev_sim/blob/main/EV_sim/ev.py"
    click DriveCycle "https://github.com/m0in92/ev_sim/blob/main/EV_sim/drivecycles.py"
    click ExtCond "https://github.com/m0in92/ev_sim/blob/main/EV_sim/extern_conditions.py"
    click Model "https://github.com/m0in92/ev_sim/blob/main/EV_sim/model.py"
    click Sol "https://github.com/m0in92/ev_sim/blob/main/EV_sim/sol.py"

    %% Click Events for Data Management
    click EVData "https://github.com/m0in92/ev_sim/tree/main/EV_sim/data/EV"
    click DCData "https://github.com/m0in92/ev_sim/tree/main/EV_sim/data/drive_cycles"
    click RefData "https://github.com/m0in92/ev_sim/tree/main/EV_sim/data/reference"

    %% Click Event for Configuration
    click ConfigDef "https://github.com/m0in92/ev_sim/blob/main/EV_sim/config/definations.py"

    %% Click Events for Utilities
    click Constants "https://github.com/m0in92/ev_sim/blob/main/EV_sim/utils/constants.py"
    click GetDB "https://github.com/m0in92/ev_sim/blob/main/EV_sim/utils/get_database_info.py"
    click Timer "https://github.com/m0in92/ev_sim/blob/main/EV_sim/utils/timer.py"

    %% Click Events for Desktop GUI
    click TkinterMain "https://github.com/m0in92/ev_sim/tree/main/EV_sim/tkinter_gui"
    click TkinterLegacy "https://github.com/m0in92/ev_sim/tree/main/EV_sim/tkinter_gui_depreciated"

    %% Click Events for Web Application
    click DjangoApp "https://github.com/m0in92/ev_sim/tree/main/django_app"
    click DjangoProject "https://github.com/m0in92/ev_sim/tree/main/django_project"

    %% Click Events for Testing and Examples
    click Testing "https://github.com/m0in92/ev_sim/tree/main/tests"
    click Examples "https://github.com/m0in92/ev_sim/tree/main/examples"

    %% Styles
    classDef user fill:#FFCCCC,stroke:#990000,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef coreFile fill:#87CEEB,stroke:#4682B4,stroke-width:1px;
    classDef dataFile fill:#D3D3D3,stroke:#696969,stroke-width:1px;
    classDef config fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef utils fill:#E0FFFF,stroke:#008B8B,stroke-width:2px;
    classDef utilsFile fill:#AFEEEE,stroke:#20B2AA,stroke-width:1px;
    classDef gui fill:#98FB98,stroke:#006400,stroke-width:2px;
    classDef guiFile fill:#90EE90,stroke:#32CD32,stroke-width:1px;
    classDef web fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
    classDef webFile fill:#FFB6C1,stroke:#FF1493,stroke-width:1px;
    classDef testFile fill:#D8BFD8,stroke:#8B008B,stroke-width:2px;
    classDef api fill:#FFD700,stroke:#B8860B,stroke-width:2px;
```
