API Reference¶

Main Classes ¶

The Env class ¶

class energym.envs.env.Env[source]¶

The main Energym class to describe an abstract simulation environment.

It encapsulates an environment with arbitrary behind-the-scenes dynamics. An environment can be partially or fully observed.

Notes

Accept field keys or identify them? Maybe not a good idea… # TODO

Attributes

energym_pathstr: Absolute path to the energym folder.
runs_pathstr: Path to store the information of the simulation run.

Methods

step(action)	Advances the simulation by one timestep. (not implemented)
reset()	Resets the simulation environment. (not implemented)
close()	Closes the simulation environment. (not implemented)
get_forecast()	Gets the forecasts for external parameters.
get_output()	Gets the outputs of the last simulation step.

abstract close()[source]¶

Closes the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

abstract get_forecast()[source]¶

Return forecasts for the environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

abstract get_output()[source]¶

Gets the outputs of the last simulation step.

Not implemented. Subclasses should override this method.

Raises NotImplementedError

abstract reset()[source]¶

Resets the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

abstract step(action)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

property unwrapped¶

Completely unwrap this env.

Returns

energym.Env: The base non-wrapped energym.Env instance.

class energym.envs.env_fmu.EnvFMU(model_path, start_time, stop_time, step_size, weather=None, input_specs=None, output_specs=None, kpi_options=None, default_path=True, weather_file_path=None)[source]¶

The FMU base class for Energym.

It encapsulates an environment whose simulation is performed in an FMU. The methods step(), reset() and close() from Env are implemented here.

Attributes

fmu_filestr: Full path to the FMU file
model_descriptionfmpy ModelDescription object: Encapsulated description of the model extracted from the FMU using FMPy inspection methods
fmi_versionstr: Version number of FMI, inspected inside the FMU. Should be ‘1.0’ or ‘2.0’
step_sizeint or double: Simulation stepsize in seconds. Int for EnergyPlus, double for Modelica
weatherstr: Indicates the used weather profile
is_fmu_initializedbool: Flags the FMU initialization process
vrsdict: Contains the variable names and their references
fmi_typestr: The simulation type as speified by the FMU, either ‘cosim’ or ‘modex’
start_timeint: Start of simulation time in seconds
stop_timeint: End of simulation time in seconds
kpisKPI object: To track the KPI relevant metrics
input_spacedict: Contains controllable input variables
output_spacedict: Contains output variables
observation_historylist: Collects all observations of one simulation
unzipdirstr: Directory for extracting the FMU
fmuFMU1Slave or FMU2Slave or FMU1Model or FMU2Model: Simulation object
timeint or double: Current simulation time (int for EnergyPlus, double for Modelica)

Methods

initialize()	Initializes simulation object.
__build_input_space(input_specs)	Collects the inputs from the simulation object.
__build_output_space(output_specs)	Collects the outputs from the simulation object.
__initialize_fmu()	Initializes the FMU after instantiation.
get_inputs_names()	Retrieves list of inputs from model description.
get_outputs_names()	Retrieves list of outputs from model description.
get_date()	Gets the current simulation time.
step(inputs=None)	Advances the simulation one timestep.
print_kpis()	Prints the KPIs.
get_kpi(start_ind=0, end_ind=-1)	Retrieves the KPIs.
get_cumulative_kpi(phrase, kpi_type, out_type)	Retrieves the cumulative KPIs over multiple variables.
sample_random_action()	Samples random actions from the action space.
get_forecast(forecast_length = 24, kwargs)**	Generates a weather forecast of a given length.
look_for_weather_file(name = None)	Finds a weather file in the FMU.
post_process(list_rel_out, res, arrays=False)	Post-process output of FMPY.
reset()	Resets the simulation.
close()	Terminates the FMU and removes leftover folders.

Parameters

model_path: str: Path to the fmu model file, relative inside the simulation folder
start_time: int: Begin of the simulation time in seconds in relation to the beginning of the year
stop_time: int: End of the simulation time in seconds in relation to the beginning of the year
step_size: double: Step size in second. May be chosen freely for some models (modelica), or needs to be identical to model step size in other cases (EnergyPlus)
weatherEPW or MOS, optional: Specifies the used weather file, by default None
input_specsdict, optional: Contains the model inputs, by default None
output_specsdict, optional: Contains the model outputs, by default None
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None
default_pathbool: Whether to use the deault path or an absolute path in model_path

Raises

ValueError: If the FMU supprts neither co-simulation nor model exchange

close(save=True)[source]¶: Terminates the FMU and removes leftover folders.

get_cumulative_kpi(names, kpi_type, out_type)[source]¶

