Models¶

Battery¶

class acnportal.acnsim.models.battery.Battery(capacity, init_charge, max_power)¶

This class models the behavior of a battery and battery management system (BMS).

Parameters:	capacity (float) – Capacity of the battery [kWh] init_charge (float) – Initial charge of the battery [kWh] max_power (float) – Maximum charging rate of the battery [kW]

charge(pilot, voltage, period)¶

Method to “charge” the battery

Parameters:	pilot (float) – Pilot signal passed to the battery. [A] voltage (float) – AC voltage provided to the battery charger. [V] period (float) – Length of the charging period. [minutes]
Returns:	actual charging rate of the battery. [A]
Return type:	float
Raises:	`ValueError` – if voltage or period are <= 0.

current_charging_power¶: Returns the current draw of the battery on the AC side.

max_charging_power¶: Returns the maximum charging power of the Battery.

reset(init_charge=None)¶

Reset battery to initial state. If init_charge is not given (is None), the battery is reset to its initial charge on initialization.

Parameters:	init_charge (float) – charge battery should be reset to. [acnsim units]
Returns:	None

class acnportal.acnsim.models.battery.Linear2StageBattery(capacity, init_charge, max_power, noise_level=0, transition_soc=0.8, charge_calculation='continuous')¶

Extends Battery with a simple piecewise linear model of battery dynamics based on SoC.

Battery model based on a piecewise linear approximation of battery behavior. The battery will charge at the minimum of max_rate and the pilot until it reaches _transition_soc. After this, the maximum charging rate of the battery will decrease linearly to 0 at 100% state of charge.

For more info on model: https://www.sciencedirect.com/science/article/pii/S0378775316317396

All public attributes are the same as Battery.

Parameters:

noise_level (float) – Standard deviation of the noise to add to the charging process. (kW)
transition_soc (float) – State of charging when transitioning from constant current to constraint voltage.
charge_calculation (str) –
If ‘stepwise’, use the charging method from a previous version of acnportal, which assumes a constant maximal charging rate for the entire timestep during which the pilot signal is input. This charging method is less accurate than the _charge method, and should only be used for reproducing results from older versions of acnportal.

If ‘continuous’ or not provided, use the _charge method, which assumes a continuously varying maximal charging rate.

charge(pilot, voltage, period)¶

Method to “charge” the battery based on a two-stage linear battery model.

Uses one of {_charge, _charge_stepwise} to charge the battery depending on the value of the charge_calculation attribute of this object.

acnportal.acnsim.models.battery.batt_cap_fn(requested_energy, stay_dur, voltage, period)¶

This function takes as input a requested energy, stay duration, and measurement parameters (voltage & period) and calculates the minimum capacity linear 2 stage battery such that it is feasible to deliver requested_energy in stay_dur periods.

The function returns this minimum total capacity along with an initial capacity, which is the maximum initial capacity the battery with given total capacity may have such that it is feasible (after charging at max rate) to deliver requested_energy in stay_dur periods. Thus, the returned total and initial capacities maximize the amount of time the battery behaves non-ideally during charging.

Parameters:	requested_energy (float) – Energy requested by this EV. If this fit uses data from ACN-Data, this requested_energy is the amount of energy actually delivered in real life. stay_dur (float) – Number of periods the EV stayed. voltage (float) – Voltage at which the battery is charged (V). period (float) – Number of minutes in a period (minutes).

EV¶

class acnportal.acnsim.models.ev.EV(arrival, departure, requested_energy, station_id, session_id, battery, estimated_departure=None)¶

Class to model the behavior of an Electrical Vehicle (ev).

Parameters:

arrival (int) – Arrival time of the ev. [periods]
departure (int) – Departure time of the ev. [periods]
requested_energy (float) – Energy requested by the ev on arrival. [kWh]
station_id (str) – Identifier of the station used by this ev.
session_id (str) – Identifier of the session belonging to this ev.
battery (Battery-like) – Battery object to be used by the EV.

arrival¶: Return the arrival time of the EV.

charge(pilot, voltage, period)¶

Method to “charge” the ev.

Parameters:	pilot (float) – Pilot signal passed to the battery. [A] voltage (float) – AC voltage provided to the battery charger. [V] period (float) – Length of the charging period. [minutes]
Returns:	Actual charging rate of the ev. [A]
Return type:	float

current_charging_rate¶: Return the current charging rate of the EV. (float)

departure¶: Return the departure time of the EV. (int)

energy_delivered¶: Return the total energy delivered so far in this charging session. (float)

estimated_departure¶: Return the estimated departure time of the EV.

fully_charged¶: Return True if the EV’s demand has been fully met. (bool)

maximum_charging_power¶: Return the maximum charging power of the battery.

percent_remaining¶

Return the percent of demand which still needs to be fulfilled. (float)

Defined as the ratio of remaining demand and requested energy.

remaining_demand¶

Return the remaining energy demand of this session. (float)

Defined as the difference between the requested energy of the session and the energy delivered so far.

requested_energy¶: Return the energy request of the EV for this session. (float) [acnsim units].

reset()¶

Reset battery back to its initialization. Also reset energy delivered.

Returns:	None.

session_id¶: Return the unique session identifier for this charging session. (str)

station_id¶: Return the unique identifier for the EVSE used for this charging session.

update_station_id(station_id)¶: Method to update the station where EV will charge.

EVSE¶

class acnportal.acnsim.models.evse.BaseEVSE(station_id)¶

