oreni.core

oreni.core

oreni.core

config

Dict

Bases: dict

dot.notation access to dictionary attributes

engine

Engine

Engine(*args, **kwargs)

Bases: Core

Base class for simulation engines.

This class provides the core functionality for managing and executing simulations. It inherits from Core and implements essential attributes and methods for handling simulation cases, variables, sensors, and data.

ATTRIBUTE	DESCRIPTION
_engine_directory	Directory path for engine operations TYPE: str
_output_data_path	Directory path for output data TYPE: str
_cases	List of simulation cases TYPE: list
_variables	List of simulation variables TYPE: list
_sensors	Dictionary of sensors TYPE: dict
_data	Pandas DataFrame for simulation data TYPE: DataFrame

data property writable

data

variables property writable

variables

This is the Vars attribute - each subclass of Foo gets its own. Lookups should follow the method resolution order.

sensors property writable

sensors

This is the Sensors attribute - each subclass of Foo gets its own. Lookups should follow the method resolution order.

output_data_path property writable

output_data_path

This is the _engine_directory attribute - each subclass of Foo gets its own. Lookups should follow the method resolution order.

logger

LoggerOreni

LoggerOreni(name='Oreni', level=DEBUG)

Bases: object

set_handlers

set_handlers(level=DEBUG)

Set the handlers for the logger.

PARAMETER	DESCRIPTION
level	The logging level to set for the handlers. Defaults to logging.DEBUG. TYPE: int DEFAULT: DEBUG

RETURNS	DESCRIPTION
	None

oreni.refurbishment

oreni.refurbishment

oreni.refurbishment

catalog

Catalog

Catalog(cat_schemas_dir)

Get the template for the general and specific (category dependant) descriptions of the products, Get the allowed products categories

instantiate_catalog

instantiate_catalog(cat_name)

Make a catalog embryo named "catname", containing several classes of products given by self.pdt_categories

PARAMETER	DESCRIPTION
cat_name	str, the name of the catalog TYPE: str

RETURNS	DESCRIPTION
None	Updated class with new attribute "cat_name"

update_product

update_product(
    cat_name,
    pdt_name,
    pdt_category,
    val,
    key_lv1,
    key_lv2=None,
)

According to the location (key_lv1 or key_lv2) of the parameter to be updated, the function modify its value "val"

PARAMETER	DESCRIPTION
cat_name	str, the name of the target catalog TYPE: str
pdt_name	str, the name of the target products to be updated TYPE: str
pdt_category	str, the class/category of the products to be updated TYPE: str
val	the value to be writen TYPE: Union[Dict, str, float, int]
key_lv1	the level 1 - of the dict tree structure - location f the parameter to be updated TYPE: str
key_lv2	the level 2 - of the dict tree structure - location f the parameter to be updated TYPE: Union[None, str] DEFAULT: None

RETURNS	DESCRIPTION
None	Updated attribute cat_name

add_product

add_product(cat_name, pdt_name, pdt)

Add a given products defined by "pdt" into the catalog "cat_name".

PARAMETER	DESCRIPTION
cat_name	str, the name of the target catalog TYPE: str
pdt_name	str, the name of the target products to be added TYPE: str
pdt	dict, the description of the products to be added into the catalog "cat_name" TYPE: Dict

RETURNS	DESCRIPTION
None	Updated attribute "cat_name"

remove_product

remove_product(cat_name, pdt_name, pdt_category)

Remove a target products "pdt_name" from a catalog "cat_name"

PARAMETER	DESCRIPTION
cat_name	str, the name of the target catalog TYPE: str
pdt_name	str, the name of the target products to be removed TYPE: str
pdt_category	str, the class/category of the products to be updated TYPE: str

RETURNS	DESCRIPTION
None	Updated attribute "cat_name"

works

Action

Action(act_schemas_dir)

Construction products, this one is picked up in a catalog

PARAMETER	DESCRIPTION
act_schemas_dir	path, the path of the directory containing the action templates TYPE: Path

instantiate_action

instantiate_action(act_name, act_category)

This method initialize an action, adding it to the class under the attribute "act_name" and described by the given json schema _schema.json

PARAMETER	DESCRIPTION
act_name	str, the name of the action TYPE: str
act_category	str, the category of the action, typically WallModification or WindowModification TYPE: str

RETURNS	DESCRIPTION
None	Updated class with new attribute "act_name"

set_action

set_action(act_name, val, key_lv1, key_lv2=None)

Given an action "act_name", set_action modify the value of a parameter described by it name key_kv1 (and eventually key_lv2) and its value val. The method check whether the key_lv1 and key_lv2 are consistent with the action schema

PARAMETER	DESCRIPTION
act_name	str, the name of the action to be added TYPE: str
val	the value of the parameter to be set TYPE: Union[Dict, str, float, int]
key_lv1	the name of the parameter to be set TYPE: str
key_lv2	the sub-name of the parameter to be set TYPE: Union[None, str] DEFAULT: None

RETURNS	DESCRIPTION
None	Updated attributed "act_name"

update_action

update_action(act, val, key_lv1, key_lv2=None)

Given an action "act_name", set_action modify the value of a parameter described by it name key_kv1 (and eventually key_lv2) and its value val. The method check whether the key_lv1 and key_lv2 are consistent with the action schema

PARAMETER	DESCRIPTION
act	the original description of action "act_name" TYPE: Dict
val	the value of the parameter to be set TYPE: Union[Dict, str, float, int]
key_lv1	the name of the parameter to be set TYPE: str
key_lv2	the sub-name of the parameter to be set TYPE: Union[None, str] DEFAULT: None

RETURNS	DESCRIPTION
act	the updated description of action "act_name" TYPE: Dict

add_action

add_action(act_name, act_category, act)

Given an action description through "act" dictionary, this method adds it to the class following the formalism given by the schema : for every parameter (key_lv1) and sub-parameter (key_lv2), the set_action function writes the param-value couple into the class attribute "act_name".

PARAMETER	DESCRIPTION
act_name	str, the name of the action to be added TYPE: str
act_category	str, the action category, typically wall modification or window modification TYPE: str
act	dict, the object containing the description of the action. It has to be consistent with the schema TYPE: Dict

RETURNS	DESCRIPTION
None	Updated attribute "act_name"

remove_n_layers

remove_n_layers(
    engine_ep,
    act_name,
    new_construction,
    new_construction_suffix="_REFURBISHED",
    target_construction_name=None,
    target_surface_names=None,
    layer_to_remove_indexes=None,
)

This method

1/ takes an Energy+ Construction object and remove some layers according to layer_to_remove_indexes based on the _remove_nlayers method. A copy of the original Construction is done in order that only the wanted target_surface_names are modified 2/ updates the name of the Construction used for every wall in the target_surface_names list

PARAMETER	DESCRIPTION
engine_ep	class, containing the Energy+ model given on an idf file format and methods to handle it, all TYPE: EnergyPlus
act_name	str, the name of the current action TYPE: Union[str, None]
new_construction	bool, if this action is in continuation of another one (typically remove_nlayers), set True and TYPE: bool
new_construction_suffix	str, if new_Construction is True, this parameter specify the suffix of the Construction name TYPE: str DEFAULT: '_REFURBISHED'
target_construction_name	str, the name of the Construction to be modified by the current action TYPE: Union[str, None] DEFAULT: None
target_surface_names	list of str, the list of the walls for which the Construction is going to be modified TYPE: Union[List[str], None] DEFAULT: None
layer_to_remove_indexes	list of int, the positions of the Material/layers to be removed TYPE: Union[List[int], None] DEFAULT: None

RETURNS	DESCRIPTION
None	Updated Energy+ idf file

add_n_layers

add_n_layers(
    engine_ep,
    act_name,
    catalog,
    cat_name,
    new_construction,
    new_construction_suffix="_REFURBISHED",
    target_construction_name=None,
    target_surface_names=None,
    layer_insert=None,
)

This method adds all the Materials in "Materials" at the correct position of the given Construction target_Construction_name. Then it updated the wanted target_surface_names to ensure they are using the resulting Construction