Retrieves the cumulative KPIs over multiple variables.

For implementation details see the KPI class.

Parameters

nameslist or str: List of variable names or common string to filter the variables.
kpi_typestr: One of the 4 KPI types to filter the variables.
out_typestr: Cumulative KPI type (“avg” or “sum”).

Returns

float or int: The computed KPI.

get_date()[source]¶

Gets the current simulation time.

Returns

int: Minutes of the current simulation time
int: Hours of the current simulation time
int: Day of the current simulation time
int: Month of the current simulation time

get_forecast(forecast_length=24)[source]¶

Generates a weather forecast of a given length.

Parameters

forecast_lengthint, optional: Number of timesteps that will be forecasted, by default 24

Returns

forecastdict: Forecasted values for default keys or ones specified in kwargs

get_inputs_names()[source]¶

Retrieves list of inputs from model description.

Returns

input_keyslist of str: List with input names.

get_kpi(start_ind=0, end_ind=- 1)[source]¶

Retrieves the KPIs.

For implementation details see the KPI class.

Parameters

start_indint, optional: Index from where the KPI computation starts, by default 0
end_ind: int, optional: Index where the KPI computation ends, by default -1

Returns

kpi_summarydict: Dict containing all the tracked variables and their KPIs.

get_outputs_names()[source]¶

Retrieves list of outputs from model description.

Returns

output_keyslist of str: Variable names that specify outputs.

initialize()[source]¶

Initializes simulation object.

Instantiates FMPy FMUSalve1 or FMUSlave2 object based on FMI version detected.

