citylearn.electric_vehicle module
- class citylearn.electric_vehicle.ElectricVehicle(electric_vehicle_simulation: ElectricVehicleSimulation, episode_tracker: EpisodeTracker, observation_metadata: Mapping[str, bool], action_metadata: Mapping[str, bool], battery: Battery = None, min_battery_soc: int = None, name: str = None, **kwargs)[source]
Bases:
Environment- property action_metadata: Mapping[str, bool]
Mapping od active and inactive actions.
- property action_space: Box
Agent action spaces.
- property active_actions: List[str]
Actions in action_metadata with True value i.e. indicates which storage systems are to be controlled during simulation.
- property active_observations: List[str]
Observations in observation_metadata with True value i.e. obeservable.
- adjust_electric_vehicle_soc_on_system_connection(soc_system_connection: float)[source]
Adjusts the state of charge (SoC) of an electric vehicle’s (Electric_Vehicle’s) battery upon connection to the system.
When an Electric_Vehicle is in transit, the system “loses” the connection and does not know how much battery has been used during travel. As such, when an Electric_Vehicle enters an incoming or connected state, its battery SoC is updated to be close to the predicted SoC at arrival present in the Electric_Vehicle dataset.
However, predictions sometimes fail, so this method introduces variability for the simulation by randomly creating a discrepancy between the predicted value and a “real-world inspired” value. This discrepancy is generated using a normal (Gaussian) distribution, which is more likely to produce values near 0 and less likely to produce extreme values.
The range of potential variation is between -30% to +30% of the predicted SoC, with most of the values being close to 0 (i.e., the prediction). The exact amount of variation is calculated by taking a random value from the normal distribution and scaling it by the predicted SoC. This value is then added to the predicted SoC to get the actual SoC, which can be higher or lower than the prediction.
The difference between the actual SoC and the initial SoC (before the adjustment) is passed to the battery’s charge method. If the difference is positive, the battery is charged; if the difference is negative, the battery is discharged.
For example, if the Electric_Vehicle dataset has a predicted SoC at arrival of 20% (of the battery’s total capacity), this method can randomly adjust the Electric_Vehicle’s battery to 22% or 19%, or even by a larger margin such as 40%.
Args: soc_system_connection (float): The predicted SoC at system connection, expressed as a percentage of the battery’s total capacity.
- autosize_battery(**kwargs)[source]
Autosize Battery for a typical Electric_Vehicle.
- Parameters:
**kwargs (dict) – Other keyword arguments parsed to electrical_storage autosize function.
- property electric_vehicle_simulation: ElectricVehicleSimulation
Return the Electric_Vehicle simulation data.
- estimate_action_space() Box[source]
Get estimate of action spaces. Find minimum and maximum possible values of all the actions, which can then be used by the RL agent to scale the selected actions. :returns: action_space – Action low and high limits. :rtype: spaces.Box
Notes
The lower and upper bounds for the cooling_storage, heating_storage and dhw_storage actions are set to (+/-) 1/maximum_demand for each respective end use, as the energy storage device can’t provide the building with more energy than it will ever need for a given time step. . For example, if cooling_storage capacity is 20 kWh and the maximum cooling_demand is 5 kWh, its actions will be bounded between -5/20 and 5/20. These boundaries should speed up the learning process of the agents and make them more stable compared to setting them to -1 and 1.
- estimate_observation_space(include_all: bool = None, normalize: bool = None, periodic_normalization: bool = None) Box[source]
Get estimate of observation spaces. :param include_all: Whether to estimate for all observations as listed in observation_metadata or only those that are active. :type include_all: bool, default: False, :param normalize: Whether to apply min-max normalization bounded between [0, 1]. :type normalize: bool, default: False :param periodic_normalization: Whether to apply sine-cosine normalization to cyclic observations including hour, day_type and month. :type periodic_normalization: bool, default: False
- Returns:
observation_space – Observation low and high limits.
- Return type:
spaces.Box
- estimate_observation_space_limits(include_all: bool = None, periodic_normalization: bool = None) Tuple[Mapping[str, float], Mapping[str, float]][source]
Get estimate of observation space limits. Find minimum and maximum possible values of all the observations, which can then be used by the RL agent to scale the observations and train any function approximators more effectively. :param include_all: Whether to estimate for all observations as listed in observation_metadata or only those that are active. :type include_all: bool, default: False, :param periodic_normalization: Whether to apply sine-cosine normalization to cyclic observations including hour, day_type and month. :type periodic_normalization: bool, default: False
- Returns:
observation_space_limits – Observation low and high limits.
- Return type:
Tuple[Mapping[str, float], Mapping[str, float]]
Notes
Lower and upper bounds of net electricity consumption are rough estimates and may not be completely accurate hence, scaling this observation-variable using these bounds may result in normalized values above 1 or below 0.
- static get_periodic_observation_metadata() dict[str, range][source]
Get periodic observation names and their minimum and maximum values for periodic/cyclic normalization.
- Returns:
periodic_observation_metadata – Observation low and high limits.
- Return type:
Mapping[str, int]
- property min_battery_soc: int
Min battery soc percentage.
- property name: str
Unique building name.
- property observation_metadata: Mapping[str, bool]
Mapping of active and inactive observations.
- property observation_space: Box
Agent observation space.
- observations(include_all: bool = None, normalize: bool = None, periodic_normalization: bool = None) Mapping[str, float][source]
Observations at current time step.
- Parameters:
include_all (bool, default: False,) – Whether to estimate for all observations as listed in observation_metadata or only those that are active.
normalize (bool, default: False) – Whether to apply min-max normalization bounded between [0, 1].
periodic_normalization (bool, default: False) – Whether to apply sine-cosine normalization to cyclic observations.
- Returns:
observation_space – Observation low and high limits.
- Return type:
spaces.Box