Title: | Electric Vehicle Charging Sessions Simulation |
Version: | 1.6.1 |
Maintainer: | Marc CaƱigueral <marccanyigueral@gmail.com> |
Description: | Simulation of Electric Vehicles charging sessions using Gaussian models, together with time-series power demand calculations. |
License: | GPL-3 |
Encoding: | UTF-8 |
LazyData: | true |
RoxygenNote: | 7.3.2 |
Imports: | MASS, dplyr, lubridate, purrr, rlang, tidyr, jsonlite, dygraphs, ggplot2 |
Suggests: | spelling, testthat (≥ 3.0.0) |
Depends: | R (≥ 3.5) |
URL: | https://github.com/resourcefully-dev/evsim/, https://resourcefully-dev.github.io/evsim/ |
BugReports: | https://github.com/resourcefully-dev/evsim/issues |
Language: | en-US |
Config/testthat/edition: | 3 |
NeedsCompilation: | no |
Packaged: | 2025-05-06 12:20:11 UTC; marc |
Author: | Marc CaƱigueral |
Repository: | CRAN |
Date/Publication: | 2025-05-07 12:30:12 UTC |
Adapt charging features
Description
Calculate connection and charging times according to energy, power and time resolution
Usage
adapt_charging_features(
sessions,
time_resolution = 15,
power_resolution = 0.01
)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
time_resolution |
integer, time resolution (in minutes) of the sessions' datetime variables |
power_resolution |
numeric, power resolution (in kW) of the sessions' power |
Details
All sessions' Power
must be higher than 0
, to avoid NaN
values from dividing
by zero.
The ConnectionStartDateTime
is first aligned to the desired time resolution,
and the ConnectionEndDateTime
is calculated according to the ConnectionHours
.
The ChargingHours
is recalculated with the values of Energy
and Power
,
limited by ConnectionHours
. Finally, the charging times are also calculated.
Value
tibble
Examples
suppressMessages(library(dplyr))
sessions <- head(evsim::california_ev_sessions, 10)
sessions %>%
select(ConnectionStartDateTime, ConnectionEndDateTime, Power)
adapt_charging_features(
sessions,
time_resolution = 60,
power_resolution = 0.01
) %>%
select(ConnectionStartDateTime, ConnectionEndDateTime, Power)
adapt_charging_features(
sessions,
time_resolution = 15,
power_resolution = 1
) %>%
select(ConnectionStartDateTime, ConnectionEndDateTime, Power)
Assign a charging station to EV charging sessions
Description
Variable ChargingStation
and Socket
will be assigned to the sessions
tibble with a name pattern being: names_prefix
+ "CHS" + number
Usage
add_charging_infrastructure(
sessions,
resolution = 15,
min_stations = 0,
n_sockets = 2,
names_prefix = NULL,
duration_th = 0
)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
resolution |
integer, time resolution in minutes |
min_stations |
integer, minimum number of charging stations to consider |
n_sockets |
integer, number of sockets per charging station |
names_prefix |
character, prefix of the charging station names (optional) |
duration_th |
integer between 0 and 100, minimum share of time (in percentage)
of the "occupancy duration curve" (see function |
Value
tibble
Examples
# Assign a `ChargingStation` to every session according to the occupancy
sessions_infrastructure <- add_charging_infrastructure(
sessions = head(evsim::california_ev_sessions, 50),
resolution = 60
)
print(unique(sessions_infrastructure$ChargingStation))
# Now without considering the occupancy values that only represent
# a 10% of the time
sessions_infrastructure <- add_charging_infrastructure(
sessions = head(evsim::california_ev_sessions, 50),
resolution = 60, duration_th = 10
)
print(unique(sessions_infrastructure$ChargingStation))
EV model example
Description
Example of an evmodel
object created with evprof
for testing purposes.
It has been created using an Open source data set of EV charging sessions
provided by ACN.
Usage
california_ev_model
Format
california_ev_model
An evmodel
object.
- metadata
Information about the characteristics of the model
- model
Gaussian Mixture Models for connection times and energy
EV charging sessions example
Description
Example of an charging sessions data set ready to use by evprof
functions.
It is the open source data set downloaded from the
ACN-Data website, transformed according
to the standard names defined by evprof
Usage
california_ev_sessions
Format
california_ev_sessions
A tibble
object with standard variable names defined by evprof
Source
https://ev.caltech.edu/dataset
Clustered EV charging sessions example
Description
Example of a charging sessions data set that has been clustered by evprof
functions
Usage
california_ev_sessions_profiles
Format
california_ev_sessions_profiles
A tibble
object with standard variable names defined by evprof
Source
https://ev.caltech.edu/dataset
Convert numeric time value to a datetime period (hour-based)
Description
Convert numeric time value to a datetime period (hour-based)
Usage
convert_time_num_to_period(time_num)
Arguments
time_num |
Numeric time value (hour-based) |
Estimate sessions connection values
Description
Estimate sessions connection values following a Multi-variate Guassian distribution. The minimum considered value for duration is 30 minutes.
Usage
estimate_connection(n, mu, sigma, log)
Arguments
n |
integer, number of sessions |
mu |
numeric vector, means of bivariate GMM |
sigma |
numeric matrix, covariance matrix of bivariate GMM |
log |
logical, true if models have logarithmic transformation |
Value
vector of numeric values
Estimate sessions energy values following a Gaussian distribution. The minimum considered value is 1kWh based on real data analysis.
Description
Estimate sessions energy values following a Gaussian distribution. The minimum considered value is 1kWh based on real data analysis.
Usage
estimate_energy(n, mu, sigma, log)
Arguments
n |
integer, number of sessions |
mu |
numeric, mean of Gaussian distribution |
sigma |
numeric, standard deviation of Gaussian distribution.
If unknown, a recommended value is |
log |
logical, true if models have logarithmic transformation |
Value
numeric vector
Estimate sessions parameters of a specific profile
Description
Estimate sessions parameters of a specific profile
Usage
estimate_sessions(
profile_name,
n_sessions,
power,
connection_models,
energy_models,
connection_log,
energy_log,
charging_powers
)
Arguments
profile_name |
character, profile name |
n_sessions |
integer, total number of sessions per day |
power |
numeric, charging power of the session |
connection_models |
tibble, bivariate GMM of the profile |
energy_models |
tibble, univariate GMM of the profile |
connection_log |
logical, true if connection models have logarithmic transformations |
energy_log |
logical, true if energy models have logarithmic transformations |
charging_powers |
tibble with variables |
Value
tibble
Expand a session along time slots within its connection time
Description
The session
is divided in multiple time slots
with the corresponding Power
consumption, among other variables.
Usage
expand_session(session, resolution)
Arguments
session |
tibble, sessions data set in standard format marked by |
resolution |
integer, time resolution (in minutes) of the time slots |
Value
tibble
Expand sessions along time slots
Description
Every session in sessions
is divided in multiple time slots
with the corresponding Power
consumption, among other variables.
Usage
expand_sessions(sessions, resolution)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
resolution |
integer, time resolution (in minutes) of the time slots |
Details
The Power
value is calculated for every time slot according to the original
required energy. The columns PowerNominal
, EnergyRequired
and
FlexibilityHours
correspond to the values of the original session, and not
to the expanded session in every time slot. The column ID
shows the number
of the time slot corresponding to the original session.
Value
tibble
Examples
library(dplyr)
sessions <- head(evsim::california_ev_sessions, 10)
expand_sessions(
sessions,
resolution = 60
)
Charging rates distribution
Description
Get charging rates distribution in percentages from a charging sessions data set
Usage
get_charging_rates_distribution(sessions, unit = "year", power_interval = NULL)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
unit |
character. Valid base units are |
power_interval |
numeric, interval of kW between power rates.
It is used to round the |
Value
tibble
Examples
get_charging_rates_distribution(evsim::california_ev_sessions, unit = "year")
Connection GMM
Description
Get connection Gaussian Mixture Models from parameters
Usage
get_connection_models_from_parameters(
time_cycle_parameters,
connection_log = FALSE
)
Arguments
time_cycle_parameters |
tibble with Gaussian Mixture Models parameters.
This tibble must have the following columns: |
connection_log |
logical, true if connection models have logarithmic transformations |
Value
connection GMM tibble
Create the custom EV model
Description
Get the EV model object of class evmodel
Usage
get_custom_ev_model(
names,
months_lst = list(1:12, 1:12),
wdays_lst = list(1:5, 6:7),
parameters_lst,
connection_log,
energy_log,
data_tz
)
Arguments
names |
character vector with the given names of each time-cycle model |
months_lst |
list of integer vectors with the corresponding months of the year for each time-cycle model |
wdays_lst |
list of integer vectors with the corresponding days of the week for each time-cycle model (week start = 1) |
parameters_lst |
list of tibbles corresponding to the GMM parameters of every time-cycle model |
connection_log |
logical, true if connection models have logarithmic transformations |
energy_log |
logical, true if energy models have logarithmic transformations |
data_tz |
character, time zone of the original data (necessary to properly simulate new sessions) |
Value
object of class evmodel
Examples
# For workdays time cycle
workdays_parameters <- dplyr::tibble(
profile = c("Worktime", "Visit"),
ratio = c(80, 20),
start_mean = c(9, 11),
start_sd = c(1, 4),
duration_mean = c(8, 4),
duration_sd = c(0.5, 2),
energy_mean = c(15, 6),
energy_sd = c(4, 3)
)
# For weekends time cycle
weekends_parameters <- dplyr::tibble(
profile = "Visit",
ratio = 100,
start_mean = 12,
start_sd = 4,
duration_mean = 3,
duration_sd = 2,
energy_mean = 4,
energy_sd = 4
)
parameters_lst <- list(workdays_parameters, weekends_parameters)
# Get the whole model
ev_model <- get_custom_ev_model(
names = c("Workdays", "Weekends"),
months_lst = list(1:12, 1:12),
wdays_lst = list(1:5, 6:7),
parameters_lst = parameters_lst,
connection_log = FALSE,
energy_log = FALSE,
data_tz = "Europe/Amsterdam"
)
Get day sessions
Description
Get day sessions
Usage
get_day_sessions(day, ev_models, connection_log, energy_log, charging_powers)
Arguments
day |
Date to simulate |
ev_models |
profiles models |
connection_log |
Logical, true if connection models have logarithmic transformations |
energy_log |
Logical, true if energy models have logarithmic transformations |
charging_powers |
tibble with variables |
Value
tibble
Time-series EV demand
Description
Obtain time-series of EV demand from sessions data set
Usage
get_demand(
sessions,
dttm_seq = NULL,
by = "Profile",
resolution = 15,
mc.cores = 1
)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
dttm_seq |
sequence of datetime values that will be the |
by |
character, being 'Profile' or 'Session'. When |
resolution |
integer, time resolution (in minutes) of the sessions datetime variables.
If |
mc.cores |
integer, number of cores to use. Must be at least one, and parallelization requires at least two cores. |
Details
Note that the time resolution of variables ConnectionStartDateTime
and
ChargingStartDateTime
must coincide with
resolution
parameter. For example, if a charging session in sessions
starts charging
at 15:32 and resolution = 15
, the load of this session won't be computed. To solve this,
the function automatically aligns charging sessions' start time according to
resolution
, so following the previous example the session would start at 15:30.
Value
time-series tibble with first column of type datetime
Examples
suppressMessages(library(lubridate))
suppressMessages(library(dplyr))
# Get demand with the complete datetime sequence from the sessions
sessions <- head(evsim::california_ev_sessions, 100)
demand <- get_demand(
sessions,
by = "Session",
resolution = 60
)
demand %>% plot_ts(ylab = "EV demand (kW)", legend_show = "onmouseover")
# Get demand with a custom datetime sequence and resolution of 15 minutes
sessions <- head(evsim::california_ev_sessions_profiles, 100)
dttm_seq <- seq.POSIXt(
as_datetime(dmy(08102018)) %>% force_tz(tz(sessions$ConnectionStartDateTime)),
as_datetime(dmy(11102018)) %>% force_tz(tz(sessions$ConnectionStartDateTime)),
by = "15 mins"
)
demand <- get_demand(
sessions,
dttm_seq = dttm_seq,
by = "Profile",
resolution = 15
)
demand %>% plot_ts(ylab = "EV demand (kW)", legend_show = "onmouseover")
Energy GMM
Description
Get energy Gaussian Mixture Models from parameters
Usage
get_energy_models_from_parameters(time_cycle_parameters, energy_log = FALSE)
Arguments
time_cycle_parameters |
tibble with Gaussian Mixture Models parameters.
This tibble must have the following columns: |
energy_log |
logical, true if connection models have logarithmic transformations |
Value
energy GMM tibble
Get estimated profiles
Description
Get estimated profiles
Usage
get_estimated_connections(n, profile_models, log)
Arguments
n |
number of sessions |
profile_models |
models of the profile |
log |
Logical, true if models have logarithmic transformation |
Value
list with sessions connection values
Estimate energy given energy models tibble
Description
Estimate energy given energy models tibble
Usage
get_estimated_energy(power_vct, energy_models, energy_log)
Arguments
power_vct |
numeric vector of power values of simulated sessions |
energy_models |
energy models tibble |
energy_log |
Logical, true if models have logarithmic transformation |
Value
list of numeric vectors
Get evmodel
parameters in a list
Description
Every time cycle is an element of the returned list, containing a list with the user profile as elements, each one containing the ratio and the corresponding tables with the statistic parameters of connection and energy GMM.
Usage
get_evmodel_parameters(evmodel)
Arguments
evmodel |
object of class |
Value
list
Examples
get_evmodel_parameters(evsim::california_ev_model)
Get evmodel
parameters in a list of summary tables
Description
Every time cycle is an element of the returned list, containing a table with
a user profile in every row and the mean and standard deviation values of the
GMM variables (connection duration, connection start time and energy).
If the energy models were built by charging rate, the average mean
and sd
are provided without taking into account different charging rates (this
information is lost in this summary).
Usage
get_evmodel_summary(evmodel)
Arguments
evmodel |
object of class |
Value
list
Examples
get_evmodel_summary(evsim::california_ev_model)
Time-series EV occupancy
Description
Obtain time-series of simultaneously connected EVs from sessions data set
Usage
get_occupancy(
sessions,
dttm_seq = NULL,
by = "Profile",
resolution = 15,
mc.cores = 1
)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
dttm_seq |
sequence of datetime values that will be the |
by |
character, being 'Profile' or 'Session'. When |
resolution |
integer, time resolution (in minutes) of the sessions datetime variables.
If |
mc.cores |
integer, number of cores to use. Must be at least one, and parallelization requires at least two cores. |
Details
Note that the time resolution of variable ConnectionStartDateTime
must coincide with
resolution
parameter. For example, if a charging session in sessions
starts charging
at 15:32 and resolution = 15
, the load of this session won't be computed. To solve this,
the function automatically aligns charging sessions' start time according to
resolution
, so following the previous example the session would start at 15:30.
Value
time-series tibble with first column of type datetime
Examples
library(lubridate)
library(dplyr)
# Get occupancy with the complete datetime sequence from the sessions
sessions <- head(evsim::california_ev_sessions, 100)
connections <- get_occupancy(
sessions,
by = "ChargingStation",
resolution = 60
)
connections %>%
plot_ts(ylab = "Vehicles connected", legend_show = "onmouseover")
# Get occupancy with a custom datetime sequence and resolution of 15 minutes
sessions <- head(evsim::california_ev_sessions_profiles, 100)
dttm_seq <- seq.POSIXt(
as_datetime(dmy(08102018)) %>% force_tz(tz(sessions$ConnectionStartDateTime)),
as_datetime(dmy(11102018)) %>% force_tz(tz(sessions$ConnectionStartDateTime)),
by = "15 mins"
)
connections <- get_occupancy(
sessions,
dttm_seq = dttm_seq,
by = "Profile"
)
connections %>%
plot_ts(ylab = "Vehicles connected", legend_show = "onmouseover")
User profiles distribution
Description
Get the user profiles distribution from the original data set used to build the model
Usage
get_user_profiles_distribution(evmodel)
Arguments
evmodel |
object of class |
Value
tibble
Examples
get_user_profiles_distribution(evsim::california_ev_model)
Is the sessions data set aligned in time?
Description
Checks if sessions time variables (only connection/charging start times) are aligned with a specific time resolution.
Usage
is_aligned(sessions, resolution)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
resolution |
integer, time resolution (in minutes) of the time slots |
Value
logical
Parallel processing for windows
Description
mclapply version that works on windows
Usage
mclapply.windows(X, FUN, ..., mc.cores)
Arguments
X |
a vector (atomic or list) or an expressions vector. Other objects (including classed objects) will be coerced by as.list. |
FUN |
the function to be applied to (mclapply) each element of X. |
... |
For mclapply, optional named arguments to FUN. |
mc.cores |
integer, number of cores to be used. Could be overruled if number of items in list is lower. |
Details
This is a workaround to allow parallel processing in windows since
parallel
package only works with linux distributions.
Source: https://www.r-bloggers.com/2014/07/implementing-mclapply-on-windows-a-primer-on-embarrassingly-parallel-computation-on-multicore-systems-with-r/
Value
list
Plot the occupancy duration curve
Description
This term is based on the "load duration curve" and is useful to see the behavior of occupancy over the time in your charging installation. The steeper the curve, the shorter the duration that higher number of connections are sustained. Conversely, the flatter the curve, the longer the duration that higher number of connections are sustained. This information is crucial for various purposes, such as infrastructure planning, capacity sizing, and resource allocation.
Usage
plot_occupancy_duration_curve(
sessions,
dttm_seq = NULL,
by = "Profile",
resolution = 15,
mc.cores = 1
)
Arguments
sessions |
tibble, sessions data set in standard format marked by |
dttm_seq |
sequence of datetime values that will be the |
by |
character, being 'Profile' or 'Session'. When |
resolution |
integer, time resolution (in minutes) of the sessions datetime variables.
If |
mc.cores |
integer, number of cores to use. Must be at least one, and parallelization requires at least two cores. |
Value
ggplot
Examples
library(dplyr)
sessions <- head(evsim::california_ev_sessions_profiles, 100)
plot_occupancy_duration_curve(
sessions,
by = "Profile",
resolution = 15
)
Interactive plot for time-series tibbles
Description
First column of the df
tibble must be a datetime
or date variable.
The rest of columns must be numeric of the same units. This functions makes
use of dygraphs
package to generate an HTML Dygraphs plot.
Usage
plot_ts(
df,
title = NULL,
xlab = NULL,
ylab = NULL,
legend_show = "auto",
legend_width = 250,
group = NULL,
width = NULL,
height = NULL,
...
)
Arguments
df |
data.frame or tibble, first column of name |
title |
character, title of the plot (accepts HTML code) |
xlab |
character, X axis label (accepts HTML code) |
ylab |
character, Y axis label (accepts HTML code) |
legend_show |
character, when to display the legend. Specify "always" to always show the legend. Specify "onmouseover" to only display it when a user mouses over the chart. Specify "follow" to have the legend show as overlay to the chart which follows the mouse. The default behavior is "auto", which results in "always" when more than one series is plotted and "onmouseover" when only a single series is plotted. |
legend_width |
integer, width (in pixels) of the div which shows the legend. |
group |
character, dygraphs group to associate this plot with. The x-axis zoom level of dygraphs plots within a group is automatically synchronized. |
width |
Width in pixels (optional, defaults to automatic sizing) |
height |
Height in pixels (optional, defaults to automatic sizing) |
... |
extra arguments to pass to |
Value
dygraph
Examples
suppressMessages(library(lubridate))
suppressMessages(library(dplyr))
# Get demand with the complete datetime sequence from the sessions
sessions <- head(evsim::california_ev_sessions, 100)
demand <- get_demand(
sessions,
by = "Session",
resolution = 60
)
demand %>% plot_ts()
Prepare the models from the evmodel
object ready for the simulation
Description
The ratios and default charging power for every user profile, and the sessions per day for every time cycle are included.
Usage
prepare_model(ev_models, sessions_day, user_profiles)
Arguments
ev_models |
tibble with models from an |
sessions_day |
tibble with variables |
user_profiles |
tibble with variables |
Value
tibble
print
method for evmodel
object class
Description
print
method for evmodel
object class
Usage
## S3 method for class 'evmodel'
print(x, ...)
Arguments
x |
|
... |
further arguments passed to or from other methods. |
Value
nothing but prints information about the evmodel
object
Examples
print(california_ev_model)
Read EV model
Description
Read an EV model JSON file and convert it to object of class evmodel
Usage
read_ev_model(file)
Arguments
file |
path to the JSON file |
Value
object of class evmodel
Examples
ev_model <- california_ev_model # Model of example
save_ev_model(ev_model, file = file.path(tempdir(), "evmodel.json"))
read_ev_model(file = file.path(tempdir(), "evmodel.json"))
Round a numeric value to interval
Description
Round a numeric value to interval
Usage
round_to_interval(dbl, interval)
Arguments
dbl |
numeric value |
interval |
decimal interval (from 0 to 1) |
Save the EV model
Description
Save the EV model object of class evmodel
to a JSON file
Usage
save_ev_model(evmodel, file)
Arguments
evmodel |
object of class |
file |
character string with the path or name of the file |
Value
nothing but saves the evmodel
object in a JSON file
Examples
ev_model <- california_ev_model # Model of example
save_ev_model(ev_model, file = file.path(tempdir(), "evmodel.json"))
Names of standard features of a sessions dataset
Description
A vector with the standard names of sessions features for this package functions.
Usage
sessions_feature_names
Format
A vector
Simulation of EV sessions
Description
Simulate EV charging sessions given the evmodel
object and other contextual parameters.
Usage
simulate_sessions(
evmodel,
sessions_day,
user_profiles,
charging_powers,
dates,
resolution
)
Arguments
evmodel |
object of class |
sessions_day |
tibble with variables |
user_profiles |
tibble with variables |
charging_powers |
tibble with variables |
dates |
date sequence that will set the time frame of the simulated sessions |
resolution |
integer, time resolution (in minutes) of the sessions datetime variables |
Details
Some adaptations have been done to the output of the Gaussian models: the minimum simulated energy is considered to be 1 kWh, while the minimum connection duration is 30 minutes.
Value
tibble
Examples
library(dplyr)
library(lubridate)
# Get the example `evmodel`
ev_model <- evsim::california_ev_model
# Simulate EV charging sessions, considering that the Worktime sessions
# during Workdays have 11 kW, while all Visit sessions charge at 3.7kW or
# 11kW, with a distribution of 30% and 70% respectively.
simulate_sessions(
ev_model,
sessions_day = tibble(
time_cycle = c("Workday", "Weekend"),
n_sessions = c(15, 10)
),
user_profiles = tibble(
time_cycle = c("Workday", "Workday", "Weekend"),
profile = c("Visit", "Worktime", "Visit"),
ratio = c(0.5, 0.5, 1),
power = c(NA, 11, NA)
),
charging_powers = tibble(
power = c(3.7, 11),
ratio = c(0.3, 0.7)
),
dates = seq.Date(today(), today()+days(4), length.out = 4),
resolution = 15
)