Interface

This module contains methods for directly interacting with the _simulator.

class acnportal.acnsim.interface.Constraint(constraint_matrix, magnitudes, constraint_index, evse_index)

constraint_index

Alias for field number 2

constraint_matrix

Alias for field number 0

evse_index

Alias for field number 3

magnitudes

Alias for field number 1

class acnportal.acnsim.interface.InfrastructureInfo(constraint_matrix: numpy.ndarray, constraint_limits: numpy.ndarray, phases: numpy.ndarray, voltages: numpy.ndarray, constraint_ids: List[str], station_ids: List[str], max_pilot: numpy.ndarray, min_pilot: numpy.ndarray, allowable_pilots: Optional[List[numpy.ndarray]] = None, is_continuous: Optional[numpy.ndarray] = None)

Class to store information about the electrical infrastructure.

Parameters:

• constraint_matrix (np.array[float]) – M x N array relating the individual station currents to aggregate currents each of which is subject to a constraint. M is the number of constraints and N is the number of stations.
• constraint_limits (np.array[float]) – Limits on each constrained link. Length M.
• phases (np.array[float]) – Phase angle of the current at each station (EVSE). Length N. [deg]
• voltages (np.array[float]) – Voltage of each station. Length N. [V]
• constraint_ids (List[str]) – Unique identifier of each constraint.
• station_ids (List[str]) – Unique identifier of each station.
• (np.array[float] (min_pilot) – Maximum pilot signal supported by each station.
• (np.array[float] – Minimum pilot signal supported by each station. A non-zero min_pilot indicates that the station does not support any charging rates between 0 and min_pilot. It is implied that all EVSEs support a pilot signal of 0, even if min_pilot > 0.
• allowable_pilots (List[np.array[float]) – Pilot signals which each station supports. The allowable pilot signals for station i are stored in allowable_pilots[i]. If a station supports continuous pilot signals, the list is of length 2, where the first value is the lower bound on the continuous interval and the second is the upper bound. In continuous case, it is implied that all EVSEs support a pilot signal of 0, even if the continuous interval does not include 0.
• is_continuous (np.array[bool]) – True if a station supports continuous pilot signals, False otherwise.

get_station_index(station_id: str) → int

Get the numerical index of a given station_id in the network.

num_stations

Return total number of stations in this network.

class acnportal.acnsim.interface.Interface(simulator: Simulator)

Interface between algorithms and the ACN Simulation Environment.

active_evs

Returns a list of active EVs for use by the algorithm.

Returns:List of EVs currently plugged in and not finished. Return type:List[EV]

active_sessions() → List[acnportal.acnsim.interface.SessionInfo]

Return a copy of the list of SessionInfo objects describing the currently

charging EVs.

Returns:List of currently active charging sessions. Return type:List[SessionInfo]

allowable_pilot_signals(station_id: str) → Tuple[bool, List[float]]

Returns the allowable pilot signal levels for the specified EVSE. One may assume an EVSE pilot signal of 0 is allowed regardless of this function’s return values.

Parameters:station_id (str) – The ID of the station for which the allowable rates should be returned. Returns:If the range is continuous or not list[float]: The sorted set of acceptable pilot signals. If continuous this

range will have 2 values the min and the max acceptable values. [A]

Return type:bool

current_datetime

Get the simulated wall time of the simulator.

Returns:

The datetime corresponding to the current time step of

the simulator.

Return type:datetime

current_time

Get the current time (the current _iteration) of the simulator.

Returns:The current _iteration of the simulator. Return type:int

evse_phase(station_id: str) → float

Returns the phase angle of the EVSE.

Parameters:station_id (str) – The ID of the station. Returns:phase angle of the EVSE. [degrees] Return type:float

evse_voltage(station_id: str) → float

Returns the voltage of the EVSE.

Parameters:station_id (str) – The ID of the station. Returns:voltage of the EVSE. [V] Return type:float

get_constraints() → acnportal.acnsim.interface.Constraint

Get the constraint matrix and corresponding EVSE ids for the network.

Returns:

namedtuple including the following attributes:

constraint_matrix (np.ndarray): Matrix representing the constraints

of the network. Each row is a constraint and each column is an index.

constraint_limits (np.ndarray): Vector of bounding limits for each

constraint (1 for each constraint).

constraint_ids (List[str]): Names of each constraint. station_ids (List[str]): Names of each station.

Return type:Constraint

get_demand_charge(start: Optional[int] = None) → float

Get the demand charge for the given period. ($/kW)

Parameters:start (int) – Time step of the simulation where price vector should begin. If None, uses the current timestep of the simulation. Default None. Returns:Demand charge for the given period. ($/kW) Return type:float

get_prev_peak() → float

Get the highest aggregate peak demand so far in the simulation.

Returns:Peak demand so far in the simulation. (A) Return type:float

get_prices(length: int, start: Optional[int] = None) → numpy.ndarray

Get a vector of prices beginning at time start and continuing for length periods. ($/kWh)

Parameters:

• length (int) – Number of elements in the prices vector. One entry per period.
• start (int) – Time step of the simulation where price vector should begin. If None, uses the current timestep of the simulation. Default None.

Returns:

Array of floats where each entry is the price for the

corresponding period. ($/kWh)

Return type:

np.ndarray[float]

infrastructure_info() → acnportal.acnsim.interface.InfrastructureInfo

Returns a copy of the InfrastructureInfo object generated from interface.

Returns:A description of the charging infrastructure. Return type:InfrastructureInfo

is_feasible(load_currents: Dict[str, List[float]], linear: bool = False, violation_tolerance: Optional[float] = None, relative_tolerance: Optional[float] = None) → bool

Return if a set of current magnitudes for each load are feasible.

Wraps Network’s is_feasible method.

For a given constraint, the larger of the violation_tolerance and relative_tolerance is used to evaluate feasibility.

Parameters:

• load_currents (Dict[str, List[number]]) – Dictionary mapping load_ids to schedules of charging rates.
• linear (bool) – If True, linearize all constraints to a more conservative but easier to compute constraint by ignoring the phase angle and taking the absolute value of all load coefficients. Default False.
• violation_tolerance (float) – Absolute amount by which schedule may violate network constraints. Default None, in which case the network’s violation_tolerance attribute is used.
• relative_tolerance (float) – Relative amount by which schedule may violate network constraints. Default None, in which case the network’s relative_tolerance attribute is used.

Returns:

If load_currents is feasible at time t according to this set of

constraints.

Return type:

bool

last_actual_charging_rate

Return the actual charging rates in the last period for all

active sessions.

Returns:

A dictionary with the session ID as key and actual

charging rate as value.

Return type:Dict[str, number]

last_applied_pilot_signals

Return the pilot signals that were applied in the last _iteration

of the simulation for all active EVs.

Does not include EVs that arrived in the current _iteration.

Returns:

A dictionary with the session ID as key and the

pilot signal as value.

Return type:Dict[str, float]

max_pilot_signal(station_id: str) → float

Returns the maximum allowable pilot signal level for the specified EVSE.

Parameters:station_id (str) – The ID of the station. Returns:the maximum pilot signal supported by this EVSE. [A] Return type:float

max_recompute_time

Return the maximum recompute time of the simulator.

Returns:

Maximum recompute time of the simulation in number of periods.

[periods]

Return type:int

min_pilot_signal(station_id: str) → float

Returns the minimum allowable pilot signal level for the EVSE. A zero pilot signal is always assumed to be allowed; the minimum allowable pilot signal returned here is the minimum nonzero pilot signal allowed by the EVSE if said EVSE is non-continuous.

Parameters:station_id (str) – The ID of the station. Returns:the minimum pilot signal supported by this EVSE. [A] Return type:float

period

Return the length of each timestep in the simulation.

Returns:Length of each time interval in the simulation. [minutes] Return type:float

remaining_amp_periods(ev: acnportal.acnsim.interface.SessionInfo) → float

Return the EV’s remaining demand in A*periods.

Parameters:ev (SessionInfo) – The SessionInfo object for which to get remaining demand. Returns:the EV’s remaining demand in A*periods. Return type:float

exception acnportal.acnsim.interface.InvalidScheduleError

Raised when the schedule passed to the simulator is invalid.

class acnportal.acnsim.interface.SessionInfo(station_id: str, session_id: str, requested_energy: float, energy_delivered: float, arrival: int, departure: int, estimated_departure: Optional[int] = None, current_time: int = 0, min_rates: Union[float, List[float]] = 0, max_rates: Union[float, List[float]] = inf)

Class to store information relevant to a charging session.

Parameters:

• station_id (str) – Unique identifier of the station (EVSE) where the session takes place.
• session_id (str) – Unique identifier of the charging session.
• requested_energy (float) – Energy requested by the user during the session. [kWh]
• energy_delivered (float) – Energy delivered already during the session. [kWh]
• arrival (int) – Time index when the session begins.
• departure (int) – Time index when the session ends.
• estimated_departure (int) – Time index when the user estimates the session will end.
• current_time (int) – Time index of the current time.
• min_rates (Union[float, List[float]) – Lower bound for the charging rate of the session. If List (or np.array) length should be departure - arrival and each entry is a lower bound for the corresponding time period.
• max_rates (Union[float, List[float]) – Upper bound for the charging rate of the session. If List (or np.array) length should be departure - arrival and each entry is a upper bound for the corresponding time period.

arrival_offset

Return the time (in periods) until the arrival of the EV represented by this Session, or 0 if the EV has already arrived.

remaining_demand

Return the Session’s remaining demand in kWh.

remaining_time

Return the time remaining until the EV represented by this Session departs, or the time between the EV’s departure and arrival if the EV has not arrived yet. If the EV has already departed, return 0.