sustaingym.envs.evcharging.event_generation#

This module implements trace generation for the EVCharging class.

Traces consist of EV plug-in and unplug events and marginal carbon emissions. The module implements trace generation through the RealTraceGenerator and ArtificialTraceGenerator classes, which generate traces either from real data or from sampling from an artificial data model, respectively.

Module Contents#

Classes#

AbstractTraceGenerator

Abstract class for EventQueue generator.

RealTraceGenerator

Class for EventQueue generator using real traces from ACNData.

GMMsTraceGenerator

Class for EventQueue generator by sampling from trained GMMs.
class sustaingym.envs.evcharging.event_generation.AbstractTraceGenerator(site: sustaingym.envs.evcharging.utils.SiteStr, date_period: tuple[str, str] | sustaingym.envs.evcharging.utils.DefaultPeriodStr, requested_energy_cap: float = 100, seed: int | None = None)[source]#

Abstract class for EventQueue generator.

Subclasses are expected to implement the methods _create_events() and __repr__().

Parameters:

  • site (sustaingym.envs.evcharging.utils.SiteStr) – garage to get events from, either ‘caltech’ or ‘jpl’

  • date_period (tuple[str, str] | sustaingym.envs.evcharging.utils.DefaultPeriodStr) – either a pre-defined date period or a custom date period. If custom, the input must be a 2-tuple of strings with both strings in the format YYYY-MM-DD. Otherwise, should be a default period string.

  • requested_energy_cap (float) – max amount of requested energy allowed (kWh)

  • seed (int | None) – seed for random sampling

site#

either ‘caltech’ or ‘jpl’

date_range_str#

a 2-tuple of string elements describing date range to generate from.

date_range#

a 2-tuple of timezone-aware datetimes.

requested_energy_cap#

maximum amount of requested energy allowed (kWh)

station_ids#

list of strings of station identifiers

num_stations#

number of charging stations at site

day#

“day” of simulation, can be artificial

moer_loader#

class for loading carbon emission rates data

rng#

random number generator

TIME_STEP_DURATION = 5[source]#
MAX_STEPS_OF_TRACE = 288[source]#
BATTERY_CAPACITY = 100[source]#
MAX_POWER = 100[source]#
BA_CALTECH_JPL = 'SGIP_CAISO_SCE'[source]#
MOER_DATA_DIR = 'sustaingym/data/moer'[source]#
site__repr__() → str[source]#

Returns string representation of site.

Return type:

str

date_range__repr__() → str[source]#

Returns string representation of date range.

Return type:

str

set_seed(seed: int | None) → None[source]#

Sets random seed to make sampling reproducible.

Parameters:

seed (int | None) –

Return type:

None

get_event_queue() → tuple[acnportal.acnsim.EventQueue, list[acnportal.acnsim.EV], int][source]#

Creates an EventQueue for the current day, and then updates the day.

Sessions are added as Plugin events, and Recompute events are added every period so that the algorithm can be continually called. Unplug events are generated internally by the simulator and do not need to be explicitly added.

Returns:

  • events – event queue of EV charging sessions

  • evs – list of all EVs in event queue

  • num_plugin – number of plug in events (not counting recompute events)

Return type:

tuple[acnportal.acnsim.EventQueue, list[acnportal.acnsim.EV], int]

get_moer() → numpy.ndarray[source]#

Retrieves MOER data from the MOERLoader().

Returns:

data – array of shape (289, 37). The first column is the historical MOER. The remaining columns are forecasts for the next 36 five-min time steps. Units kg CO2 per kWh. Rows are sorted chronologically.

Return type:

numpy.ndarray

class sustaingym.envs.evcharging.event_generation.RealTraceGenerator(site: sustaingym.envs.evcharging.utils.SiteStr, date_period: tuple[str, str] | sustaingym.envs.evcharging.utils.DefaultPeriodStr, sequential: bool = True, use_unclaimed: bool = False, requested_energy_cap: float = 100, seed: int | None = None)[source]#

Bases: AbstractTraceGenerator

Class for EventQueue generator using real traces from ACNData.

See AbstractTraceGenerator for more arguments and attributes

Parameters:

  • sequential (bool) – whether to draw simulated days sequentially from date range or randomly

  • use_unclaimed (bool) – whether to use unclaimed sessions, which do not have the “requested energy” or “estimated departure” attributes. If True, the generator uses the energy delivered in the session and the disconnect time in place of those attributes, eliminating real-world uncertainty in user requests.

  • seed (int | None) – if sequential, the seed determines which day to start on

  • site (sustaingym.envs.evcharging.utils.SiteStr) –

  • date_period (tuple[str, str] | sustaingym.envs.evcharging.utils.DefaultPeriodStr) –

  • requested_energy_cap (float) –

sequential#

whether to draw simulated days sequentially from date range or randomly

use_unclaimed#

whether to use unclaimed sessions, which do not have the “requested energy” or “estimated departure” attributes. If True, the generator uses the energy delivered in the session and the disconnect time in place of those attributes, eliminating real-world uncertainty in user requests.

set_seed(seed: int | None) → None[source]#

If days are sequential, sets the day. Otherwise, seeds the random number generator.

Parameters:

seed (int | None) –

Return type:

None

class sustaingym.envs.evcharging.event_generation.GMMsTraceGenerator(site: sustaingym.envs.evcharging.utils.SiteStr, date_period: tuple[str, str] | sustaingym.envs.evcharging.utils.DefaultPeriodStr, n_components: int = 30, requested_energy_cap: float = 100, seed: int | None = None)[source]#

Bases: AbstractTraceGenerator

Class for EventQueue generator by sampling from trained GMMs.

See AbstractTraceGenerator for more arguments and attributes

Parameters:

  • site (sustaingym.envs.evcharging.utils.SiteStr) – garage to get events from, either ‘caltech’ or ‘jpl’

  • date_period (tuple[str, str] | sustaingym.envs.evcharging.utils.DefaultPeriodStr) – either a pre-defined date period or a custom date period. If custom, the input must be a 2-tuple of strings with both strings in the format YYYY-MM-DD. Otherwise, should be a default period string.

  • n_components (int) – number of components in GMM

  • requested_energy_cap (float) – max amount of requested energy allowed (kWh)

  • seed (int | None) – seed for random sampling

n_components#

int, number of components in use for GMM

gmm#

sklearn.mixture.GaussianMixture, models sessions distribution

cnt#

np.ndarray, shape [num_days], empirical distribution for number of sessions on each day

station_usage#

np.ndarray, shape [num_stations], total number of sessions during interval for each station

Notes about saved GMMs

default gmm directory: in package sustaingym/data/evcharging/gmms
    gmms
    |----caltech
    |   |---2019-05-01 2019-08-31 30.pkl
    |   |---2019-09-01 2019-12-31 30.pkl
    |   |---2020-02-01 2020-05-31 30.pkl
    |   |---2021-05-01 2021-08-31 30.pkl
    |----jpl
    |   |---2019-05-01 2019-08-31 30.pkl
    |   |---2019-09-01 2019-12-31 30.pkl
    |   |---2020-02-01 2020-05-31 30.pkl
    |   |---2021-05-01 2021-08-31 30.pkl
    Each '*.pkl' file containing a trained GMM, station usage count,
        and daily session count.
custom gmm directory: GMMs can also be trained on custom date ranges
    and number components. These are saved in the 'gmms' folder
    relative to the current working directory. See train_gmm_model.py
    for how to train GMMs from the command line.
set_seed(seed: int | None) → None[source]#

Sets random seed to make GMM sampling reproducible.

Parameters:

seed (int | None) –

Return type:

None