PARAMETER	DESCRIPTION
engine_ep	class, containing the Energy+ model given on an idf file format and methods to handle it, all TYPE: EnergyPlus
act_name	the action name, possibly None if the action detailed are pass through the args "Materials" TYPE: Union[str, None]
catalog	the catalog class objects TYPE: Catalog
cat_name	the catalog name TYPE: str
new_construction	if this action is in continuation of another one (typically remove_nlayers), set True and TYPE: bool
new_construction_suffix	if this action is not in the continuation of another one, set properly TYPE: str DEFAULT: '_REFURBISHED'
target_construction_name	the name of the Construction to be modified by the current action TYPE: Union[str, None] DEFAULT: None
target_surface_names	the list of the walls for which the Construction is going to be modified TYPE: Union[List[str], None] DEFAULT: None
layer_insert	the layer Materials to be inserted and their position TYPE: Union[Dict, None] DEFAULT: None

Returns:

set_reversed_layers_if_necessary

set_reversed_layers_if_necessary(engine_ep, constr_ex)

The fonction get the layers of REFURBISHED construction and set them in reversed order into a construction named xxx_REFURBISHED_Rev created beforehand. This is mandatory when a wall is shared between 2 thermal zones, one zone sees the initial construction, the other its reversed state. Args: engine_ep: class, containing the Energy+ model given on an idf file format and methods to handle it, all based on the eppy package constr_ex: EP Object, Modified construction

Returns: None

set_hvac_system

set_hvac_system(
    engine_ep,
    services_mapping,
    hvac_system_name,
    services,
    catalog,
    cat_name,
    target_hvac_system_name,
)

PARAMETER	DESCRIPTION
engine_ep	class, containing the Energy+ model given on an idf file format and methods to handle it, all TYPE: EnergyPlus
services_mapping	dictionary giving for each service : - the system supplying it and - the function to compute it TYPE: json
hvac_system_name	the name of the HVAC system to be added in the Energy+ idf file and the _hvac.json file
services	The service names concerned by the HVAC system modification TYPE: str
catalog	the catalog class objects TYPE: Catalog
cat_name	the catalog in which the fenestration has to be found TYPE: str
target_hvac_system_name	the name of the hvac systems to be refurbished TYPE: str

Returns:

Work

Work(duration, act_schema_dir, wks_schema_dir)

Bases: Action

When the renovation work require a Construction products, this one is picked up in a catalog

PARAMETER	DESCRIPTION
duration	Project lifetime in years. TYPE: int
act_schema_dir	the path of the directory containing the action schemas TYPE: Path
wks_schema_dir	the path of the directory containing the works schemas TYPE: Path

instantiate_works

instantiate_works(engine_ep, wks_name, services)

This method initialize a work, adding it to the class under the attribute "wks_name" and described by the given json schema

PARAMETER	DESCRIPTION
engine_ep	class, containing the Energy+ model given on an idf file format and methods to handle it, all TYPE: EnergyPlus
services	dictionary giving for each service : - the system supplying it and - the function to compute it TYPE: Any
wks_name	str, the name of the work TYPE: str

RETURNS	DESCRIPTION
None	Updated class with new attribute "wks_name"

remove_n_layers_work

remove_n_layers_work(
    act_name,
    act_dict,
    new_construction=True,
    new_construction_suffix="_REFURBISHED",
)

This method add the remove layers action into the work class, run the remove_n_layers function then update the metrics (economics, environmental, etc.) of the class

PARAMETER	DESCRIPTION
act_name	the name of the action to be run TYPE: str
act_dict	the description of the action, must follow the schema in .\Action_schemas TYPE: Dict
new_construction	if true, a new Construction will be added into the energy+ model, as a modification of TYPE: bool DEFAULT: True
new_construction_suffix	the name of the new_Construction in case where new_Construction is True TYPE: str DEFAULT: '_REFURBISHED'

Returns:

add_n_layers_work

add_n_layers_work(
    catalog,
    act_name,
    act_dict,
    cat_name,
    target_construction_name=None,
    new_construction=True,
    new_construction_suffix="_REFURBISHED",
)

This method add the add layers action into the work class, run the add_n_layers function then update the metrics (economics, environmental, etc.) metrics of the class

PARAMETER	DESCRIPTION
catalog	the catalog class objects TYPE: Catalog
act_name	the name of the action to be run TYPE: str
act_dict	the description of the action, must follow the schema in .\Action_schemas TYPE: Dict
cat_name	the name of the catalog in which the Materials have to be picked up TYPE: str
target_construction_name	the name of the Construction to be refurbished TYPE: Union[str, None] DEFAULT: None
new_construction	if true, a new Construction will be added into the energy+ model, as a modification of TYPE: bool DEFAULT: True
new_construction_suffix	the name of the new_Construction in case where new_Construction is True TYPE: str DEFAULT: '_REFURBISHED'

Returns:

modify_walls

modify_walls(
    catalog,
    cat_name,
    remove_layers_dict,
    add_layers_dict,
    rmv_action_name="RemoveLayers",
    add_action_name="AddLayers",
    newconstrsuffix="_REFURBISHED",
)

This method combines removing and adding layer actions in order to represent a real wall refurbishment work. It first modifies the idf file according to both actions, then calculate the action global detailed economics and environmental costs

PARAMETER	DESCRIPTION
catalog	the catalog class objects TYPE: Catalog
cat_name	str, the name of the catalog in which the Material has to be picked up TYPE: str
remove_layers_dict	dict, the description of the removing layers action TYPE: Dict
add_layers_dict	dict, the description of the adding layers action TYPE: Dict
rmv_action_name	str, the name of the removing layers action TYPE: str DEFAULT: 'RemoveLayers'
add_action_name	str, the name of the adding layers action TYPE: str DEFAULT: 'AddLayers'
newconstrsuffix	str, the suffix to be added to the construction to be modified TYPE: str DEFAULT: '_REFURBISHED'

Returns:

modify_fenestration

modify_fenestration(
    catalog,
    cat_name,
    rpl_windows_dict,
    rpl_windows_action_name="ReplaceWindows",
)

This method is based on the _set_fenestration action in order to represent a real window refurbishment work. It first modifies the idf file according to this action, then calculate the action global detailed economics and environmental costs

PARAMETER	DESCRIPTION
catalog	the catalog class objects TYPE: Catalog
cat_name	str, the name of the catalog in which the window Material has to be picked up TYPE: str
rpl_windows_dict	dict, the description of the window replacement action TYPE: Dict
rpl_windows_action_name	str, the name of the window replacement action TYPE: str DEFAULT: 'ReplaceWindows'

Returns:

modify_hvac

modify_hvac(
    catalog,
    cat_name,
    rpl_hvac_dict,
    rpl_hvac_action_name="ReplaceHVAC",
)

This method is based on the _set_fenestration action in order to represent a real window refurbishment work. It first modifies the idf file according to this action, then calculate the action global detailed economics and environmental costs

PARAMETER	DESCRIPTION
catalog	the catalog class objects TYPE: Catalog
cat_name	str, the name of the catalog in which the window Material has to be picked up TYPE: str
rpl_hvac_dict	dict, the description of the HVAC system replacement action TYPE: Dict
rpl_hvac_action_name	str, the name of the HVAC system replacement action TYPE: str DEFAULT: 'ReplaceHVAC'

Returns:

update_metric

update_metric(metric='Economics')

This method calculate the cumulated costs of all the actions carried out on the same building. It updates the description of economics/environmental metrics at the work level

PARAMETER	DESCRIPTION
metric	str, the name of the metrics to be updated. At the moment, only Economics and Environmental TYPE: str DEFAULT: 'Economics'

Returns:

Uncertainties

Uncertainties(schemas_dir)

instantiate_modifications

instantiate_modifications(
    engine_ep, unc_name, unc_category
)

This method initialize a set of modifications due to uncertainties, adding it to the class under the attribute "unc_name" and described by the given json schema

PARAMETER	DESCRIPTION
engine_ep	class, containing the Energy+ model given on an idf file format and methods to handle it, all TYPE: EnergyPlus
unc_name	str, the name of the uncertainties set TYPE: str
unc_category	str, the category of the uncertainty, typically Economics, Occupancy, Weather, Ground or AirRenewal TYPE: str

