optivgi.scm.ev

Defines the Electric Vehicle (EV) data structure and related enums.

This module includes the EV dataclass, which stores all relevant information about a vehicle for scheduling purposes, and the ChargingRateUnit enum used to specify power units.

class optivgi.scm.ev.ChargingRateUnit(value)

Bases: Enum

Enum for charging rate units (Power or Current). All values represented in the algorithm and EV are in kW (not W) or A. This class can be used to convert this value to W or A for sending to the EVSE.

W = 'W'
A = 'A'
convert(value, unit, voltage=None)

Converts a power or current value from one unit to another.

Requires voltage for W <-> A conversion. Uses EVConstants.CHARGING_RATE_VOLTAGE as a default if voltage is not provided or is zero.

Parameters:

  • value (float) – The numerical value to convert.

  • from_unit – The unit of the input value (ChargingRateUnit.W or ChargingRateUnit.A).

  • voltage (Optional[float]) – The nominal voltage (in Volts) to use for conversion. If None or zero, EVConstants.CHARGING_RATE_VOLTAGE is used.

  • unit (Self)

Returns:

float – The converted value in the target unit (self).

Raises:

ValueError – If voltage is required for conversion but is not provided or is zero/negative.

class optivgi.scm.ev.EV(ev_id, active, station_id, connector_id, min_power, max_power, arrival_time, departure_time, energy, unit=ChargingRateUnit.W, voltage=240, power=<factory>)

Bases: object

Represents an Electric Vehicle and its charging requirements/constraints.

This dataclass holds both static information (ID, power limits, energy needs) and dynamic state (calculated power schedule).

Parameters:
ev_id: int

Unique identifier for the EV. This is used to track and manage the EV’s charging session and is essential for scheduling and reporting. It should be unique across all EVs in the system.

Type:

ev_id

active: bool

Indicates whether the EV is currently connected and actively participating in the charging session (True), or if it’s a future reservation/planned arrival (False). This is important for scheduling and resource allocation.

Type:

active

station_id: int

Identifier of the charging station the EV is connected to or assigned to. This is used for managing the charging session and sending the charging profile to the correct station.

Type:

station_id

connector_id: int

Identifier of the specific connector/outlet on the station.

Type:

connector_id

min_power: float

Minimum charging power (in kW or A, matching unit) required by the EV when charging. Can be 0 if supported by the EVSE.

Type:

min_power

max_power: float

Maximum charging power (in kW or A, matching unit) the EV or station connector can handle. This is the upper limit for the charging profile and should not be exceeded.

Type:

max_power

arrival_time: datetime

The datetime when the EV arrives or is expected to arrive.

Type:

arrival_time

departure_time: datetime

The datetime when the EV needs to be fully charged or will depart.

Type:

departure_time

energy: float

The amount of energy (in kWh or Ah, matching unit) required by the EV before departure.

Type:

energy

unit: ChargingRateUnit = 'W'

The physical unit (ChargingRateUnit.W or ChargingRateUnit.A) for min_power, max_power, and the calculated power list. Determines if energy is in kWh (for W) or Ah (for A). Defaults to Watts (W).

Type:

unit

voltage: float = 240

The nominal voltage (in Volts) at the connector. Used for W/A conversions if needed. Defaults to EVConstants.CHARGING_RATE_VOLTAGE.

Type:

voltage

power: list[float]

A list storing the calculated charging power (in the unit specified by self.unit) allocated to this EV for each time step defined by AlgorithmConstants.TIMESTEPS. Initialized to zeros. This list is populated by the SCM Algorithm.calculate() method. (repr=False to avoid overly long default string representation). The length of this list is equal to AlgorithmConstants.TIMESTEPS.

Type:

power

departure_index(now)

Calculates the index of the time step corresponding to the EV’s departure time.

The index is relative to the planning horizon starting at now. The result is clamped between 0 and AlgorithmConstants.TIMESTEPS - 1.

Parameters:

now (datetime) – The reference start time of the planning horizon.

Returns:

int – The integer index for the departure time step. Returns 0 if departure is before or at now.

arrival_index(now)

Calculates the index of the time step corresponding to the EV’s arrival time.

The index is relative to the planning horizon starting at now. The result is clamped between 0 and AlgorithmConstants.TIMESTEPS - 1.

Parameters:

now (datetime) – The reference start time of the planning horizon.

Returns:

int – The integer index for the arrival time step. Returns 0 if arrival is before or at now.

energy_charged()

Calculates the total energy scheduled to be delivered based on the power list.

Sums the power allocated in each time step and converts it to energy using AlgorithmConstants.POWER_ENERGY_FACTOR.

Returns:

float – The total calculated energy in kWh (if unit is W) or Ah (if unit is A).

current_charging_profile(now, unit=None)

Generates a charging profile dictionary containing only the power for the current time step.

This is suitable for systems requiring immediate power commands, conforming to a structure similar to OCPP’s SetChargingProfileRequest.

Parameters:

  • now (datetime) – The current time, used to set the profile’s start schedule time.

  • unit (Optional[ChargingRateUnit]) – The desired output unit (ChargingRateUnit.W or ChargingRateUnit.A) for the ‘limit’ value in the profile. If None, self.unit is used.

Returns:

dict – A dictionary representing the charging profile for the current time step. Returns an empty dictionary if the EV is not active or has no power scheduled now.

charging_profile(now, unit=None)

Generates the full charging profile dictionary over the entire planning horizon.

This compiles the calculated self.power list into a structure suitable for protocols like OCPP, including compression to reduce the number of periods where the power limit remains constant.

Parameters:

  • now (datetime) – The current time, used to set the profile’s start schedule time.

  • unit (Optional[ChargingRateUnit]) – The desired output unit (ChargingRateUnit.W or ChargingRateUnit.A) for the ‘limit’ values in the profile periods. If None, self.unit is used.

Returns:

dict – A dictionary representing the complete charging profile. Returns an empty dictionary if the EV has no power scheduled.