look_for_weather_file(name=None, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Finds a weather file in the FMU.

Parameters

namestr: Name of weather file

Raises

Exception: If no weather file/more than one weather file is found or the file has a wrong type

post_process(list_rel_out, res, arrays=False)[source]¶

Post-process output of FMPY.

Parameters

list_rel_outlist of str: Output labels
reslist: Output of doStep FMPy method
arraysbool, optional: If True, array output in processed structure, default is False

Returns

dic_res: collections.OrderedDict: Dictionary with values of output for each key

print_kpis()[source]¶: Prints the KPIs.

reset()[source]¶: Resets the simulation.

sample_random_action()[source]¶

Samples random actions from the action space.

Returns

dict: Inputs with random values, within a specified range

step(inputs=None)[source]¶

Advances the simulation one timestep.

Applies input for current step, simulate the system in FMU and retrieves outputs.

Parameters

inputs: dict: Inputs for the system. Keys are input names, values are iterables of input values. If not defined, assumes no inputs required.

Returns

outputs: dict: Outputs for the system.

The EnvEPlusFMU class ¶

class energym.envs.env_fmu_eplus.EnvEPlusFMU(model_path, start_time, stop_time, step_size, weather, input_specs, output_specs, kpi_options, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Base class for EnergyPlus based FMU simulation models.

Subclasses EnvFMU and inherits its behavior. Defines EnergyPlus specific simulation details.

Parameters

model_pathstr: Specifies the path to the FMU
start_timeint: Begin of the simulation time in seconds in relation to the beginning of the year
stop_timeint: End of the simulation time in seconds in relation to the beginning of the year
step_sizefloat: Length of a simulation timestep in seconds
weatherstr: Specifies the used weather file
input_specsdict: Contains the inputs of the model
output_specsdict: Contains the outputs of the model
kpi_optionsdict: Dict to specify the tracked KPIs.
default_pathbool: Whether to use the default path or an absolute path in model_path and weather

Raises

Exception: If the passed weather file is not contained in the list of available weather files

get_output()[source]¶

Gets the outputs of the last simulation step.

Not implemented. Subclasses should override this method.

Raises NotImplementedError

initialize()[source]¶

Initializes simulation object.

Instantiates FMPy FMUSalve1 or FMUSlave2 object based on FMI version detected. For E+, by default, an empty stepp is made at the beginning and default step parameters are done.

step(inputs=None)[source]¶

Advances the simulation one timestep.

Applies input for current step, simulate the system in FMU and retrieves outputs.

Parameters

inputs: dict: Inputs for the system. Keys are input names, values are iterables of input values. If not defined, assumes no inputs required.

Returns

outputs: dict: Outputs for the system.

Model Classes ¶

The Seminarcenter environment ¶

class energym.envs.seminarcenter.seminarcenter.Seminarcenter(model_path, CO2_schedule, start_day=1, start_month=1, year=2019, simulation_days=10, weather='DNK_MJ_Horsens1', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the models SeminarcenterThermostat-v0 and SeminarcenterFull-v0.

Subclasses EnvEPlusFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvEPlusFMU.

Attributes

CO2_scheduleEProductionSchedule: Schedule specifying the CO2 emission of the current energy mix.

Methods

step(inputs):	Advances the simulation one timestep.
predict_co2(steps):	Provides a forecast for the CO2 schedule.

Parameters

model_pathstr: Specifies the path to the FMU
CO2_scheduleEProductionSchedule: Schedule specifying the CO2 emission of the current energy mix.
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “DNK_MJ_Horsens1”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

The Apartments environment ¶

class energym.envs.apartments.apartments.Apartments(model_path, EV_schedule, start_day=1, start_month=1, year=2019, simulation_days=10, weather='ESP_CT_Barcelona', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the models ApartmentsThermal-v0 and ApartmentsGrid-v0.

Subclasses EnvEPlusFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvEPlusFMU.

Attributes

EV_scheduleElectricVehicleSchedule: Energy consumption schedule for electric vehicles

Methods

step(inputs):	Advances the simulation one timestep.
predict_ev(steps):	Provides a forecast for the EV schedule.

Parameters

model_pathstr: Specifies the path to the FMU
EV_scheduleElectricVehicleSchedule: Energy consumption schedule for electric vehicles
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “ESP_CT_Barcelona”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

The Apartments2 environment ¶

class energym.envs.apartments2.apartments2.Apartments2(model_path, EV1_schedule, EV2_schedule, start_day=1, start_month=1, year=2019, simulation_days=10, weather='ESP_CT_Barcelona', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the models Apartments2Thermal-v0 and Apartments2Grid-v0.

Subclasses EnvEPlusFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvEPlusFMU.

Attributes

EV_scheduleElectricVehicleSchedule: Energy consumption schedule for electric vehicles

Methods

step(inputs):	Advances the simulation one timestep.
predict_ev(steps):	Provides a forecast for the EV schedule.

Parameters

model_pathstr: Specifies the path to the FMU
EV_scheduleElectricVehicleSchedule: Energy consumption schedule for electric vehicles
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “ESP_CT_Barcelona”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

The Offices environment ¶

class energym.envs.offices.offices.Offices(model_path, start_day=1, start_month=1, year=2019, simulation_days=10, weather='GRC_A_Athens', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the model OfficesThermostat-v0.

Subclasses EnvEPlusFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvEPlusFMU.

Parameters

model_pathstr: Specifies the path to the FMU
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “GRC_A_Athens”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

The MixedUse environment ¶

class energym.envs.mixeduse.mixeduse.MixedUse(model_path, start_day=1, start_month=1, year=2019, simulation_days=10, weather='GRC_A_Athens', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the model MixedUseFanFCU-v0.

Subclasses EnvEPlusFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvEPlusFMU.

Parameters

model_pathstr: Specifies the path to the FMU
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “GRC_A_Athens”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

The SimpleHouse environment ¶

class energym.envs.simple_house.simple_house.SimpleHouse(model_path, start_day=1, start_month=1, year=2019, simulation_days=21, weather='CH_BS_Basel', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the models

Subclasses EnvModFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvModFMU.

Parameters

model_pathstr: Specifies the path to the FMU
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “CH_ZH_Maur”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

The SwissHouse environment ¶

class energym.envs.swiss_house.swiss_house.SwissHouse(model_path, start_day=1, start_month=1, year=2019, simulation_days=21, weather='CH_BS_Basel', kpi_options=None, default_path=True, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Containing information for the models

Subclasses EnvModFMU and inherits its behavior. Simulation based details are specified in this class and passed to the constructor of EnvModFMU.

Parameters

model_pathstr: Specifies the path to the FMU
start_dayint, optional: Day of the month to start the simulation, by default 1
start_monthint, optional: Month of the year to start the simulation, by default 1
yearint, optional: Year to start the simulation, by default 2019
simulation_daysint, optional: Number of days the simulation can run for, by default 10
weatherstr, optional: Specific weather file to run the simulation, by default “CH_ZH_Maur”
kpi_optionsdict, optional: Dict to specify the tracked KPIs, by default None.

Wrappers ¶

The abstract Wrapper class ¶

class energym.envs.env.Wrapper(env)[source]¶

Wraps the environment to allow a modular transformation.

This class is the base class for all wrappers. The subclass could override some methods to change the behavior of the original environment without touching the original code.

Note

Don’t forget to call super().__init__(env) if the subclass overrides __init__().

close()[source]¶

Closes the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

get_forecast(**kwargs)[source]¶

Return forecasts for the environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

get_output()[source]¶

Gets the outputs of the last simulation step.

Not implemented. Subclasses should override this method.

Raises NotImplementedError

reset(**kwargs)[source]¶

Resets the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

step(inputs)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

property unwrapped¶

Completely unwrap this env.

Returns

energym.Env: The base non-wrapped energym.Env instance.

The abstract OutputsWrapper class ¶

class energym.envs.env.OutputsWrapper(env)[source]¶

Wrapper to transform simulations outputs

get_forecast(**kwargs)[source]¶

Return forecasts for the environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

get_output()[source]¶

Gets the outputs of the last simulation step.

Not implemented. Subclasses should override this method.

Raises NotImplementedError

reset(**kwargs)[source]¶

Resets the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

step(inputs)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

The abstract StepWrapper class ¶

class energym.envs.env.StepWrapper(env)[source]¶

Wrapper to transform steps

reset(**kwargs)[source]¶

Resets the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

abstract step(inputs)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

The abstract InputsWrapper class ¶

class energym.envs.env.InputsWrapper(env)[source]¶

Wrapper to transform simulations inputs

reset(**kwargs)[source]¶

Resets the simulation environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

step(inputs)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

OutputsWrapper ¶

class energym.wrappers.rescale_outputs.RescaleOutputs(env, lower_bound=None, upper_bound=None)[source]¶: Rescales the continuous outputs space of the environment to a given range. By default, variables are rescaled between 0 and 1.

class energym.wrappers.transform_outputs.TransformOutputs(env, f)[source]¶

Transform the outputs via an arbitrary function. May be used, in particular, to add custom outputs.: Careful: the custom outputs are not registered in output_space. By rescaling, it is needed to first rescale and then add these custom outputs

Example:

>>> import energym
>>> env = energym.make('SimpleHouseSlab-v0')
>>> env = TransformObservation(env, lambda dict: f(dict))
>>> env.reset()

Args:: env (Env): environment f ({callable}): callable function on dictionary

class energym.wrappers.filter_outputs.FilterOutputs(env, filter_keys=None)[source]¶

Filter dictionary observations by their keys.

Args:

env: The environment to wrap. filter_keys: List of keys to be included in the observations.

Raises:

ValueError: If observation keys in not instance of None or: iterable.
ValueError: If any of the filter_keys are not included in: the original env’s observation space

StepWrapper ¶

class energym.wrappers.downsample_outputs.DownsampleOutputs(env, steps, downsampling_dic)[source]¶

Transform the outputs via an arbitrary function.

Example:

>>> TBD

Args:: env (Env): environment steps: number of downsampling steps downsampling_dic ({keys:callable}): keys and callable functions on them

get_forecast(forecast_length=24)[source]¶

Return forecasts for the environment.

Not implemented. Subclasses should override this method.

Raises

NotImplementedError

step(inputs)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

class energym.wrappers.rl_wrapper.RLWrapper(env, reward_function)[source]¶

Transform steps outputs to have rl (gym like) outputs timesteps, i.e. add rewards, done, and info Changes the outputs structure, from outputs to outputs, reward, done, info, as in gym. To be put at the end of all other wrappers. Example:

>>> TBD

Args:: env (Env): environment reward_function: reward function

step(inputs)[source]¶

Advances the simulation by one timestep.

Not implemented. Subclasses should override this method.

Parameters

actiondict: An action provided by the controller

Raises

NotImplementedError

InputsWrapper ¶

class energym.wrappers.clip_inputs.ClipInputs(env)[source]¶: Clip the continuous action within the valid bound.

class energym.wrappers.rescale_inputs.RescaleInputs(env, lower_bound=None, upper_bound=None)[source]¶: Rescales the continuous inputs space of the environment to a given range. By default, it is rescaled between 0 and 1.

Utils and Main Functions ¶

The make method ¶

energym.factory.make(key, eval_mode=False, **kwargs)[source]¶

Creates an instance of the requested simulation model.

Parameters

keystr: Name of the simulation model.
eval_modebool: Whether to return an instance of the evaluation scenario

Returns

Simulation model object: The instantiation of the corresponding simulation model.

Raises

Exception: If the requested model is not available or the configuration is not correct.

The KPI class ¶

class energym.envs.utils.kpi.KPI(kpi_options)[source]¶

A class to track the KPIs while running simulations.

The KPIs are customizable by specifying them in the kpi_options dict. An example for the dict looks as follows:

kpi_options = {

“kpi1”:{“name”:”Z01_T” ,”type”:”avg_dev”, “target”:[19,23]},

“kpi2”:{“name”:”Z01_T” ,”type”:”tot_viol”, “target”:[19,23]},

“kpi3”:{“name”:”Fa_Pw_All”,”type”:”avg”},

“kpi4”:{“name”:”Fa_Pw_All”, “type”:”sum”}

}

Possible KPI types are:

“avg”: The average over the given steps.
“sum”: The sum over the given steps.
“avg_dev”: The average deviation from a target (float or list).
“tot_viol”: The number of interval constraint violations for a
target interval (list).

Attributes

kpi_dict: dict: Dict of kpi related outputs with list of observations
num_obs: int: Number of saved observations

Methods

add_observations(obs)	Extracts relevant observations and appends them to the corresponding list.
get_kpi(start_ind, end_ind)	Computes the KPIs for a given time window.
get_cumulative_kpi(phrase, kpi_type, out_type)	Computes cumulative KPIs over multiple variables.
reset()	Frees up the storages in the object.

Parameters

kpi_optionsdict: Dict to specify the tracked KPIs.

add_observation(obs)[source]¶

Extracts relevant observations and appends them to the corresponding list.

Parameters

obsdict: Observation object to be tracked.

get_cumulative_kpi(names, kpi_type, out_type)[source]¶

Computes cumulative KPIs over multiple variables.

Parameters

nameslist or str: List of variable names or common string to filter the variables.
kpi_typestr: One of the 4 KPI types to filter the variables.
out_typestr: Cumulative KPI type (“avg” or “sum”).

Returns

float or int: Cumulative KPI value.

Raises

IndexError: If no variables fitting the criteria are detected.

get_kpi(start_ind=0, end_ind=- 1)[source]¶

Computes the KPIs for a given time window.

Parameters

start_indint, optional: Index determining the start of the time window, by default 0
end_indint, optional: Index determining the end of the time window, by default -1

Returns

kpi_summarydict: Dict containing the KPIs.

Raises

IndexError: If no observations are stored.

reset()[source]¶: Frees up the storages in the object.

The weather classes ¶

class energym.envs.utils.weather.Weather(names, delimiter)[source]¶

Base class for handling weather files.

The encapsulated weather file can be used for forecast generation. The logic is taken from https://github.com/building-energy/epw.

Attributes

headersdict: A dictionary containing the header rows of the weather file.
dataframepd.Dataframe: Stores the weather data.
nameslist of str: List of observed weather indicators.
delimiterstr: Separation character in the file.

Methods

read(fp)	Reads a weather file.
close()	Closes the data of the current weather file.

Parameters

nameslist of str: List of observed weather indicators.
delimiterstr: Separation character in the file.

close()[source]¶: Closes the data of the current weather file.

read(fp, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Reads a weather file. Generates associated forecasts if asked

Parameters

fpstr: The path to the file.
generate_forecasts: bool, optional: If True, generate forecasts dataframe
generate_forecast_method: {‘stochastic’, ‘perfect’, ‘persistence’}, optional: If ‘stochastic’, generate random forecast, If ‘perfect’, use actual weather as forecast. If ‘persistence’, persitence forecast from previous day
generate_forecast_keys: list, optional: List of keys to generate forecast for. By default is [“Dry Bulb Temperature”, “Global Horizontal Radiation”]

class energym.envs.utils.weather.EPW[source]¶

Class to represent an EnergyPlus weather (epw) file.

Subclasses Weather and inherits its data handling functions.

Methods

get_forecast(hour, day, month, forecast_length)

Provides a weather forecast for a requested length and requested keys.

get_forecast(hour, day, month, forecast_length)[source]¶

Provides a weather forecast for a requested length and requested keys.

Parameters

hourint: Current hour.
dayint: Current day.
monthint: Current month.
forecast_lengthint: Number of forecasted hours.

Returns

forecastdict: Containing a forecast of the requested length for the requested keys.

Raises

Exception: If no weather file has been loaded.
Exception: If the weather file has a non-standard format.

class energym.envs.utils.weather.MOS[source]¶

Class to represent a Modelica weather (mos) file.

Subclasses Weather and inherits its data handling functions.

Methods

get_forecast(time, forecast_length)

Provides a weather forecast for a requested length and requested keys.

Parameters

nameslist of str: List of observed weather indicators.
delimiterstr: Separation character in the file.

get_forecast(time, forecast_length)[source]¶

Returns a forecast for the next forecast_length hours.

Parameters

timeint: Start time of forecast
forecast_lengthint: Forecast length in hours

Returns

forecastdict: Containing a forecast of the requested length for the requested keys.

Raises

Exception: If no weather file has been loaded.

read(fp, generate_forecasts=True, generate_forecast_method='perfect', generate_forecast_keys=None)[source]¶

Reads a weather file from MOS.

Overrides the read method of Weather.

Parameters

fpstr: The path to the file.

Contributing