RETURNS	DESCRIPTION
None	Updated class with new attribute "unc_name"

erase_occ_var_modelDescription

erase_occ_var_modelDescription(tree, overlooked_strings)

add_occ_var_modelDescription

add_occ_var_modelDescription(tree, overlooked_strings)

delete_occupant_idf

delete_occupant_idf(
    idf,
    external_schedules,
    search_strings,
    nb_agents,
    attribute="Name",
)

The idf file is developed for the maximum occupants' Gauge in the building, this function allows to delete some of them according to the occupation scenario running Args: external_schedules: idf ExternalInterface MockUP or Output:Variable objects search_strings: lists of string to be searched for nb_agents: maximum occupants' Gauge, int attribute: string corresponding to the attribute in the idf object overlooked

Returns: Nothing

set_modify_wall_args

set_modify_wall_args(act_name, act)

Split an action on walls into two parts, the first one relative to add layers only and the second one to remove layers only

PARAMETER	DESCRIPTION
act_name	action name TYPE: str
act	action full description TYPE: Dict

RETURNS	DESCRIPTION
rmv_action_name	the name of the partial action relative to the "remove layers" part TYPE: [str, Dict, str, Dict]
removelayers_dict	the description of the partial action relative to the "remove layers" part TYPE: [str, Dict, str, Dict]
add_action_name	the name of the partial action relative to the "add layers" part TYPE: [str, Dict, str, Dict]
addlayers_dict	the description of the partial action relative to the "add layers" part TYPE: [str, Dict, str, Dict]

oreni.cost_functions

oreni.cost_functions

oreni.cost_functions

CostFunction

Bases: ABC

Classe de base abstraite pour toute fonction de coût.

compute abstractmethod

compute(output_of_run_EP)

Méthode à implémenter dans toutes les sous-classes.

CostComfort_AgentModel

CostComfort

CostComfort(
    write_csv_file=False,
    output_step="TimeStep",
    rooms_corresp={},
    *args,
    **kwargs
)

Bases: CostFunction

calculate_DH_occupant_walk

calculate_DH_occupant_walk(df, rooms_corresp)

This function calculates the °C.H for feeling hot above EN 16798-1 Category I of comfort Args: df: Pandas DataFrame, issued from csv files rooms_corresp: a dict where the numbers depicting rooms in NoMASS are linked to the actual names depicting those rooms. As an example: {1: "KITCHEN", 2: "LIVINGROOM", 3: "BATHROOM", 4: "MASTERBEDROOM", 5: "BEDROOM", 6: "OFFICE"}

Returns:

CostComfort_PMV_RoomLevel

CostComfort

CostComfort(output_step='TimeStep')

Bases: CostFunction

compute_hourly_comfort

compute_hourly_comfort(df, met=1.2, clo=0.5, air_speed=0.1)

Compute hourly PMV and PPD by estimating indoor relative humidity assuming indoor absolute humidity equals outdoor absolute humidity.

PARAMETER	DESCRIPTION
df	must contain: - 'ta' (indoor air temperature, °C), - 'tr' (mean radiant temperature, °C), - 'tdp_ext' (outdoor dew point temperature, °C), - 'p_atm' (atmospheric pressure, Pa). TYPE: DataFrame
met	metabolic rate (met). TYPE: float DEFAULT: 1.2
clo	clothing insulation (clo). TYPE: float DEFAULT: 0.5
air_speed	air speed (m/s). TYPE: float DEFAULT: 0.1

RETURNS	DESCRIPTION
DataFrame	pd.DataFrame: input DataFrame with added columns: - 'RH_int' (indoor relative humidity, %), - 'PMV' (predicted mean vote), - 'PPD' (predicted percentage dissatisfied, %).

aggregate_annual_comfort

aggregate_annual_comfort(df)

Aggregate hourly comfort metrics into annual indicators.

Args: df (pd.DataFrame): must contain columns 'PMV' and 'PPD'.

dict: annual comfort indicators: - 'mean_PMV', - 'mean_PPD', - 'discomfort_hours_percentage' (PMV < -0.5 or > 0.5), - 'weighted_PPD_factor' (average discomfort factor).

CostEnergyConsumption

CostEnergyConsumption

CostEnergyConsumption(
    services, catalog_hvac, output_step="TimeStep"
)

Bases: CostFunction

            - the system supplying it and
            - the function to compute it

catalog_hvac: catalog of hvac products output_step:

compute

compute(output_of_run_EP)

PARAMETER	DESCRIPTION
output_of_run_EP	outputs of EnergyPlusforOptim.run_ep TYPE: Tuple

Returns: dictionary of {service: energy_consumption}

CostEnergyNeeds

CostEnergyNeeds

CostEnergyNeeds(service='Heating', output_step='TimeStep')

Bases: CostFunction

output_step: str = "Hourly" or "TimeStep"

CostLifeCycleAssessment

CostLifeCycleAssessment

CostLifeCycleAssessment(
    catalog,
    cat_name,
    energies_data,
    duration=50,
    output_step="TimeStep",
)

Bases: CostFunction

cat_name: the name of the catalog in which information relative to the products has to be looked for energies_data: path toward a dictionary giving for each energy (vector) its unitary cost and CO2 emissions output_step: the Energy+ output data time step

compute

compute(output_of_run_EP)

PARAMETER	DESCRIPTION
output_of_run_EP	outputs of EnergyPlusforOptim.run_ep

Returns: the life cycle assessment (CO2 emissions) of one building renovation alternative

get_annual_maintenance_co2emissions

get_annual_maintenance_co2emissions()

Args: Returns: total annual CO2 emissions due maintenance operations

get_annual_energy_consumption_co2emissions

get_annual_energy_consumption_co2emissions()

Args: Returns: annual energy consumption cost for every service in self.services

life_cycle_assessment

life_cycle_assessment(
    initial_impact,
    duration,
    services_impact,
    maintenance_impact,
    replacements_impact,
)

Calculate the total life cycle assessment (LCA) of a renovation project. At the moment, it only takes into account CO2 emissions

PARAMETER	DESCRIPTION
initial_impact	Initial environmental impact of the project (materials + works). TYPE: float
duration	Analysis period in years. TYPE: int
services_impact	Annual environmental impact of energy consumptions. TYPE: float
maintenance_impact	Annual environmental impact of operating and maintaining the system. TYPE: float
replacements_impact	array of impacts, each index being the year of replacements/major maintenance. TYPE: ndarray[float]

RETURNS	DESCRIPTION
float	Total life cycle CO2 emissions over the specified duration. TYPE: float

CostLifeCycleCost

CostLifeCycleCost

CostLifeCycleCost(
    catalog,
    cat_name,
    inflation_energies,
    inflation_maintenance,
    inflation_replacement,
    energies_data,
    duration=50,
    discount_rate=0.03,
    output_step="TimeStep",
)

Bases: CostFunction

cat_name: the name of the catalog in which information relative to the products has to be looked for inflation_energies: dict[float or array of float] giving for every energy, the inflation rate its annual expenses. If one float is given, the same inflation rate will be used for the whole calculation over the duration inflation_maintenance: float or array of float giving the inflation rate for annual maintenance expenses. If one float is given, the same inflation rate will be used for the whole calculation over the duration inflation_replacement: float or array of float giving the inflation rate for annual replacement expenses. If one float is given, the same inflation rate will be used for the whole calculation over the duration energies_data: path toward a dictionary giving for each energy (vector) its unitary cost and CO2 emissions duration: time duration of the calculation (typically 30 or 50 years) discount_rate: the discount rate (>0) output_step: the Energy+ output data time step

compute

compute(output_of_run_EP)

PARAMETER	DESCRIPTION
output_of_run_EP	outputs of EnergyPlusforOptim.run_ep

Returns: the life cycle cost of one building renovation alternative

get_annual_services_cost

get_annual_services_cost()

Args: Returns: annual energy consumption cost for every service in self.services

get_inflation

get_inflation(inflation, year)

Retrieve the inflation value for a given year.

PARAMETER	DESCRIPTION
inflation	Either a constant inflation rate or an array of inflation values. TYPE: float or ndarray[float]
year	Year for which to retrieve the inflation (1-based index). TYPE: int

