epinterface 1.0.0__py3-none-any.whl

epinterface/__init__.py

@@ -0,0 +1 @@
+"""A library for interfacing with EnergyPlus."""

epinterface/actions.py

@@ -0,0 +1,382 @@
+"""Actions to modify a library object."""
+
+from abc import abstractmethod
+from collections.abc import Callable
+from functools import reduce
+from typing import Any, Generic, Literal, TypeVar, cast
+
+from pydantic import BaseModel, Field, model_validator
+
+from epinterface.climate_studio.builder import Model
+from epinterface.climate_studio.interface import ClimateStudioLibraryV2
+
+LibT = TypeVar("LibT", dict[str, Any], ClimateStudioLibraryV2, Model, BaseModel)
+
+# TODO: Major!
+# allow operating on an object in conjunction with operating on a library
+# TODO: allow callbacks in path reduction, e.g. to compute a value like "layer with most insulation"
+
+
+def get_dict_val_or_attr(obj, key):
+    """Retrieve a value from a dictionary or list, or an attribute from an object.
+
+    Args:
+        obj (Union[dict, list, Any]): The object from which to retrieve the value or attribute.
+        key (Any): The key or attribute name to retrieve.
+
+    Returns:
+        val (Any): The value associated with the key if `obj` is a dictionary or list,
+             or the attribute value if `obj` is an object.
+    """
+    if isinstance(obj, dict | list):
+        return obj[key]
+    else:
+        return getattr(obj, key)
+
+
+def set_dict_val_or_attr(obj, key, val):
+    """Sets a value in a dictionary or list, or sets an attribute on an object.
+
+    If the provided object is a dictionary or list, the function sets the value
+    at the specified key or index. If the object is not a dictionary or list,
+    the function sets an attribute on the object with the specified key and value.
+
+    Args:
+        obj (Union[dict, list, object]): The object to modify.
+        key (Union[str, int]): The key or attribute name to set.
+        val (Any): The value to set.
+
+    Raises:
+        TypeError: If the object is a list and the key is not an integer.
+    """
+    if isinstance(obj, dict | list):
+        obj[key] = val
+    else:
+        setattr(obj, key, val)
+
+
+T = TypeVar("T")
+
+
+class ParameterPath(BaseModel, Generic[T]):
+    """Pathing to find a parameter in a library/object.
+
+    ParameterPath is a generic class that represents a path consisting of strings, integers,
+    or other ParameterPath instances. It provides methods to resolve the path and retrieve
+    values from a given library.
+    """
+
+    path: list["str | int | ParameterPath"] = Field(
+        ..., description="The path to the parameter to select."
+    )
+
+    def resolved_path(self, lib: LibT):
+        """Resolve the path to the parameter in the library.
+
+        Args:
+            lib (LibT): The library to search for the parameter.
+
+        Returns:
+            path (list[Any]): The resolved path to the parameter in the library.
+        """
+        return [
+            p if isinstance(p, str | int) else p.get_lib_val(lib) for p in self.path
+        ]
+
+    def get_lib_val(self, lib: LibT) -> T:
+        """Retrieves a value from a nested dictionary or object attribute path.
+
+        Args:
+            lib (LibT): The library object from which to retrieve the value.
+
+        Returns:
+            val (T): The value retrieved from the nested dictionary or object attribute path.
+        """
+        return cast(T, reduce(get_dict_val_or_attr, self.resolved_path(lib), lib))
+
+    @property
+    def parent_path(self):
+        """Returns the parent path of the current path.
+
+        Returns:
+            parent_path (ParameterPath): The parent path of the current path.
+        """
+        # TODO: how can we type-narrow the generic parameterpath here?
+        # get the parent using the similar reduction technique as before
+        return ParameterPath[Any](path=self.path[:-1])
+
+
+Priority = Literal["low", "high"]
+
+
+class Action(BaseModel, Generic[T]):
+    """An action to modify a library object.
+
+    This base class should be inherited by classes that represent actions to modify
+    a library object. It provides an abstract method `run` that should be implemented
+    by subclasses to perform the modification.
+    """
+
+    target: ParameterPath[T] = Field(
+        ..., description="The path to the parameter to modify."
+    )
+    priority: Priority | None = Field(
+        default=None,
+        description="The priority of the action (low will execute if the new value is less than the old value).",
+    )
+
+    def run(self, lib: LibT) -> LibT:
+        """Run the action to modify the library object.
+
+        Args:
+            lib (LibT): The library object to modify.
+
+        Returns:
+            lib (LibT): The modified library object.
+        """
+        new_val = self.new_val(lib)
+        original_val = self.get_original_val(lib)
+        if self.check_priority(original_val, new_val):
+            original_obj = self.get_original_obj(lib)
+            key = self.original_key
+            set_dict_val_or_attr(original_obj, key, new_val)
+        return lib
+
+    def check_priority(self, original: T, new: T) -> bool:
+        """Check if the new value should be applied based on the action priority.
+
+        Args:
+            original (T): The original value in the library object.
+            new (T): The new value to apply.
+
+        Returns:
+            apply (bool): True if the new value should be applied, False otherwise.
+        """
+        if self.priority is None:
+            return True
+
+        if not isinstance(original, int | float) or not isinstance(new, int | float):
+            msg = "priority comparison only supported for numerical values."
+            raise TypeError(msg)
+
+        if self.priority == "low":
+            return original > new
+
+        elif self.priority == "high":
+            return original < new
+        else:
+            msg = f"Invalid priority value: {self.priority}"
+            raise ValueError(msg)
+
+    def get_original_val(self, lib: LibT) -> T:
+        """Retrieve the original value from the library object.
+
+        Args:
+            lib (LibT): The library object from which to retrieve the original value.
+
+        Returns:
+            val (T): The original value from the library object.
+        """
+        return self.target.get_lib_val(lib)
+
+    @property
+    def original_key(self) -> str | int | ParameterPath:
+        """Retrieve the key of the original value in the library object.
+
+        Returns:
+            key (str | int | ParameterPath): The key of the original value in the library object.
+        """
+        # TODO: handle cases where final key is a ParameterPath!!
+        return self.target.path[-1]
+
+    def get_original_obj(self, lib: LibT):
+        """Retrieve the object containing the original value in the library object.
+
+        Args:
+            lib (LibT): The library object from which to retrieve the original object.
+
+        Returns:
+            obj (Any): The object containing the original value in the library object.
+        """
+        return self.target.parent_path.get_lib_val(lib)
+
+    @abstractmethod
+    def new_val(self, lib: LibT) -> T:
+        """Calculate the new value to apply to the library object.
+
+        NB: This method should be implemented by subclasses to calculate the new value.
+
+        Args:
+            lib (LibT): The library object on which to apply the new value.
+
+        Returns:
+            val (T): The new value to apply to the library object.
+        """
+        pass
+
+
+class ReplaceWithExisting(Action[T]):
+    """Replace a value in a library object with a value from another location in the library."""
+
+    source: ParameterPath[T]
+
+    def new_val(self, lib: LibT) -> T:
+        """Retrieve the value from the source path to replace the target value.
+
+        Args:
+            lib (LibT): The library object from which to retrieve the new value.
+
+        Returns:
+            val (T): The new value to replace the target value.
+        """
+        return self.source.get_lib_val(lib)
+
+
+class ReplaceWithVal(Action[T]):
+    """Replace a value in a library object with a new value."""
+
+    val: T
+
+    def new_val(self, lib: LibT) -> T:
+        """Returns the current value of the instance to use for updating.
+
+        Args:
+            lib (LibT): A library instance of type LibT.
+
+        Returns:
+            val (T): The current value of the instance.
+        """
+        return self.val
+
+
+Numeric = TypeVar("Numeric", int, float)
+Operation = Literal["+", "*"]
+
+
+class DeltaVal(Action[Numeric]):
+    """Add a value to a parameter in a library object."""
+
+    delta: Numeric = Field(
+        ..., description="The value to modify to the original value."
+    )
+    op: Operation = Field(
+        ..., description="The operation to perform on the original value."
+    )
+
+    def new_val(self, lib: LibT) -> Numeric:
+        """Calculate a new value by combining the original value from the given library with a delta.
+
+        Args:
+            lib (LibT): The library from which to retrieve the original value.
+
+        Returns:
+            new_val (Numeric): The new value obtained by combining the original value with the delta.
+        """
+        original_val = self.get_original_val(lib)
+
+        return self.combine(original_val, self.delta)
+
+    @property
+    def combine(self) -> Callable[[Numeric, Numeric], Numeric]:
+        """Combines two numeric values based on the specified operation.
+
+        Supported operations:
+            - "+": Addition
+            - "*": Multiplication
+
+        Returns:
+            fn (Callable[[Numeric, Numeric], Numeric]): A function that takes two numeric arguments and returns a numeric result.
+
+        Raises:
+            ValueError: If the operation specified by `self.op` is not supported.
+
+        """
+        if self.op == "+":
+            return lambda x, y: x + y
+        elif self.op == "*":
+            return lambda x, y: x * y
+        else:
+            msg = f"Invalid operation: {self.op}"
+            raise ValueError(msg)
+
+
+class ActionSequence(BaseModel):
+    """A sequence of actions to perform on a library object."""
+
+    name: str = Field(..., description="The name of the action sequence.")
+    actions: list[
+        "DeltaVal | ReplaceWithExisting | ReplaceWithVal | ActionSequence"
+    ] = Field(  # TODO: should we allow nested actionsequences?
+        ..., description="A sequence of actions to perform on a library object."
+    )
+
+    def run(self, lib: LibT) -> LibT:
+        """Run the sequence of actions on the library object.
+
+        Args:
+            lib (LibT): The library object to modify.
+
+        Returns:
+            lib (LibT): The modified library object.
+        """
+        for action in self.actions:
+            lib = action.run(lib)
+        return lib
+
+
+class ActionLibrary(BaseModel):
+    """A library of action sequences, e.g. to represent deep and shallow retrofits for different types of buildings."""
+
+    name: str = Field(..., description="The name of the action library.")
+    actions: list[ActionSequence] = Field(
+        ..., description="A list of action sequences to perform on a library object."
+    )
+
+    @model_validator(mode="after")
+    def check_action_names_are_unique(self):
+        """Check that the names of the action sequences in the action library are unique.
+
+        Raises:
+            ValueError: If the names of the action sequences are not unique.
+        """
+        action_names = self.action_names
+        if len(action_names) != len(set(action_names)):
+            msg = f"Action names must be unique: {', '.join(action_names)}"
+            raise ValueError(msg)
+        return self
+
+    @property
+    def action_names(self):
+        """Return the names of the action sequences in the action library.
+
+        Returns:
+            action_names (list[str]): The names of the action sequences in the action
+        """
+        return [action.name for action in self.actions]
+
+    def get(self, name: str) -> ActionSequence:
+        """Retrieve an action sequence by name.
+
+        Args:
+            name (str): The name of the action sequence to retrieve.
+
+        Returns:
+            action (ActionSequence): The action sequence with the specified name.
+
+        Raises:
+            KeyError: If the action sequence with the specified name is not found in the action library.
+        """
+        if name in self.action_names:
+            return self.actions[self.action_names.index(name)]
+        else:
+            msg = f"Action sequence not found: {name}\nAvailable action sequences: {', '.join(self.action_names)}"
+            raise KeyError(msg)
+
+
+ParameterPath.model_rebuild()
+Action.model_rebuild()
+ReplaceWithExisting.model_rebuild()
+ReplaceWithVal.model_rebuild()
+DeltaVal.model_rebuild()
+ActionSequence.model_rebuild()
+ActionLibrary.model_rebuild()