Abstract base class to model Electric Vehicle Supply Equipment (charging station). This class is meant to be inherited from to implement new EVSEs.

Subclasses must implement the max_rate, allowable_pilot_signals, and _valid_rate methods.

_station_id¶

Unique identifier of the EVSE.

Type:	str

_ev¶

EV currently connected the the EVSE.

Type:	EV

_current_pilot¶

Pilot signal for the current time step. [acnsim units]

Type:	float

is_continuous¶

If True, this EVSE accepts a continuous range of pilot signals. If False, this EVSE accepts only a discrete set of pilot signals.

Type:	bool

allowable_pilot_signals¶

Returns the allowable pilot signal levels for this EVSE.

NOT IMPLEMENTED IN BaseEVSE. This method MUST be implemented in all subclasses.

Returns:	List of acceptable pilot signal values or an interval of acceptable pilot signal values.
Return type:	List[float]

current_pilot¶: Return pilot signal for the current time step. (float)

ev¶: Return EV currently connected the the EVSE. (EV)

max_rate¶: Return maximum charging current allowed by the EVSE. (float)

min_rate¶: Return minimum charging current allowed by the EVSE. (float)

plugin(ev)¶

Method to attach an EV to the EVSE.

Parameters:	ev (EV) – EV which should be attached to the EVSE.
Returns:	None.
Raises:	`StationOccupiedError` – Exception raised when plugin is called by an EV is already attached to the EVSE.

set_pilot(pilot, voltage, period)¶

Apply a new pilot signal to the EVSE.

Before applying the new pilot, this method first checks if the pilot is allowed. If it is not, an InvalidRateError is raised. If the rate is valid, it is forwarded on to the attached EV if one is present. This method is also where EV charging is triggered. Thus it must be called in every time time period where the attached EV should receive charge.

Parameters:	pilot (float) – New pilot (control signal) to be sent to the attached EV. [A] voltage (float) – AC voltage provided to the battery charger. [V] period (float) – Length of the charging period. [minutes]
Returns:	None.
Raises:	`InvalidRateError` – Exception raised when pilot is not allowed by the EVSE.

station_id¶: Return unique identifier of the EVSE. (str)

unplug()¶

Method to remove an EV currently attached to the EVSE.

Sets ev to None and current_pilot to 0.

Returns:	None

class acnportal.acnsim.models.evse.DeadbandEVSE(station_id, deadband_end=6, max_rate=inf, min_rate=None)¶

Subclass of BaseEVSE which enforces the J1772 deadband between 0 - 6 A.

See BaseEVSE attributes.

_max_rate¶

Maximum charging current allowed by the EVSE.

Type:	float

_deadband_end¶

Upper end of the deadband. Pilot signals between 0 and this number are not allowed for this EVSE.

Type:	float

allowable_pilot_signals¶

Returns the allowable pilot signal levels for this EVSE.

It is implied that a 0 A signal is allowed.

Implements abstract method allowable_pilot_signals from BaseEVSE.

Returns:	List of 2 values: the min and max acceptable values.
Return type:	list[float]

deadband_end¶: Return deadband end of the EVSE. (float)

max_rate¶: Return maximum charging current allowed by the EVSE. (float)

class acnportal.acnsim.models.evse.EVSE(station_id, max_rate=inf, min_rate=0)¶

This class of EVSE allows for charging in a continuous range from min_rate to max_rate.

See BaseEVSE attributes.

_max_rate¶

Maximum charging current allowed by the EVSE.

Type:	float

_min_rate¶

Minimum charging current allowed by the EVSE.

Type:	float

allowable_pilot_signals¶

Returns the allowable pilot signal levels for this EVSE.

Implements abstract method allowable_pilot_signals from BaseEVSE.

Returns:	List of 2 values: the min and max acceptable values.
Return type:	list[float]

max_rate¶: Return maximum charging current allowed by the EVSE. (float)

min_rate¶: Return minimum charging current allowed by the EVSE. (float)

class acnportal.acnsim.models.evse.FiniteRatesEVSE(station_id, allowable_rates)¶

Subclass of EVSE which allows for finite allowed rate sets.

Most functionality remains the same except those differences noted below.

See BaseEVSE attributes.

allowable_rates¶

Iterable of rates which are allowed by the EVSE. On initialization, allowable_rates is converted into a list of rates in increasing order that includes 0 and contains no duplicate values.

Type:	iterable

allowable_pilot_signals¶

Returns the allowable pilot signal levels for this EVSE.

Implements abstract method allowable_pilot_signals from BaseEVSE.

Returns:	List of allowable pilot signals.
Return type:	list[float]

max_rate¶: Return maximum charging current allowed by the EVSE. (float)

min_rate¶: Return minimum charging current allowed by the EVSE. (float)

exception acnportal.acnsim.models.evse.InvalidRateError¶: Raised when an invalid pilot signal is passed to an EVSE.

exception acnportal.acnsim.models.evse.StationOccupiedError¶: Raised when a plugin event is called for an EVSE that already has an EV attached.

acnportal.acnsim.models.evse.get_evse_by_type(station_id, evse_type)¶

Factory to produce EVSEs of a given type.

Parameters:	station_id (str) – Unique identifier of the EVSE. evse_type (str) – Type of the EVSE. Currently supports ‘BASIC’, ‘AeroVironment’, and ‘ClipperCreek’.
Returns:	an EVSE of the specified type and with the specified id.
Return type:	EVSE