RETURNS	DESCRIPTION
float	Inflation rate for the specified year. TYPE: float

discount

discount(value, discount_rate, year, inflation=0.0)

Discount a future value to its present value using the real discount rate.

PARAMETER	DESCRIPTION
value	Future cost to be discounted. TYPE: float
discount_rate	Nominal annual discount rate (e.g., 0.03 for 3%). TYPE: float
year	Number of years in the future the cost occurs. TYPE: int
inflation	Inflation rate(s). Can be constant or vary yearly. Defaults to 0.0. TYPE: float or ndarray[float] DEFAULT: 0.0

RETURNS	DESCRIPTION
float	Present value of the future cost. TYPE: float

discounted_sum

discounted_sum(
    duration, cost_function, discount_rate, inflation=0.0
)

Generic function to compute the discounted sum of values over time.

PARAMETER	DESCRIPTION
duration	Number of years. TYPE: int
cost_function	Function returning the cost for a given year (1-based). TYPE: Callable[[int], Union[float, ndarray]]
discount_rate	Nominal annual discount rate. TYPE: float
inflation	Inflation rate(s). Defaults to 0.0. TYPE: float or List[float] DEFAULT: 0.0

RETURNS	DESCRIPTION
float	Total discounted value. TYPE: float

operating_maintenance_cost

operating_maintenance_cost(
    duration, annual_cost, discount_rate, inflation=0.0
)

Compute discounted cost of maintenance over time.

PARAMETER	DESCRIPTION
duration	Number of years the cost occurs. TYPE: int
annual_cost	Cost incurred each year. TYPE: float or ndarray[float]
discount_rate	Nominal annual discount rate. TYPE: float
inflation	Inflation rate(s) for O&M costs. Defaults to 0.0. TYPE: float or ndarray[float] DEFAULT: 0.0

RETURNS	DESCRIPTION
float	Present value of total O&M costs over the duration. TYPE: float | None

operating_energies_cost

operating_energies_cost(
    duration, services_cost, discount_rate, inflation
)

Calculate the present value of recurring annual operating and maintenance costs.

PARAMETER	DESCRIPTION
duration	Number of years the cost occurs. TYPE: int
services_cost	Cost incurred each year. TYPE: float or ndarray
discount_rate	Nominal annual discount rate. TYPE: float
inflation	Inflation rate(s) for energy costs. Defaults to 0.0. TYPE: dict[str, Union[float, ndarray]]

RETURNS	DESCRIPTION
float	Present value of total energy costs over the building lifespan. TYPE: float

replacement_cost

replacement_cost(
    duration, replacements, discount_rate, inflation=0.0
)

Compute discounted cost of replacements/ major maintenance, either constant or yearly array.

PARAMETER	DESCRIPTION
duration	Project lifetime in years. TYPE: int
replacements	A single float: same cost every year. A NumPy array of floats: one cost per year (length must match duration). TYPE: float or ndarray
discount_rate	Nominal annual discount rate. TYPE: float
inflation	Inflation rate(s) for replacements. Defaults to 0.0. TYPE: float or list of float DEFAULT: 0.0

RETURNS	DESCRIPTION
float	Present value of total replacement/maintenance costs. TYPE: float

life_cycle_cost

life_cycle_cost(
    initial_cost,
    duration,
    services_cost,
    maintenance_cost,
    replacements_cost,
    discount_rate,
    inflation_energies,
    inflation_maintenance=0.0,
    inflation_replacement=0.0,
)

Calculate the total life cycle cost (LCC) of a renovation project.

PARAMETER	DESCRIPTION
initial_cost	Initial capital cost of the project. TYPE: float
duration	Analysis period in years. TYPE: int
services_cost	energy consumption cost for each service. TYPE: dict[str, float or ndarray]
maintenance_cost	Annual cost of operating and maintaining the system. TYPE: float
replacements_cost	array of costs, each index being the year of replacements/major maintenance. TYPE: ndarray
discount_rate	Nominal annual discount rate. TYPE: float
inflation_energies	Inflation rate(s) for energies costs. Defaults to 0.0. TYPE: dict[str, float or ndarray]
inflation_maintenance	Inflation rate(s) for maintenance costs. Defaults to 0.0. TYPE: float or ndarray DEFAULT: 0.0
inflation_replacement	Inflation rate(s) for replacements. Defaults to 0.0. TYPE: float or ndarray DEFAULT: 0.0

RETURNS	DESCRIPTION
float	Total discounted life cycle cost over the specified duration. TYPE: float

oreni.uncertainties

oreni.uncertainties

oreni.uncertainties

UncertainSpace

UncertainSpace

UncertainSpace(unc_space_schema_dir)

get_columns

get_columns()

Builds a pandas MultiIndex from the uncertain spaces stored in self.uncertain_space. For each uncertain space, the first level is the uncertainty name (from "Name") and the second level is the alias list defined in the uncertain space description (the "Alias" field). This method extracts the alias names directly.

oreni.engine

oreni.engine

oreni.engine

EnergyPlus

EnergyPlus

EnergyPlus(output_step='TimeStep', *args, **kwargs)

Bases: Engine

getObjectFields

getObjectFields(object_type)

This function takes an object type and an IDD file, and returns the fields, their type, and any possible keys for the given object type, in the form of a dictionary.

PARAMETER	DESCRIPTION
object_type	The type of the object to query. TYPE: str

RETURNS	DESCRIPTION
Dict	A dictionary containing either the fields with their types and keys, or an error message if the object type is not found. TYPE: Dict

SetAndRun1Simulation

SetAndRun1Simulation

SetAndRun1Simulation(
    duration,
    run_dir,
    idf_path,
    epw_path,
    services_path,
    root_path,
    fmu_path=None,
    output_step="Hourly",
    save_idf=False,
    save_csv=False,
    debug=False,
)

- run the resulting model
- compute various cost functions, some of them using the simulation results

Args:

duration: the building’s service life before deconstruction, in years run_dir: the directory in which the Energy+ model is going to be run idf_path: the absolute path to the original Energy+ model epw_path: the absolute path to the weather file services_path: the absolute path to the json file describing the HVAC systems x services root_path: optional, the directory in which the source code can be found fmu_path: the absolute path to the fmu file, only for the cases where agent based occupancy model is used output_step: the time step of the Energy+ outputs (usually Hourly or Timestep) save_idf: if True, the modified .idf file will be saved save_csv: if True, the results csv file will be saved debug: if yes, print debug info del_wks: if True, the WorksXUncertainties class instance will be removed from the current class

instantiate_uncertain_design_problem

instantiate_uncertain_design_problem(
    actions, cost_functions, catalog, cat_name, metrics
)

decision space + catalog,

cost functions, and uncertain space. Then, it instantiates the WorkXUncertainties class enabling the representation of building + context modifications

PARAMETER	DESCRIPTION
actions	the list of refurbishment action to be combined and applied to the building TYPE: List[Tuple]
cost_functions	the objective functions to be optimized TYPE: List
catalog	the catalog used by the optimization process TYPE: Catalog
cat_name	the catalog name TYPE: str
metrics	the list of quantities/evaluations to be updated while running the refurbishment actions TYPE: List[str]

Returns:

instantiate_uncertain_works_framework

instantiate_uncertain_works_framework(wksXunc_name)

This function : - instantiates and initializes the Energy+ model wrapper (eppy object class) with the given .idf and epw. files. - Load the services description from the json file - instantiates the class (WorksXUncertainties) to handle and modify a building retrofit project

PARAMETER	DESCRIPTION
wksXunc_name	the name of one simulation TYPE: str

Returns:

set_action_j_from_design_i

set_action_j_from_design_i(
    design_i, decision_space_dim_j, act_name
)

From the i-th refurbishment design (in design_i), and the j_th retrofit action (in decision_space_dim_j), this function build an action dictionary fully described

PARAMETER	DESCRIPTION
design_i	the i-th design is a set of renovation actions TYPE: DataFrame
decision_space_dim_j	the j-th renovation action of the i-th design TYPE: Dict
act_name	the name of the j-th renovation action of the i-th design TYPE: str