epinterface/builder.py

@@ -0,0 +1,310 @@
+"""A simple model for automatically constructing a shoebox building energy model."""
+
+import logging
+import shutil
+from pathlib import Path
+
+import pandas as pd
+from archetypal.idfclass import IDF
+from archetypal.schedule import Schedule
+from archetypal.schedule import ScheduleTypeLimits as AScheduleTypeLimits
+
+from epinterface.ddy_injector_bayes import DDYSizingSpec
+from epinterface.geometry import ShoeboxGeometry
+from epinterface.interface import (
+    Construction,
+    DefaultMaterialLibrary,
+    ElectricEquipment,
+    HVACTemplateThermostat,
+    HVACTemplateZoneIdealLoadsAirSystem,
+    Lights,
+    People,
+    RunPeriod,
+    SimpleGlazingMaterial,
+    SimulationControl,
+    Timestep,
+    ZoneInfiltrationDesignFlowRate,
+    ZoneList,
+)
+from epinterface.weather import BaseWeather
+
+logger = logging.getLogger(__name__)
+
+
+class SimpleResidentialModel(BaseWeather, extra="allow"):
+    """A simple model for automatically constructing a shoebox building energy model."""
+
+    EPD: float = 9.0
+    LPD: float = 4.0
+    WWR: float = 0.15
+    WindowU: float = 2.7
+    WindowSHGC: float = 0.763
+    HeatingSetpoint: float = 19
+    CoolingSetpoint: float = 24
+    PeopleDensity: float = 0.05
+    Infiltration: float = 0.1
+    timestep: int = 6
+
+    async def build(
+        self, output_dir: Path | str, weather_cache_dir: Path | str | None = None
+    ) -> IDF:
+        """Build the energy model.
+
+        Args:
+            output_dir (Path | str): The directory to save the IDF file.
+            weather_cache_dir (Path | str | None): The directory to cache the weather files.
+
+        Returns:
+            IDF: The constructed IDF model.
+        """
+        if isinstance(output_dir, str):
+            output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        material_lib = DefaultMaterialLibrary()
+        weather_cache_dir = Path(weather_cache_dir) if weather_cache_dir else output_dir
+        epw_path, ddy_path = await self.fetch_weather(weather_cache_dir)
+        schedules = pd.read_parquet(
+            Path(__file__).parent / "data" / "res_schedules.parquet"
+        )
+
+        shutil.copy(
+            Path(__file__).parent / "data" / "Minimal.idf",
+            output_dir / "Minimal.idf",
+        )
+        idf = IDF(
+            (output_dir / "Minimal.idf").as_posix(),
+            epw=(epw_path.as_posix()),
+            output_directory=output_dir.as_posix(),
+            prep_outputs=True,
+        )  # pyright: ignore [reportArgumentType]
+        ddy = IDF(
+            (ddy_path.as_posix()),
+            as_version="9.2.0",
+            file_version="9.2.0",
+            prep_outputs=False,
+        )
+        ddyspec = DDYSizingSpec(match=True)
+        ddyspec.inject_ddy(idf, ddy)
+
+        # Configure simulation
+        sim_control = SimulationControl(
+            Do_Zone_Sizing_Calculation="Yes",
+            Do_System_Sizing_Calculation="Yes",
+            Do_Plant_Sizing_Calculation="Yes",
+            Run_Simulation_for_Sizing_Periods="Yes",
+            Run_Simulation_for_Weather_File_Run_Periods="Yes",
+            Do_HVAC_Sizing_Simulation_for_Sizing_Periods="Yes",
+        )
+        sim_control.add(idf)
+
+        # Configure run period
+        run_period = RunPeriod(
+            Name="Year",
+            Use_Weather_File_Daylight_Saving_Period="No",
+            Use_Weather_File_Rain_Indicators="No",
+            Use_Weather_File_Snow_Indicators="No",
+            Use_Weather_File_Holidays_and_Special_Days="No",
+            Begin_Month=1,
+            Begin_Day_of_Month=1,
+            End_Month=12,
+            End_Day_of_Month=31,
+            Day_of_Week_for_Start_Day="Sunday",
+        )
+        run_period.add(idf)
+
+        # configure timestep
+        timestep = Timestep(
+            Number_of_Timesteps_per_Hour=self.timestep,
+        )
+        timestep.add(idf)
+
+        # create constant scheds
+        always_on_schedule = Schedule.constant_schedule(Name="Always_On", value=1)
+        always_off_schedule = Schedule.constant_schedule(Name="Always_Off", value=0)
+        year, *_ = always_on_schedule.to_year_week_day()
+        year.to_epbunch(idf)
+        year, *_ = always_off_schedule.to_year_week_day()
+        year.to_epbunch(idf)
+
+        always_on_schedule = Schedule.constant_schedule(Name="Always On", value=1)
+        always_off_schedule = Schedule.constant_schedule(Name="Always Off", value=0)
+        year, *_ = always_on_schedule.to_year_week_day()
+        year.to_epbunch(idf)
+        year, *_ = always_off_schedule.to_year_week_day()
+        year.to_epbunch(idf)
+
+        always_on_schedule = Schedule.constant_schedule(Name="On", value=1)
+        always_off_schedule = Schedule.constant_schedule(Name="Off", value=0)
+        year, *_ = always_on_schedule.to_year_week_day()
+        year.to_epbunch(idf)
+        year, *_ = always_off_schedule.to_year_week_day()
+        year.to_epbunch(idf)
+
+        # Handle Geometry
+        zone_dims = ShoeboxGeometry(
+            x=0,
+            y=0,
+            w=10,
+            d=10,
+            h=3,
+            num_stories=3,
+            roof_height=2.5,
+            basement=False,
+            wwr=0.15,
+            zoning="by_storey",
+        )
+        idf = zone_dims.add(idf)
+
+        window_construction = Construction(
+            name="Project External Window",
+            layers=[
+                SimpleGlazingMaterial(
+                    Name="DefaultGlazing",
+                    Solar_Heat_Gain_Coefficient=self.WindowSHGC,
+                    UFactor=self.WindowU,
+                    Visible_Transmittance=0.7,
+                )
+            ],
+        )
+        window_construction.add(idf)
+
+        # Handle Wall Constructions
+        wall_construction = Construction(
+            name="Project Wall",  # NB/TODO: this is the name set by geomeppy
+            layers=[
+                material_lib.stucco.as_layer(thickness=0.03),
+                material_lib.insulation.as_layer(thickness=0.15),
+                material_lib.gypsum.as_layer(thickness=0.02),
+            ],
+        )
+        wall_construction.add(idf)
+
+        # Handle Roof Constructions
+        # roof_construction = Construction(
+        #     name="Project Flat Roof",
+        #     layers=[
+        #         material_lib.stucco.as_layer(thickness=0.03),
+        #         material_lib.insulation.as_layer(thickness=0.15),
+        #         material_lib.gypsum.as_layer(thickness=0.02),
+        #     ],
+        # )
+        # roof_construction.add(idf)
+
+        # TODO: handle other constructions.
+
+        # Handle Zone List
+        zone_names = [
+            zone.Name
+            for zone in idf.idfobjects["ZONE"]
+            if "attic" not in zone.Name.lower()
+        ]
+        zone_list = ZoneList(Name="Conditioned_Zones", Names=zone_names)
+        zone_list.add(idf)
+
+        # Handle HVAC
+        thermostat = HVACTemplateThermostat(
+            Name="Thermostat",
+            Constant_Heating_Setpoint=self.HeatingSetpoint,
+            Constant_Cooling_Setpoint=self.CoolingSetpoint,
+        )
+        thermostat.add(idf)
+        for zone in idf.idfobjects["ZONE"]:
+            zone_name = zone.Name
+            if "attic" in zone_name.lower():
+                continue
+            hvac_template = HVACTemplateZoneIdealLoadsAirSystem(
+                Zone_Name=zone_name,
+                Template_Thermostat_Name=thermostat.Name,
+            )
+            idf = hvac_template.add(idf)
+
+        # Handle People
+        occ_sched, *_ = Schedule.from_values(
+            "Occupancy_sch",
+            Values=schedules.Occupancy.values.tolist(),
+            Type="fraction",
+        ).to_year_week_day()
+        any_number_lim = AScheduleTypeLimits(
+            Name="any number", LowerLimit=None, UpperLimit=None
+        )
+        any_number_lim.to_epbunch(idf)
+        acti_year, *_ = Schedule.constant_schedule(
+            value=117.28,  # pyright: ignore [reportArgumentType]
+            Name="Activity_Schedule",
+            Type="any number",
+        ).to_year_week_day()
+        occ_sched.to_epbunch(idf)
+        acti_year.to_epbunch(idf)
+        people = People(
+            Name="People",
+            Zone_or_ZoneList_Name=zone_list.Name,
+            Number_of_People_Schedule_Name=occ_sched.Name,
+            Activity_Level_Schedule_Name=acti_year.Name,
+            Number_of_People_Calculation_Method="People/Area",
+            People_per_Floor_Area=self.PeopleDensity,
+        )
+        people.add(idf)
+
+        # Handle Infiltration
+        infiltration = ZoneInfiltrationDesignFlowRate(
+            Name="Infiltration",
+            Zone_or_ZoneList_Name=zone_list.Name,
+            Schedule_Name=always_on_schedule.Name,
+            Design_Flow_Rate_Calculation_Method="AirChanges/Hour",
+            Flow_Rate_per_Exterior_Surface_Area=self.Infiltration,
+        )
+        infiltration.add(idf)
+
+        # Handle Equipment
+        equip_sched, *_ = Schedule.from_values(
+            "Equipment_sch",
+            Values=schedules.Equipment.values.tolist(),
+            Type="fraction",
+        ).to_year_week_day()
+        equip_sched.to_epbunch(idf)
+        equipment = ElectricEquipment(
+            Name="Equipment",
+            Zone_or_ZoneList_Name=zone_list.Name,
+            Schedule_Name=equip_sched.Name,
+            Design_Level_Calculation_Method="Watts/Area",
+            Watts_per_Zone_Floor_Area=self.EPD,
+        )
+        equipment.add(idf)
+
+        # Handle Lights
+        lights_sched, *_ = Schedule.from_values(
+            "Lights_sch",
+            Values=schedules.Lights.values.tolist(),
+            Type="fraction",
+        ).to_year_week_day()
+        lights_sched.to_epbunch(idf)
+        lights = Lights(
+            Name="Lights",
+            Zone_or_ZoneList_Name=zone_list.Name,
+            Schedule_Name=lights_sched.Name,
+            Design_Level_Calculation_Method="Watts/Area",
+            Watts_per_Zone_Floor_Area=self.LPD,
+        )
+        lights.add(idf)
+
+        # Handle Water
+        # TODO: energy only changes with flow rate because no heater is provided.
+        # water_flow_sch, *_ = Schedule.constant_schedule(Name="Water_Flow", value=0.1).to_year_week_day()
+        # water_flow_sch.to_epbunch(idf)
+        # target_temp_sch, *_ = Schedule.constant_schedule(Name="Target_Temperature", value=10, Type="Temperature").to_year_week_day()
+        # target_temp_sch.to_epbunch(idf)
+        # water = WaterUseEquipment(
+        #     Name="DHW",
+        #     Peak_Flow_Rate=0.0001,
+        #     Flow_Rate_Fraction_Schedule_Name=water_flow_sch.Name,
+        #     Hot_Water_Supply_Temperature_Schedule_Name=target_temp_sch.Name,
+        #     # Zone_Name=
+        #     # Latent_Fraction_Schedule_Name=
+        #     # Sensible_Fraction_Schedule_Name=
+        # )
+        # water.add(idf)
+
+        # TODO: should we be using a slab processor?
+
+        return idf