RETURNS	DESCRIPTION
action	a dictionary containing the full description of a refurbishment action TYPE: Dict

construct_input_1action

construct_input_1action(act_name, action, cat_name)

Considering that one simulation ("simulation") is a combination of different action, this method set the Energy+ .idf file to hold one action, given by its name "act_name" and description "act"

PARAMETER	DESCRIPTION
act_name	the name of the action to be run TYPE: str
action	the description of the static (unchanged while optimizing) and variable (change according to the TYPE: Dict
cat_name	the name of the catalog to be used TYPE: str

Returns:

construct_input_1design_static

construct_input_1design_static(cat_name, metrics)

Considering that an experience design is a set of several simulations, itself a combination of different actions, this method set one Energy+ .idf file to hold each action of the simulation "design_num", and update the linked evaluation metrics

PARAMETER	DESCRIPTION
cat_name	the name of the catalog to be used TYPE: str
metrics	the list of evaluations to be updated while running the refurbishment actions TYPE: List

Returns:

run_ep

run_ep(file_name, output_directory)

Run Energy+ simulation for file_name .idf file modified according to information given by experience_i_design

PARAMETER	DESCRIPTION
file_name	the name to be given to the i-th simulation TYPE: str
output_directory	the directory path for the simulation outputs TYPE: Path

RETURNS	DESCRIPTION
output_directory	the directory path for the simulation outputs TYPE: None
file_name	the name to be given to the i-th simulation TYPE: Path
run_dir	the directory of running simulation TYPE: str
idf_to_return	the resulting idf eppy object TYPE: Path

compute_cost_functions

compute_cost_functions(file_name)

PARAMETER	DESCRIPTION
file_name	the name of the model to be run TYPE: str

RETURNS	DESCRIPTION
cost	the refurbishment works assessment according to one or several cost functions TYPE: Union[float, List[float]]

SetAndRunSimulations

SetAndRunSimulations

SetAndRunSimulations(
    duration,
    run_dir,
    idf_path,
    epw_path,
    services_path,
    root_path,
    fmu_path=None,
    output_step="Hourly",
    save_idf=False,
    save_csv=False,
    debug=False,
    del_wks=True,
)

- run the resulting model
- compute various cost functions, some of them using the simulation results

Args:

duration: the building’s service life before deconstruction, in years run_dir: the directory in which the Energy+ model is going to be run idf_path: the absolute path to the original Energy+ model epw_path: the absolute path to the weather file services_path: the absolute path to the json file describing the HVAC systems x services root_path: optional, the directory in which the source code can be found fmu_path: the absolute path to the fmu file, only for the cases where agent based occupancy model is used output_step: the time step of the Energy+ outputs (usually Hourly or Timestep) save_idf: if True, the modified .idf file will be saved save_csv: if True, the results csv file will be saved debug: if yes, print debug info del_wks: if True, the WorksXUncertainties class instance will be removed from the current class

instantiate_uncertain_design_problem

instantiate_uncertain_design_problem(
    decision_space,
    uncertain_space,
    cost_functions,
    catalog,
    cat_name,
    metrics,
)

decision space + catalog,

cost functions, and uncertain space. Then, it instantiates the WorkXUncertainties class enabling the representation of building + context modifications

PARAMETER	DESCRIPTION
decision_space	object class describing the set of retrofit actions TYPE: Union[DecisionSpace, None]
uncertain_space	object class describing the set of uncertainties TYPE: Union[UncertainSpace, None]
cost_functions	the objective functions to be optimized TYPE: List
catalog	the catalog used by the optimization process TYPE: Catalog
cat_name	the catalog name TYPE: str
metrics	the list of quantities/evaluations to be updated while running the refurbishment actions TYPE: List[str]

Returns:

instantiate_uncertain_works_framework

instantiate_uncertain_works_framework(wksXunc_name)

This function : - instantiates and initializes the Energy+ model wrapper (eppy object class) with the given .idf and epw. files. - Load the services description from the json file - instantiates the class (WorksXUncertainties) to handle and modify a building retrofit project

PARAMETER	DESCRIPTION
wksXunc_name	the name of one simulation TYPE: str

Returns:

set_action_j_from_design_i

set_action_j_from_design_i(
    design_i, decision_space_dim_j, act_name
)

From the i-th refurbishment design (in design_i), and the j_th retrofit action (in decision_space_dim_j), this function build an action dictionary fully described

PARAMETER	DESCRIPTION
design_i	the i-th design is a set of renovation actions TYPE: DataFrame
decision_space_dim_j	the j-th renovation action of the i-th design TYPE: Dict
act_name	the name of the j-th renovation action of the i-th design TYPE: str

RETURNS	DESCRIPTION
action	a dictionary containing the full description of a refurbishment action TYPE: Dict

set_uncertainty_i_from_var_j

set_uncertainty_i_from_var_j(
    uncertain_draw_i, uncertain_space_dim_j, unc_name
)

From the i-th uncertainties draw (in uncertain_draw_i), and the j_th uncertainty of this draw (in uncertain_space_dim_j), this function build an uncertainty dictionary fully defined

PARAMETER	DESCRIPTION
uncertain_draw_i	the i-th draw of uncertainties set TYPE: DataFrame
uncertain_space_dim_j	the j-th uncertainty of the i_th uncertain draw TYPE: Dict
unc_name	the name of the j-th uncertainty of the i_th uncertain draw TYPE: str

RETURNS	DESCRIPTION
uncertainty	a dictionary containing the full description of an uncertainty TYPE: Dict

construct_input_uncertainty

construct_input_uncertainty(
    unc_name, uncertain_space_dim_j, uncertainties_draw_i
)

Considering that one simulation "i" is a combination of different uncertainties, this method set the Energy+ .idf file to hold one uncertainty, given by its name "unc_name" and description from uncertain_space_dim_j and uncertainties_draw_i

PARAMETER	DESCRIPTION
unc_name	the name of the j-th uncertainty of the i_th uncertain draw TYPE: str
uncertain_space_dim_j	the j-th uncertainty of the i_th uncertain draw TYPE: Dict
uncertainties_draw_i	the i-th draw of uncertainties set TYPE: DataFrame

Returns:

construct_input_1uncertaintiesdraw

construct_input_1uncertaintiesdraw(uncertainties_i)

PARAMETER	DESCRIPTION
uncertainties_i	the set of uncertainties to be combined and applied to the building retrofit project, for the i_th simulation TYPE: DataFrame

Returns:

construct_input_1action

construct_input_1action(
    act_name,
    decision_space_dim_j,
    experience_design_i,
    cat_name,
)

Considering that one simulation is a combination of different actions, this function set the Energy+ .idf file to hold one action, given by its name "act_name" and description from decision_space_dim_j and experience_design_i

PARAMETER	DESCRIPTION
act_name	the name of the j-th renovation action of the i-th design TYPE: str
decision_space_dim_j	the j-th renovation action of the i-th design TYPE: Dict
experience_design_i	the i-th design is a set of renovation actions TYPE: DataFrame
cat_name	the name of the catalog to be used TYPE: str

Returns:

construct_input_1design

construct_input_1design(
    experience_design_i, cat_name, metrics
)

Considering that an experience design is a set of several simulations, itself a combination of different actions, this method set one Energy+ .idf file to hold each action of the experience_i_design and update the assessment metrics

PARAMETER	DESCRIPTION
experience_design_i	the set of refurbishment action to be combined and applied to the building TYPE: DataFrame
cat_name	the name of the catalog to be used TYPE: str
metrics	the list of assessments to be updated while running the refurbishment actions TYPE: List

Returns:

run_ep

run_ep(
    uncertain_experience_i,
    file_name,
    output_directory,
    use_energyplus_api=False,
)

Run Energy+ simulation for file_name .idf file modified according to information given by experience_i_design

PARAMETER	DESCRIPTION
use_energyplus_api	TYPE: bool DEFAULT: False
uncertain_experience_i	the i-th set of refurbishment actions and uncertainties to be combined and applied to the building TYPE: DataFrame
file_name	the name to be given to the i-th simulation TYPE: str
output_directory	the directory path for the simulation outputs TYPE: Path

RETURNS	DESCRIPTION
experience_i_design	the i-th set of refurbishment actions TYPE: DataFrame
uncertainties_i	the i-th set of uncertainties TYPE: Path
output_directory	the directory path for the simulation outputs TYPE: str
file_name	the name to be given to the i-th simulation TYPE: Path
run_dir	the directory of running simulation TYPE: Any
idf_to_return	the resulting idf eppy object TYPE: Any

compute_cost_functions

compute_cost_functions(xu_batch, iteration)

PARAMETER	DESCRIPTION
xu_batch	the input data to be set in the .idf file Energy+ model - design part x uncertainty part TYPE: Iterable
iteration	the index of the simulation TYPE: str

RETURNS	DESCRIPTION
cost	the refurbishment works assessment according to one or several cost functions TYPE: Union[float, List[float]]

oreni.optim

oreni.optim

oreni.optim

DiscreteVariableEncoder

DiscreteVariableEncoder(decision_space)

Encoder for discrete unordered variables to work with BoTorch.

BoTorch requires continuous variables, so we encode discrete variables using one-hot encoding or integer encoding with appropriate bounds.

encode_design

encode_design(design_df)

Encode a design DataFrame to continuous tensor for BoTorch.

decode_design

decode_design(encoded_tensor, design_df)

Decode a continuous tensor back to discrete design DataFrame.

botorch_multi_objective_optimizer

botorch_multi_objective_optimizer(
    function,
    decision_space,
    uncertain_space,
    function_labels,
    n_initial_points=10,
    n_optimization_iterations=20,
    n_uncs=10,
    n_occ_rdm=1,
    n_jobs=cpu_count() - 1,
    acquisition_function="qEHVI",
    reference_point=None,
    batch_size=1,
    raw_samples=512,
    num_restarts=10,
)

Multi-objective optimization using BoTorch with support for discrete unordered variables.

PARAMETER	DESCRIPTION
function	Function to optimize (should return list of objective values) TYPE: Callable
decision_space	Decision space definition TYPE: DecisionSpace
uncertain_space	Uncertain space definition (optional) TYPE: Optional[UncertainSpace]
function_labels	Labels for objective functions TYPE: List[str]
n_initial_points	Number of initial random points for exploration TYPE: int DEFAULT: 10
n_optimization_iterations	Number of optimization iterations TYPE: int DEFAULT: 20
n_uncs	Number of uncertainty samples per design TYPE: int DEFAULT: 10
n_occ_rdm	Number of occupancy samples per uncertainty TYPE: int DEFAULT: 1
n_jobs	Number of parallel jobs TYPE: int DEFAULT: cpu_count() - 1
acquisition_function	Type of acquisition function ("qEHVI", "qNEHVI", etc.) TYPE: str DEFAULT: 'qEHVI'
reference_point	Reference point for hypervolume calculation TYPE: Optional[List[float]] DEFAULT: None
batch_size	Batch size for parallel evaluation TYPE: int DEFAULT: 1
raw_samples	Number of random samples for acquisition function optimization (higher = more robust but slower) TYPE: int DEFAULT: 512
num_restarts	Number of optimization restarts for acquisition function optimization TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
Tuple[DataFrame, DataFrame, DataFrame]	Tuple of (uncertain_design, experience_design, uncertain_draws)

get_device_info

get_device_info()

Get information about the current PyTorch device configuration.

botorch_multi_objective_optimizer_kernel

botorch_multi_objective_optimizer_kernel(
    function,
    decision_space,
    uncertain_space,
    function_labels,
    n_initial_points=10,
    n_optimization_iterations=2,
    n_uncs=2,
    n_occ_rdm=1,
    n_jobs=cpu_count() - 1,
    acquisition_function="qEHVI",
    reference_point=None,
    batch_size=1,
    raw_samples=512,
    num_restarts=10,
    kernel_type="mixed",
    fallback_to_simple_kernel=True,
)

Multi-objective optimization using BoTorch with support for discrete unordered variables.

PARAMETER	DESCRIPTION
function	Function to optimize (should return list of objective values) TYPE: Callable
decision_space	Decision space definition TYPE: DecisionSpace
uncertain_space	Uncertain space definition (optional) TYPE: Optional[UncertainSpace]
function_labels	Labels for objective functions TYPE: List[str]
n_initial_points	Number of initial random points for exploration TYPE: int DEFAULT: 10
n_optimization_iterations	Number of optimization iterations TYPE: int DEFAULT: 2
n_uncs	Number of uncertainty samples per design TYPE: int DEFAULT: 2
n_occ_rdm	Number of occupancy samples per uncertainty TYPE: int DEFAULT: 1
n_jobs	Number of parallel jobs TYPE: int DEFAULT: cpu_count() - 1
acquisition_function	Type of acquisition function ("qEHVI", "qNEHVI", etc.) TYPE: str DEFAULT: 'qEHVI'
reference_point	Reference point for hypervolume calculation TYPE: Optional[List[float]] DEFAULT: None
batch_size	Batch size for parallel evaluation TYPE: int DEFAULT: 1
raw_samples	Number of random samples for acquisition function optimization (higher = more robust but slower) TYPE: int DEFAULT: 512
num_restarts	Number of optimization restarts for acquisition function optimization TYPE: int DEFAULT: 10
kernel_type	Type of kernel to use ("mixed", "matern", "rbf", "categorical") TYPE: str DEFAULT: 'mixed'
fallback_to_simple_kernel	Whether to fallback to simple RBF kernel on numerical issues TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Tuple[DataFrame, DataFrame, DataFrame]	Tuple of (uncertain_design, experience_design, uncertain_draws)

DecisionSpace

DecisionSpace

DecisionSpace(decision_schema_dir, act_schemas_dir)

get_columns

get_columns()

Builds a pandas MultiIndex from the decision spaces stored in self.decision_space. For each decision space, the first level is the action name (from "Name") and the second level is the alias list defined in the decision space description (the "Alias" field). This method extracts the alias names directly.

botorch_optimization

BoTorch-based multi-objective optimization for ORENI framework.

This module provides optimization capabilities using BoTorch for multi-objective optimization with discrete unordered variables, specifically designed for building renovation optimization under uncertainties.

DiscreteVariableEncoder

DiscreteVariableEncoder(decision_space)

Encoder for discrete unordered variables to work with BoTorch.

BoTorch requires continuous variables, so we encode discrete variables using one-hot encoding or integer encoding with appropriate bounds.

encode_design

encode_design(design_df)

Encode a design DataFrame to continuous tensor for BoTorch.

decode_design

decode_design(encoded_tensor, design_df)

Decode a continuous tensor back to discrete design DataFrame.

get_device_info

get_device_info()

Get information about the current PyTorch device configuration.

botorch_multi_objective_optimizer

botorch_multi_objective_optimizer(
    function,
    decision_space,
    uncertain_space,
    function_labels,
    n_initial_points=10,
    n_optimization_iterations=20,
    n_uncs=10,
    n_occ_rdm=1,
    n_jobs=cpu_count() - 1,
    acquisition_function="qEHVI",
    reference_point=None,
    batch_size=1,
    raw_samples=512,
    num_restarts=10,
)

Multi-objective optimization using BoTorch with support for discrete unordered variables.

PARAMETER	DESCRIPTION
function	Function to optimize (should return list of objective values) TYPE: Callable
decision_space	Decision space definition TYPE: DecisionSpace
uncertain_space	Uncertain space definition (optional) TYPE: Optional[UncertainSpace]
function_labels	Labels for objective functions TYPE: List[str]
n_initial_points	Number of initial random points for exploration TYPE: int DEFAULT: 10
n_optimization_iterations	Number of optimization iterations TYPE: int DEFAULT: 20
n_uncs	Number of uncertainty samples per design TYPE: int DEFAULT: 10
n_occ_rdm	Number of occupancy samples per uncertainty TYPE: int DEFAULT: 1
n_jobs	Number of parallel jobs TYPE: int DEFAULT: cpu_count() - 1
acquisition_function	Type of acquisition function ("qEHVI", "qNEHVI", etc.) TYPE: str DEFAULT: 'qEHVI'
reference_point	Reference point for hypervolume calculation TYPE: Optional[List[float]] DEFAULT: None
batch_size	Batch size for parallel evaluation TYPE: int DEFAULT: 1
raw_samples	Number of random samples for acquisition function optimization (higher = more robust but slower) TYPE: int DEFAULT: 512
num_restarts	Number of optimization restarts for acquisition function optimization TYPE: int DEFAULT: 10

RETURNS	DESCRIPTION
Tuple[DataFrame, DataFrame, DataFrame]	Tuple of (uncertain_design, experience_design, uncertain_draws)

compute_pareto_frontier

compute_pareto_frontier(objectives, minimize=None)

Compute the Pareto frontier from objective values.

PARAMETER	DESCRIPTION
objectives	Tensor of objective values (n_points, n_objectives) TYPE: Tensor
minimize	List indicating which objectives to minimize (True) or maximize (False) TYPE: List[bool] DEFAULT: None

RETURNS	DESCRIPTION
Tuple[Tensor, Tensor]	Tuple of (pareto_objectives, pareto_indices)

botorch_optimization_kernel

BoTorch-based multi-objective optimization for ORENI framework.

This module provides optimization capabilities using BoTorch for multi-objective optimization with discrete unordered variables, specifically designed for building renovation optimization under uncertainties.

DiscreteVariableEncoder

DiscreteVariableEncoder(decision_space)

Encoder for discrete unordered variables to work with BoTorch.

BoTorch requires continuous variables, so we encode discrete variables using one-hot encoding or integer encoding with appropriate bounds.

encode_design

encode_design(design_df)

Encode a design DataFrame to continuous tensor for BoTorch.

decode_design

decode_design(encoded_tensor, design_df)

Decode a continuous tensor back to discrete design DataFrame.

get_device_info

get_device_info()

Get information about the current PyTorch device configuration.

botorch_multi_objective_optimizer_kernel

botorch_multi_objective_optimizer_kernel(
    function,
    decision_space,
    uncertain_space,
    function_labels,
    n_initial_points=10,
    n_optimization_iterations=2,
    n_uncs=2,
    n_occ_rdm=1,
    n_jobs=cpu_count() - 1,
    acquisition_function="qEHVI",
    reference_point=None,
    batch_size=1,
    raw_samples=512,
    num_restarts=10,
    kernel_type="mixed",
    fallback_to_simple_kernel=True,
)

Multi-objective optimization using BoTorch with support for discrete unordered variables.

PARAMETER	DESCRIPTION
function	Function to optimize (should return list of objective values) TYPE: Callable
decision_space	Decision space definition TYPE: DecisionSpace
uncertain_space	Uncertain space definition (optional) TYPE: Optional[UncertainSpace]
function_labels	Labels for objective functions TYPE: List[str]
n_initial_points	Number of initial random points for exploration TYPE: int DEFAULT: 10
n_optimization_iterations	Number of optimization iterations TYPE: int DEFAULT: 2
n_uncs	Number of uncertainty samples per design TYPE: int DEFAULT: 2
n_occ_rdm	Number of occupancy samples per uncertainty TYPE: int DEFAULT: 1
n_jobs	Number of parallel jobs TYPE: int DEFAULT: cpu_count() - 1
acquisition_function	Type of acquisition function ("qEHVI", "qNEHVI", etc.) TYPE: str DEFAULT: 'qEHVI'
reference_point	Reference point for hypervolume calculation TYPE: Optional[List[float]] DEFAULT: None
batch_size	Batch size for parallel evaluation TYPE: int DEFAULT: 1
raw_samples	Number of random samples for acquisition function optimization (higher = more robust but slower) TYPE: int DEFAULT: 512
num_restarts	Number of optimization restarts for acquisition function optimization TYPE: int DEFAULT: 10
kernel_type	Type of kernel to use ("mixed", "matern", "rbf", "categorical") TYPE: str DEFAULT: 'mixed'
fallback_to_simple_kernel	Whether to fallback to simple RBF kernel on numerical issues TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
Tuple[DataFrame, DataFrame, DataFrame]	Tuple of (uncertain_design, experience_design, uncertain_draws)

random_optimization

set_x_batch

set_x_batch(decision_space, n_iters=1)

Generates a DataFrame of experience designs based on the decision space and iterations.

Parameters:

decision_space (DecisionSpace): A decision space object containing column definitions and search spaces. n_iters (int, optional): Number of iterations (rows) to generate, default is 1.

Returns:

pd.DataFrame A DataFrame where each column corresponds to a parameter in the decision space, and each row is a sampled set of parameter values.

set_u_batch

set_u_batch(uncertain_space, n_uncs, n_occ_rdm=1)

Generates a DataFrame (with a pandas MultiIndex for columns) from the uncertainty definitions stored in an UncertainSpace instance. For each uncertainty, the first level of the column index is the uncertainty name and the second level is the alias name as defined in the uncertain space.

For each alias, random samples are drawn according to the sampling law and bounds specified in the uncertain space (under the "Space" key). This method supports both continuous (normal/uniform) and discrete sampling.

PARAMETER	DESCRIPTION
uncertain_space	An instance of your UncertainSpace class. TYPE: UncertainSpace
n_uncs	The number of iterations (rows) to generate. TYPE: int
n_occ_rdm	The number of iterations (rows) linked to SeedValue of FMU NoMASS to generate. TYPE: int DEFAULT: 1

RETURNS	DESCRIPTION
DataFrame	pd.DataFrame: A DataFrame with MultiIndex columns and n_iters rows.

oreni.models.energyplus

oreni.models.energyplus

oreni.models.energyplus

EnergyPlusModel

Class and functions for accessing EnergyPlus Python API

EnergyPlusModel

Bases: EnergyPlusModel

EnergyPlus Model object

ATTRIBUTE	DESCRIPTION
walls_window	list of walls with windows
floors	list of floors
lighting_zone	list of lighting zones
zones	list of zones

window_walls property

window_walls

Get list of walls with windows.

floors property

floors

Get all of the floor names.

add_lighting

add_lighting(zone, lighting_level, replace=False)

Add lighting object to EnergyPlusModel's epjs dictionary.

PARAMETER	DESCRIPTION
zone	Zone name to add lighting to. TYPE: str
lighting_level	Lighting level in Watts. TYPE: float
replace	If True, replace existing lighting object in zone. TYPE: bool DEFAULT: False

RAISES	DESCRIPTION
ValueError	If zone not found in model.
ValueError	If lighting already exists in zone and replace is False.

Examples:

>>> model.add_lighting("Zone1", 10)

add_output

add_output(
    output_type, output_name, reporting_frequency="Timestep"
)

Add an output variable or meter to the epjs dictionary.

PARAMETER	DESCRIPTION
output_type	Type of the output. "variable" or "meter". TYPE: str
output_name	Name of the output variable or meter. TYPE: str
reporting_frequency	Reporting frequency of the output variable or meter. TYPE: str DEFAULT: 'Timestep'

RAISES	DESCRIPTION
ValueError	If output_type is not "variable" or "meter".

Examples:

>>> model.add_output("Zone Mean Air Temperature", "variable")
>>> model.add_output("Cooling:Electricity", "meter")

load_idf

load_idf(fpath)

Load IDF file as JSON object.

Use EnergyPlus --convert-only option to convert IDF file to epJSON file.

PARAMETER	DESCRIPTION
fpath	Path to IDF file. TYPE: Union[str, Path]

RETURNS	DESCRIPTION
dict	JSON object.

RAISES	DESCRIPTION
ValueError	If file is not an IDF file.
FileNotFoundError	If IDF file not found.
FileNotFoundError	If converted epJSON file not found.

Examples:

>>> json_data = load_idf(Path("model.idf"))

EnergyPlusSetup

Class and functions for accessing EnergyPlus Python API

EnergyPlusResult

EnergyPlusResult()

EnergyPlusSetup

EnergyPlusSetup(epmodel, weather_file=None)

EnergyPlus Simulation Setup.

ATTRIBUTE	DESCRIPTION
api	EnergyPlusAPI object
epw	Weather file path
actuator_handles	Actuator Handles
variable_handles	Variable handles
construction_handles	Construction Handles
actuators	List of actuators available
model	EnergyPlusModel object
state	EnergyPlusState object
handles	Handles object

PARAMETER	DESCRIPTION
epmodel	EnergyPlusModel object TYPE: EnergyPlusModel
weather_file	Weather file path. (default: None) TYPE: Optional[str] DEFAULT: None

Examples:

>>> epsetup = EnergyPlusSetup(epmodel, weather_file="USA_CA_Oakland.Intl.AP.724930_TMY3.epw")

actuate

actuate(component_type, name, key, value)

Set or update the operating value of an actuator in the EnergyPlus model.

If actuator has not been requested previously, it will be requested. Set the actuator value to the value specified.

PARAMETER	DESCRIPTION
component_type	The actuator category, e.g. "Weather Data" TYPE: str
name	The name of the actuator to retrieve, e.g. "Outdoor Dew Point" TYPE: str
key	The instance of the variable to retrieve, e.g. "Environment" TYPE: str
value	The value to set the actuator to TYPE: float

RAISES	DESCRIPTION
ValueError	If the actuator is not found

Examples:

>>> epsetup.actuate("Weather Data", "Outdoor Dew Point", "Environment", 10)

actuate_cooling_setpoint

actuate_cooling_setpoint(zone, value)

Set cooling setpoint for a zone.

PARAMETER	DESCRIPTION
zone	The name of the zone to set the cooling setpoint for. TYPE: str
value	The value to set the cooling setpoint to. TYPE: float

Examples:

>>> epsetup.actuate_cooling_setpoint("zone1", 24)

actuate_heating_setpoint

actuate_heating_setpoint(zone, value)

Set heating setpoint for a zone.

PARAMETER	DESCRIPTION
zone	The name of the zone to set the heating setpoint for. TYPE: str
value	The value to set the heating setpoint to. TYPE: float

Example

epsetup.actuate_cooling_setpoint("zone1", 20)

actuate_lighting_power

actuate_lighting_power(light, value)

Set lighting power for a zone.

PARAMETER	DESCRIPTION
light	The name of the lighting object to set the lighting power for. TYPE: str
value	The value to set the lighting power to. TYPE: float

Examples:

>>> epsetup.actuate_lighting_power("zone1", 1000)

actuate_cfs_state

actuate_cfs_state(window, cfs_state)

Set construction state for a surface.

PARAMETER	DESCRIPTION
window	The name of the surface to set the cfs state for. TYPE: str
cfs_state	The name of the complex fenestration system (CFS) state to set the surface to. TYPE: str

Examples:

>>> epsetup.actuate_construction_state("window1", "cfs1")

get_variable_value

get_variable_value(name, key)

Get the value of a variable in the EnergyPlus model during runtime. The variable must be requested before it can be retrieved. If this method is called in a callback function, the variable will be requested automatically. So avoid having other methods called get_variable_value in the callback function.

PARAMETER	DESCRIPTION
name	The name of the variable to retrieve, e.g. "Outdoor Dew Point" TYPE: str
key	The instance of the variable to retrieve, e.g. "Environment" TYPE: str

RETURNS	DESCRIPTION
float	The value of the variable

RAISES	DESCRIPTION
KeyError	If the key is not found
ValueError	If the variable is not found

Examples:

>>> epsetup.get_variable_value("Outdoor Dew Point", "Environment")

get_cfs_state

get_cfs_state(window)

Return the current complex fenestration state with input window name

PARAMETER	DESCRIPTION
window	name of the window TYPE: str

RETURNS	DESCRIPTION
str	name of the cfs state

request_variable

request_variable(name, key)

Request a variable from the EnergyPlus model for access during runtime.

PARAMETER	DESCRIPTION
name	The name of the variable to retrieve, e.g. "Outdoor Dew Point" TYPE: str
key	The instance of the variable to retrieve, e.g. "Environment" TYPE: str

RETURNS	DESCRIPTION
None	None

Examples:

>>> epsetup.request_variable("Outdoor Dew Point", "Environment")

get_datetime

get_datetime()

Get the current date and time from EnergyPlus Run time datatime format with iso_8601_format = yes. hour 0-23, minute 10 - 60 v23.2.0

RETURNS	DESCRIPTION
datetime	datetime object

run

run(
    idf_run="",
    output_directory="./",
    output_prefix="eplus",
    output_suffix="L",
    verbose=False,
    annual=False,
    design_day=False,
)

Run EnergyPlus simulation.

PARAMETER	DESCRIPTION
output_directory	Output directory path. (default: current directory) TYPE: Optional[str] DEFAULT: './'
output_prefix	Prefix for output files. (default: eplus) TYPE: Optional[str] DEFAULT: 'eplus'
output_suffix	Suffix style for output files. (default: L) L: Legacy (e.g., eplustbl.csv) C: Capital (e.g., eplusTable.csv) D: Dash (e.g., eplus-table.csv) TYPE: Optional[str] DEFAULT: 'L'
verbose	If True, do not logging.info EnergyPlus output to console. (default: False) TYPE: bool DEFAULT: False
annual	If True, force run annual simulation. (default: False) TYPE: bool DEFAULT: False
design_day	If True, force run design-day-only simulation. (default: False) TYPE: bool DEFAULT: False

Examples:

>>> epsetup.run(output_prefix="test1", verbose=True)

set_callback

set_callback(method_name, func)

Set callback function for EnergyPlus runtime API.

PARAMETER	DESCRIPTION
method_name	Name of the method to set callback for. TYPE: str
func	Callback function. TYPE: Callable

RAISES	DESCRIPTION
AttributeError	If method_name is not found in EnergyPlus runtime API.

Examples:

>>> epsetup.set_callback("callback_begin_system_timestep_before_predictor", func)

get_direct_normal_irradiance

get_direct_normal_irradiance()

Get direct normal irradiance.

RETURNS	DESCRIPTION
float	Direct normal irradiance in W/m2.

Examples:

>>> epsetup.get_direct_normal_irradiance()

get_diffuse_horizontal_irradiance

get_diffuse_horizontal_irradiance()

Get diffuse horizontal irradiance.

RETURNS	DESCRIPTION
float	Diffuse horizontal irradiance in W/m2.

Example

epsetup.get_diffuse_horizontal_irradiance()

ep_datetime_parser

ep_datetime_parser(inp)

Parse date and time from EnergyPlus output.

PARAMETER	DESCRIPTION
inp	Date and time string from EnergyPlus output. TYPE: str

load_idf

load_idf(fpath)

Load IDF file as JSON object.

Use EnergyPlus --convert-only option to convert IDF file to epJSON file.

PARAMETER	DESCRIPTION
fpath	Path to IDF file. TYPE: Union[str, Path]

RETURNS	DESCRIPTION
dict	JSON object.

RAISES	DESCRIPTION
ValueError	If file is not an IDF file.
FileNotFoundError	If IDF file not found.
FileNotFoundError	If converted epJSON file not found.

Examples:

>>> json_data = load_idf(Path("model.idf"))

load_energyplus_model

load_energyplus_model(fpath)

Load EnergyPlus model from JSON file.

PARAMETER	DESCRIPTION
fpath	Path to JSON file. TYPE: Union[str, Path]

RETURNS	DESCRIPTION
EnergyPlusModel	EnergyPlusModel object.

RAISES	DESCRIPTION
ValueError	If file is not an IDF or epJSON file.

Examples:

>>> model = load_energyplus_model("model.json")

utils

try_import_energyplus_api

try_import_energyplus_api(do_import=True)

Try to import pyenergyplus, and add the E+ installation to sys.path if it's not found.

EnergyPlus home can be specified with the ENERGYPLUS_HOME environment variable, in that case path is used as is. If ENERGYPLUS_VERSION is specified, /usr/local/EnergyPlus-{ENERGYPLUS_VERSION} is used (Linux only). Otherwise, the latest E+ installation in /usr/local/EnergyPlus-* is used (Linux only).

override

override(cls)

Annotation for documenting method overrides.

:param cls: the superclass that provides the overridden method. If this cls does not actually have the method, an error is raised.