EnergyPlus Interface

This is a thin wrapper around Eppy for some opinionated control.

Interface for EnergyPlus IDF objects.

AirGapMaterial

Bases: BaseObj

AirGapMaterial object.

Source code in epinterface\interface.py

class AirGapMaterial(BaseObj, extra="ignore"):
    """AirGapMaterial object."""

    key: ClassVar[str] = "MATERIAL:AIRGAP"
    Name: str
    Thermal_Resistance: float

BaseMaterial

Bases: BaseModel

A base material object for storing material definitions.

Note that this is not an EnergyPlus object, but a base class for creating new material objects which can be turned into EP objects once assigned thicknesses.

Source code in epinterface\interface.py

class BaseMaterial(BaseModel, extra="ignore", populate_by_name=True):
    """A base material object for storing material definitions.

    Note that this is not an EnergyPlus object, but a base class for creating new
    material objects which can be turned into EP objects once assigned thicknesses.
    """

    Name: str
    Roughness: str
    Conductivity: float = Field(..., ge=0, validation_alias="Conductivity [W/m.K]")
    Density: float = Field(..., ge=0, validation_alias="Density [kg/m3]")
    Specific_Heat: float = Field(..., ge=0, validation_alias="SpecificHeat [J/kg.K]")
    Thermal_Absorptance: float | None = Field(
        default=None, validation_alias="ThermalAbsorptance [0-1]", ge=0, le=1
    )
    Solar_Absorptance: float | None = Field(
        default=None, validation_alias="SolarAbsorptance [0-1]", ge=0, le=1
    )
    Visible_Absorptance: float | None = Field(
        default=None, validation_alias="VisibleAbsorptance [0-1]", ge=0, le=1
    )

    def as_layer(self, thickness: float):
        """Create a new material object with a given thickness.

        Args:
            thickness (float): The thickness of the material.

        Returns:
            mat (Material): The new material object with the given thickness.
        """
        name = f"{self.Name}_{thickness}m"
        return Material(
            Name=name, Thickness=thickness, **self.model_dump(exclude={"Name"})
        )

as_layer(thickness)

Create a new material object with a given thickness.

Parameters:

Name	Type	Description	Default
thickness	float	The thickness of the material.	required

Returns:

Name	Type	Description
mat	Material	The new material object with the given thickness.

Source code in epinterface\interface.py

def as_layer(self, thickness: float):
    """Create a new material object with a given thickness.

    Args:
        thickness (float): The thickness of the material.

    Returns:
        mat (Material): The new material object with the given thickness.
    """
    name = f"{self.Name}_{thickness}m"
    return Material(
        Name=name, Thickness=thickness, **self.model_dump(exclude={"Name"})
    )

BaseObj

Bases: BaseModel

Base class for EnergyPlus IDF objects.

The class should be inherited by all EnergyPlus IDF objects. It provides methods to add and extract objects from an IDF object.

Source code in epinterface\interface.py

class BaseObj(BaseModel):
    """Base class for EnergyPlus IDF objects.

    The class should be inherited by all EnergyPlus IDF objects. It provides
    methods to add and extract objects from an IDF object.
    """

    key: ClassVar[str]

    def add(self, idf: IDF):
        """Add the object to the IDF object.

        Args:
            idf (IDF): The IDF object to add the object to.

        Returns:
            idf (IDF): The updated IDF object.
        """
        idf.newidfobject(self.key, **self.model_dump())
        return idf

    @classmethod
    def extract(cls, idf: IDF):
        """Extract objects from an IDF object.

        Args:
            idf (IDF): The IDF object to extract objects from.

        Returns:
            objs (list[BaseObj]): A list of objects extracted from the IDF object.
        """
        objs = idf.idfobjects[cls.key]
        try:
            return [cls(**obj) for obj in objs]
        except ValidationError:
            return [cls(**obj.to_dict()) for obj in objs]

add(idf)

Add the object to the IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to add the object to.	required

Returns:

Name	Type	Description
idf	IDF	The updated IDF object.

Source code in epinterface\interface.py

def add(self, idf: IDF):
    """Add the object to the IDF object.

    Args:
        idf (IDF): The IDF object to add the object to.

    Returns:
        idf (IDF): The updated IDF object.
    """
    idf.newidfobject(self.key, **self.model_dump())
    return idf

extract(idf) classmethod

Extract objects from an IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to extract objects from.	required

Returns:

Name	Type	Description
objs	list[BaseObj]	A list of objects extracted from the IDF object.

Source code in epinterface\interface.py

@classmethod
def extract(cls, idf: IDF):
    """Extract objects from an IDF object.

    Args:
        idf (IDF): The IDF object to extract objects from.

    Returns:
        objs (list[BaseObj]): A list of objects extracted from the IDF object.
    """
    objs = idf.idfobjects[cls.key]
    try:
        return [cls(**obj) for obj in objs]
    except ValidationError:
        return [cls(**obj.to_dict()) for obj in objs]

Construction

Bases: BaseObj

Construction object.

Source code in epinterface\interface.py

class Construction(BaseObj, extra="ignore"):
    """Construction object."""

    key: ClassVar[str] = "CONSTRUCTION"
    name: str
    layers: Sequence[Material | AirGapMaterial | SimpleGlazingMaterial | NoMassMaterial]

    @property
    def r_value(self):
        """Return the R-value of the construction.

        Computed using the formula: R = sum(thickness_i / conductivity_i)

        Returns:
            r (float): The R-value of the construction (units: m^2.K/W).
        """
        return (
            sum([layer.r for layer in self.layers if isinstance(layer, Material)])
            + sum([
                layer.Thermal_Resistance
                for layer in self.layers
                if isinstance(layer, AirGapMaterial)
            ])
            + sum([
                layer.Thermal_Resistance
                for layer in self.layers
                if isinstance(layer, NoMassMaterial)
            ])
            + sum([
                1 / layer.UFactor
                for layer in self.layers
                if isinstance(layer, SimpleGlazingMaterial)
            ])
        )

    @classmethod
    def extract(cls, idf: IDF):
        """Extract objects from an IDF object.

        Args:
            idf (IDF): The IDF object to extract objects from.

        Returns:
            constructions (list[Construction]): A list of objects extracted from the IDF object.
        """
        constructions = idf.idfobjects["CONSTRUCTION"]
        res: list[Construction] = []
        for construction in constructions:
            const_dict = construction.to_dict()
            layer_names = [
                const_dict[key]
                for key in [
                    "Outside_Layer",
                    "Layer_2",
                    "Layer_3",
                    "Layer_4",
                    "Layer_5",
                    "Layer_6",
                    "Layer_7",
                    "Layer_8",
                    "Layer_9",
                    "Layer_10",
                ]
                if key in const_dict
            ]

            layer_names = [n for n in layer_names if n != "" and n]
            material_defs = [
                idf.getobject("MATERIAL", name) for name in layer_names
            ]  # TODO: handle air layers
            airgap_material_defs = [
                idf.getobject("MATERIAL:AIRGAP", name) for name in layer_names
            ]
            simple_glazing_material_defs = [
                idf.getobject("WINDOWMATERIAL:SIMPLEGLAZINGSYSTEM", name)
                for name in layer_names
            ]
            no_mass_material_defs = [
                idf.getobject("MATERIAL:NOMASS", name) for name in layer_names
            ]
            materials = [Material(**m.to_dict()) if m else None for m in material_defs]
            airgap_materials = [
                AirGapMaterial(**m.to_dict()) if m else None
                for m in airgap_material_defs
            ]
            simple_glazing_materials = [
                SimpleGlazingMaterial(**m.to_dict()) if m else None
                for m in simple_glazing_material_defs
            ]
            nomass_materials = [
                NoMassMaterial(**m.to_dict()) if m else None
                for m in no_mass_material_defs
            ]

            layers = [
                m if m else (n if n else (o if o else p))
                for m, n, o, p in zip(
                    materials,
                    airgap_materials,
                    simple_glazing_materials,
                    nomass_materials,
                    strict=False,
                )
            ]

            valid_layers = [layer for layer in layers if layer is not None]
            if len(valid_layers) != len(layers):
                logger.warning(
                    f"Construction {construction.Name} has missing layers. "
                    f"Expected {len(layers)} layers, got {len(valid_layers)}."
                    f"Skipping construction extraction."
                )
                continue
            construction = cls(name=construction.Name, layers=valid_layers)
            res.append(construction)
        return res

    def add(self, idf: IDF):
        """Add the object to the IDF object.

        Args:
            idf (IDF): The IDF object to add the object to.

        Returns:
            idf (IDF): The updated IDF object.
        """
        for layer in self.layers:
            idf = layer.add(idf)
        idf.newidfobject(
            self.key,
            Name=self.name,
            **{
                (f"Layer_{i + 1}" if i != 0 else "Outside_Layer"): layer.Name
                for i, layer in enumerate(self.layers)
            },
        )
        return idf

r_value property

Return the R-value of the construction.

Computed using the formula: R = sum(thickness_i / conductivity_i)

Returns:

Name	Type	Description
r	float	The R-value of the construction (units: m^2.K/W).

add(idf)

Add the object to the IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to add the object to.	required

Returns:

Name	Type	Description
idf	IDF	The updated IDF object.

Source code in epinterface\interface.py

def add(self, idf: IDF):
    """Add the object to the IDF object.

    Args:
        idf (IDF): The IDF object to add the object to.

    Returns:
        idf (IDF): The updated IDF object.
    """
    for layer in self.layers:
        idf = layer.add(idf)
    idf.newidfobject(
        self.key,
        Name=self.name,
        **{
            (f"Layer_{i + 1}" if i != 0 else "Outside_Layer"): layer.Name
            for i, layer in enumerate(self.layers)
        },
    )
    return idf

extract(idf) classmethod

Extract objects from an IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to extract objects from.	required

Returns:

Name	Type	Description
constructions	list[Construction]	A list of objects extracted from the IDF object.

Source code in epinterface\interface.py

@classmethod
def extract(cls, idf: IDF):
    """Extract objects from an IDF object.

    Args:
        idf (IDF): The IDF object to extract objects from.

    Returns:
        constructions (list[Construction]): A list of objects extracted from the IDF object.
    """
    constructions = idf.idfobjects["CONSTRUCTION"]
    res: list[Construction] = []
    for construction in constructions:
        const_dict = construction.to_dict()
        layer_names = [
            const_dict[key]
            for key in [
                "Outside_Layer",
                "Layer_2",
                "Layer_3",
                "Layer_4",
                "Layer_5",
                "Layer_6",
                "Layer_7",
                "Layer_8",
                "Layer_9",
                "Layer_10",
            ]
            if key in const_dict
        ]

        layer_names = [n for n in layer_names if n != "" and n]
        material_defs = [
            idf.getobject("MATERIAL", name) for name in layer_names
        ]  # TODO: handle air layers
        airgap_material_defs = [
            idf.getobject("MATERIAL:AIRGAP", name) for name in layer_names
        ]
        simple_glazing_material_defs = [
            idf.getobject("WINDOWMATERIAL:SIMPLEGLAZINGSYSTEM", name)
            for name in layer_names
        ]
        no_mass_material_defs = [
            idf.getobject("MATERIAL:NOMASS", name) for name in layer_names
        ]
        materials = [Material(**m.to_dict()) if m else None for m in material_defs]
        airgap_materials = [
            AirGapMaterial(**m.to_dict()) if m else None
            for m in airgap_material_defs
        ]
        simple_glazing_materials = [
            SimpleGlazingMaterial(**m.to_dict()) if m else None
            for m in simple_glazing_material_defs
        ]
        nomass_materials = [
            NoMassMaterial(**m.to_dict()) if m else None
            for m in no_mass_material_defs
        ]

        layers = [
            m if m else (n if n else (o if o else p))
            for m, n, o, p in zip(
                materials,
                airgap_materials,
                simple_glazing_materials,
                nomass_materials,
                strict=False,
            )
        ]

        valid_layers = [layer for layer in layers if layer is not None]
        if len(valid_layers) != len(layers):
            logger.warning(
                f"Construction {construction.Name} has missing layers. "
                f"Expected {len(layers)} layers, got {len(valid_layers)}."
                f"Skipping construction extraction."
            )
            continue
        construction = cls(name=construction.Name, layers=valid_layers)
        res.append(construction)
    return res

DefaultMaterialLibrary

Bases: BaseModel

Default material library for storing some common material defs.

Source code in epinterface\interface.py

class DefaultMaterialLibrary(BaseModel):
    """Default material library for storing some common material defs."""

    wood: BaseMaterial = wood
    gypsum: BaseMaterial = gypsum
    drywall: BaseMaterial = drywall
    osb: BaseMaterial = osb
    concrete: BaseMaterial = concrete
    insulation: BaseMaterial = insulation
    stucco: BaseMaterial = stucco

ElectricEquipment

Bases: BaseObj

ElectricEquipment object.

Source code in epinterface\interface.py

class ElectricEquipment(BaseObj, extra="ignore"):
    """ElectricEquipment object."""

    key: ClassVar[str] = "ELECTRICEQUIPMENT"
    Name: str
    Zone_or_ZoneList_Name: str
    Schedule_Name: str
    Design_Level_Calculation_Method: DesignLevelCalculationMethodType = "Watts/Area"
    Design_Level: float | None = None
    Watts_per_Zone_Floor_Area: float | None = None
    Watts_per_Person: float | None = None
    Fraction_Latent: float = 0.00
    Fraction_Radiant: float = 0.2
    Fraction_Lost: float = 0
    EndUse_Subcategory: str | None = None

HVACTemplateThermostat

Bases: BaseModel

HVACTemplateThermostat object.

Source code in epinterface\interface.py

class HVACTemplateThermostat(BaseModel):
    """HVACTemplateThermostat object."""

    Name: str
    Heating_Setpoint_Schedule_Name: str | None = None
    Constant_Heating_Setpoint: float | None = 21
    Cooling_Setpoint_Schedule_Name: str | None = None
    Constant_Cooling_Setpoint: float | None = 24

    def add(self, idf: IDF):
        """Add the object to the IDF object.

        Args:
            idf (IDF): The IDF object to add the object to.

        Returns:
            idf (IDF): The updated IDF object
        """
        idf.newidfobject("HVACTEMPLATE:THERMOSTAT", **self.model_dump())
        return idf

add(idf)

Add the object to the IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to add the object to.	required

Returns:

Name	Type	Description
idf	IDF	The updated IDF object

Source code in epinterface\interface.py

def add(self, idf: IDF):
    """Add the object to the IDF object.

    Args:
        idf (IDF): The IDF object to add the object to.

    Returns:
        idf (IDF): The updated IDF object
    """
    idf.newidfobject("HVACTEMPLATE:THERMOSTAT", **self.model_dump())
    return idf

HVACTemplateZoneIdealLoadsAirSystem

Bases: BaseModel

HVACTemplateZoneIdealLoadsAirSystem object.

Source code in epinterface\interface.py

class HVACTemplateZoneIdealLoadsAirSystem(BaseModel):
    """HVACTemplateZoneIdealLoadsAirSystem object."""

    Zone_Name: str
    Template_Thermostat_Name: str
    System_Availability_Schedule_Name: str | None = None
    Heating_Availability_Schedule_Name: str | None = None
    Cooling_Availability_Schedule_Name: str | None = None
    Maximum_Heating_Supply_Air_Temperature: float = 30
    Minimum_Cooling_Supply_Air_Temperature: float = 18
    Maximum_Heating_Supply_Air_Humidity_Ratio: float = 0.0156
    Minimum_Cooling_Supply_Air_Humidity_Ratio: float = 0.0077
    Heating_Limit: IdealLoadsLimitType = "NoLimit"
    Maximum_Heating_Air_Flow_Rate: float | None | Literal["autosize"] = None
    Maximum_Sensible_Heating_Capacity: float | None | Literal["autosize"] = None
    Cooling_Limit: IdealLoadsLimitType = "NoLimit"
    Maximum_Cooling_Air_Flow_Rate: float | None | Literal["autosize"] = None
    Maximum_Total_Cooling_Capacity: float | None | Literal["autosize"] = None
    Dehumidification_Control_Type: DehumidificationControlTypeType = "None"
    Cooling_Sensible_Heat_Ratio: float = 0.7
    Dehumidification_Setpoint: float = 60
    Humidification_Control_Type: HumidificationControlTypeType = "None"
    Humidification_Setpoint: float = 30
    Outdoor_Air_Method: OutdoorAirMethodType = "None"
    Outdoor_Air_Flow_Rate_per_Person: float = 0.00944
    Outdoor_Air_Flow_Rate_per_Zone_Floor_Area: float = 0.00025
    Outdoor_Air_Flow_Rate_per_Zone: float = 0.0
    # Design_Specification_Outdoor_Air_Object_Name: Optional[str] = None
    Demand_Controlled_Ventilation_Type: DemandControlledVentilationTypeType = "None"
    Outdoor_Air_Economizer_Type: OutdoorAirEconomizerTypeType = "NoEconomizer"
    Heat_Recovery_Type: HeatRecoveryTypeType = "None"
    Sensible_Heat_Recovery_Effectiveness: float = 0.7
    Latent_Heat_Recovery_Effectiveness: float = 0.65

    def add(self, idf: IDF):
        """Add the object to the IDF object.

        Args:
            idf (IDF): The IDF object to add the object to.

        Returns:
            idf (IDF): The updated IDF object
        """
        idf.newidfobject("HVACTEMPLATE:ZONE:IDEALLOADSAIRSYSTEM", **self.model_dump())
        return idf

add(idf)

Add the object to the IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to add the object to.	required

Returns:

Name	Type	Description
idf	IDF	The updated IDF object

Source code in epinterface\interface.py

def add(self, idf: IDF):
    """Add the object to the IDF object.

    Args:
        idf (IDF): The IDF object to add the object to.

    Returns:
        idf (IDF): The updated IDF object
    """
    idf.newidfobject("HVACTEMPLATE:ZONE:IDEALLOADSAIRSYSTEM", **self.model_dump())
    return idf

Lights

Bases: BaseObj

Lights object.

Source code in epinterface\interface.py

class Lights(BaseObj, extra="ignore"):
    """Lights object."""

    key: ClassVar[str] = "LIGHTS"
    Name: str
    Zone_or_ZoneList_Name: str
    Schedule_Name: str
    Design_Level_Calculation_Method: DesignLevelCalculationMethodType = "Watts/Area"
    Lighting_Level: float | None = None
    Watts_per_Zone_Floor_Area: float | None = None
    Watts_per_Person: float | None = None
    Return_Air_Fraction: float = 0
    Fraction_Radiant: float = 0.42
    Fraction_Visible: float = 0.18
    Fraction_Replaceable: float | None = 1
    EndUse_Subcategory: str | None = None

Material

Bases: BaseObj, BaseMaterial

Material object.

Source code in epinterface\interface.py

class Material(BaseObj, BaseMaterial, extra="ignore"):
    """Material object."""

    key: ClassVar[str] = "MATERIAL"
    Name: str
    Thickness: float

    @field_validator("Thermal_Absorptance", mode="before")
    def str_cast(cls, v):
        """Cast the value to a float if it is a string or empty.

        Args:
            v (Any): The value to cast.

        Returns:
            v (float): The casted value.
        """
        if v == "" or v is None:
            return None
        return float(v)

    @property
    def r(self):
        """Return the R of the material."""
        return self.Thickness / self.Conductivity

r property

Return the R of the material.

str_cast(v)

Cast the value to a float if it is a string or empty.

Parameters:

Name	Type	Description	Default
v	Any	The value to cast.	required

Returns:

Name	Type	Description
v	float	The casted value.

Source code in epinterface\interface.py

@field_validator("Thermal_Absorptance", mode="before")
def str_cast(cls, v):
    """Cast the value to a float if it is a string or empty.

    Args:
        v (Any): The value to cast.

    Returns:
        v (float): The casted value.
    """
    if v == "" or v is None:
        return None
    return float(v)

NoMassMaterial

Bases: BaseObj

NoMassMaterial object.

Source code in epinterface\interface.py

class NoMassMaterial(BaseObj, extra="ignore"):
    """NoMassMaterial object."""

    key: ClassVar[str] = "MATERIAL:NOMASS"
    Name: str
    Roughness: str
    Thermal_Resistance: float

People

Bases: BaseObj

People object.

Source code in epinterface\interface.py

class People(BaseObj, extra="ignore"):
    """People object."""

    key: ClassVar[str] = "PEOPLE"
    Name: str
    Zone_or_ZoneList_Name: str
    Number_of_People_Schedule_Name: str
    Number_of_People_Calculation_Method: NumberOfPeopleCalculationMethodType
    Number_of_People: float | None = None
    People_per_Floor_Area: float | None = None
    Floor_Area_per_Person: float | None = None
    Fraction_Radiant: float = 0.3
    Sensible_Heat_Fraction: float | Literal["autocalculate"] = "autocalculate"
    Activity_Level_Schedule_Name: str
    # Carbon_Dioxide_Generation_Rate: Optional[float] = None
    Enable_ASHRAE_55_Comfort_Warnings: Literal["Yes", "No"] = "No"

RunPeriod

Bases: BaseObj

RunPeriod object.

Source code in epinterface\interface.py

class RunPeriod(BaseObj, extra="ignore"):
    """RunPeriod object."""

    key: ClassVar[str] = "RUNPERIOD"
    Name: str
    Begin_Month: int
    Begin_Day_of_Month: int
    Begin_Year: int | None = None
    End_Month: int
    End_Day_of_Month: int
    End_Year: int | None = None
    Day_of_Week_for_Start_Day: Literal[
        "Sunday",
        "Monday",
        "Tuesday",
        "Wednesday",
        "Thursday",
        "Friday",
        "Saturday",
    ] = "Sunday"
    Use_Weather_File_Daylight_Saving_Period: Literal["Yes", "No"] = "No"
    Use_Weather_File_Holidays_and_Special_Days: Literal["Yes", "No"] = "No"
    Apply_Weekend_Holiday_Rule: Literal["Yes", "No"] = "Yes"
    Use_Weather_File_Rain_Indicators: Literal["Yes", "No"] = "No"
    Use_Weather_File_Snow_Indicators: Literal["Yes", "No"] = "No"

ScheduleDayHourly

Bases: BaseObj

ScheduleDayHourly object.

Source code in epinterface\interface.py

class ScheduleDayHourly(BaseObj, extra="ignore"):
    """ScheduleDayHourly object."""

    key: ClassVar[str] = "SCHEDULE:DAY:HOURLY"
    Name: str
    Schedule_Type_Limits_Name: str
    Hour_1: float
    Hour_2: float
    Hour_3: float
    Hour_4: float
    Hour_5: float
    Hour_6: float
    Hour_7: float
    Hour_8: float
    Hour_9: float
    Hour_10: float
    Hour_11: float
    Hour_12: float
    Hour_13: float
    Hour_14: float
    Hour_15: float
    Hour_16: float
    Hour_17: float
    Hour_18: float
    Hour_19: float
    Hour_20: float
    Hour_21: float
    Hour_22: float
    Hour_23: float
    Hour_24: float

ScheduleTypeLimits

Bases: BaseObj

ScheduleTypeLimits object.

Source code in epinterface\interface.py

class ScheduleTypeLimits(BaseObj, extra="ignore"):
    """ScheduleTypeLimits object."""

    key: ClassVar[str] = "SCHEDULETYPELIMITS"
    Name: str
    Lower_Limit_Value: float | None = None
    Upper_Limit_Value: float | None = None
    Numeric_Type: Literal["Continuous", "Discrete"] | None = None
    Unit_Type: (
        Literal[
            "Dimensionless",
            "Temperature",
            "DeltaTemperature",
            "PrecipitationRate",
            "Angle",
            "ConvectionCoefficient",
            "ActivityLevel",
            "Velocity",
            "Capacity",
            "Power",
            "Availability",
            "Percent",
            "Control",
            "Mode",
        ]
        | None
    ) = None

ScheduleWeekDaily

Bases: BaseObj

ScheduleWeekDaily object.

Source code in epinterface\interface.py

class ScheduleWeekDaily(BaseObj, extra="ignore"):
    """ScheduleWeekDaily object."""

    key: ClassVar[str] = "SCHEDULE:WEEK:DAILY"
    Name: str
    Monday_ScheduleDay_Name: str
    Tuesday_ScheduleDay_Name: str
    Wednesday_ScheduleDay_Name: str
    Thursday_ScheduleDay_Name: str
    Friday_ScheduleDay_Name: str
    Saturday_ScheduleDay_Name: str
    Sunday_ScheduleDay_Name: str

    @computed_field
    @property
    def CustomDay1_ScheduleDay_Name(self) -> str:
        """Automatically set additional day schedules."""
        return self.Monday_ScheduleDay_Name

    @computed_field
    @property
    def CustomDay2_ScheduleDay_Name(self) -> str:
        """Automatically set additional day schedules."""
        return self.Monday_ScheduleDay_Name

    @computed_field
    @property
    def Holiday_ScheduleDay_Name(self) -> str:
        """Automatically set additional day schedules."""
        return self.Sunday_ScheduleDay_Name

    @computed_field
    @property
    def SummerDesignDay_ScheduleDay_Name(self) -> str:
        """Automatically set additional day schedules."""
        return self.Monday_ScheduleDay_Name

    @computed_field
    @property
    def WinterDesignDay_ScheduleDay_Name(self) -> str:
        """Automatically set additional day schedules."""
        return self.Monday_ScheduleDay_Name

CustomDay1_ScheduleDay_Name: str property

Automatically set additional day schedules.

CustomDay2_ScheduleDay_Name: str property

Automatically set additional day schedules.

Holiday_ScheduleDay_Name: str property

Automatically set additional day schedules.

SummerDesignDay_ScheduleDay_Name: str property

Automatically set additional day schedules.

WinterDesignDay_ScheduleDay_Name: str property

Automatically set additional day schedules.

ScheduleYear

Bases: BaseObj

ScheduleYear object.

Source code in epinterface\interface.py

class ScheduleYear(BaseObj, extra="ignore"):
    """ScheduleYear object."""

    key: ClassVar[str] = "SCHEDULE:YEAR"
    Name: str
    Schedule_Type_Limits_Name: str

    ScheduleWeek_Name_1: str
    Start_Month_1: int
    Start_Day_1: int
    End_Month_1: int
    End_Day_1: int

    ScheduleWeek_Name_2: str | None = None
    Start_Month_2: int | None = None
    Start_Day_2: int | None = None
    End_Month_2: int | None = None
    End_Day_2: int | None = None

    ScheduleWeek_Name_3: str | None = None
    Start_Month_3: int | None = None
    Start_Day_3: int | None = None
    End_Month_3: int | None = None
    End_Day_3: int | None = None

    ScheduleWeek_Name_4: str | None = None
    Start_Month_4: int | None = None
    Start_Day_4: int | None = None
    End_Month_4: int | None = None
    End_Day_4: int | None = None

    ScheduleWeek_Name_5: str | None = None
    Start_Month_5: int | None = None
    Start_Day_5: int | None = None
    End_Month_5: int | None = None
    End_Day_5: int | None = None

    ScheduleWeek_Name_6: str | None = None
    Start_Month_6: int | None = None
    Start_Day_6: int | None = None
    End_Month_6: int | None = None
    End_Day_6: int | None = None

    ScheduleWeek_Name_7: str | None = None
    Start_Month_7: int | None = None
    Start_Day_7: int | None = None
    End_Month_7: int | None = None
    End_Day_7: int | None = None

    ScheduleWeek_Name_8: str | None = None
    Start_Month_8: int | None = None
    Start_Day_8: int | None = None
    End_Month_8: int | None = None
    End_Day_8: int | None = None

    ScheduleWeek_Name_9: str | None = None
    Start_Month_9: int | None = None
    Start_Day_9: int | None = None
    End_Month_9: int | None = None
    End_Day_9: int | None = None

    ScheduleWeek_Name_10: str | None = None
    Start_Month_10: int | None = None
    Start_Day_10: int | None = None
    End_Month_10: int | None = None
    End_Day_10: int | None = None

    ScheduleWeek_Name_11: str | None = None
    Start_Month_11: int | None = None
    Start_Day_11: int | None = None
    End_Month_11: int | None = None
    End_Day_11: int | None = None

    ScheduleWeek_Name_12: str | None = None
    Start_Month_12: int | None = None
    Start_Day_12: int | None = None
    End_Month_12: int | None = None
    End_Day_12: int | None = None

SimpleGlazingMaterial

Bases: BaseObj

SimpleGlazingMaterial object.

Source code in epinterface\interface.py

class SimpleGlazingMaterial(BaseObj, extra="ignore"):
    """SimpleGlazingMaterial object."""

    key: ClassVar[str] = "WINDOWMATERIAL:SIMPLEGLAZINGSYSTEM"
    Name: str
    UFactor: float
    Solar_Heat_Gain_Coefficient: float
    Visible_Transmittance: float

SimulationControl

Bases: BaseObj

SimulationControl object.

Source code in epinterface\interface.py

class SimulationControl(BaseObj, extra="ignore"):
    """SimulationControl object."""

    key: ClassVar[str] = "SIMULATIONCONTROL"
    Do_Zone_Sizing_Calculation: Literal["Yes", "No"] = "Yes"
    Do_System_Sizing_Calculation: Literal["Yes", "No"] = "Yes"
    Do_Plant_Sizing_Calculation: Literal["Yes", "No"] = "Yes"
    Run_Simulation_for_Sizing_Periods: Literal["Yes", "No"] = "Yes"
    Run_Simulation_for_Weather_File_Run_Periods: Literal["Yes", "No"] = "Yes"
    Do_HVAC_Sizing_Simulation_for_Sizing_Periods: Literal["Yes", "No"] = "Yes"
    Maximum_Number_of_HVAC_Sizing_Simulation_Passes: int = 1

SiteGroundTemperature

Bases: BaseObj

GroundTemperature object.

Source code in epinterface\interface.py

class SiteGroundTemperature(BaseObj, extra="ignore"):
    """GroundTemperature object."""

    key: ClassVar[str] = "SITE:GROUNDTEMPERATURE:BUILDINGSURFACE"
    January_Ground_Temperature: float
    February_Ground_Temperature: float
    March_Ground_Temperature: float
    April_Ground_Temperature: float
    May_Ground_Temperature: float
    June_Ground_Temperature: float
    July_Ground_Temperature: float
    August_Ground_Temperature: float
    September_Ground_Temperature: float
    October_Ground_Temperature: float
    November_Ground_Temperature: float
    December_Ground_Temperature: float

    @classmethod
    def FromValues(cls, values: list[float]):
        """Create a new SiteGroundTemperature object from a list of 12 monthly values.

        Args:
            values (list[float]): A list of 12 monthly values.

        Returns:
            ground_temp (SiteGroundTemperature): The new SiteGroundTemperature object.
        """
        if len(values) != 12:
            raise ValueError(f"GROUNDTEMP:EXPECTED_12:RECEIVED_{len(values)}")
        return cls(
            January_Ground_Temperature=values[0],
            February_Ground_Temperature=values[1],
            March_Ground_Temperature=values[2],
            April_Ground_Temperature=values[3],
            May_Ground_Temperature=values[4],
            June_Ground_Temperature=values[5],
            July_Ground_Temperature=values[6],
            August_Ground_Temperature=values[7],
            September_Ground_Temperature=values[8],
            October_Ground_Temperature=values[9],
            November_Ground_Temperature=values[10],
            December_Ground_Temperature=values[11],
        )

FromValues(values) classmethod

Create a new SiteGroundTemperature object from a list of 12 monthly values.

Parameters:

Name	Type	Description	Default
values	list[float]	A list of 12 monthly values.	required

Returns:

Name	Type	Description
ground_temp	SiteGroundTemperature	The new SiteGroundTemperature object.

Source code in epinterface\interface.py

@classmethod
def FromValues(cls, values: list[float]):
    """Create a new SiteGroundTemperature object from a list of 12 monthly values.

    Args:
        values (list[float]): A list of 12 monthly values.

    Returns:
        ground_temp (SiteGroundTemperature): The new SiteGroundTemperature object.
    """
    if len(values) != 12:
        raise ValueError(f"GROUNDTEMP:EXPECTED_12:RECEIVED_{len(values)}")
    return cls(
        January_Ground_Temperature=values[0],
        February_Ground_Temperature=values[1],
        March_Ground_Temperature=values[2],
        April_Ground_Temperature=values[3],
        May_Ground_Temperature=values[4],
        June_Ground_Temperature=values[5],
        July_Ground_Temperature=values[6],
        August_Ground_Temperature=values[7],
        September_Ground_Temperature=values[8],
        October_Ground_Temperature=values[9],
        November_Ground_Temperature=values[10],
        December_Ground_Temperature=values[11],
    )

SizingParameters

Bases: BaseObj

SizingParameters object.

Source code in epinterface\interface.py

class SizingParameters(BaseObj, extra="ignore"):
    """SizingParameters object."""

    key: ClassVar[str] = "SIZING:PARAMETERS"
    Heating_Sizing_Factor: float
    Cooling_Sizing_Factor: float

Timestep

Bases: BaseObj

Timestep object.

Source code in epinterface\interface.py

class Timestep(BaseObj, extra="ignore"):
    """Timestep object."""

    key: ClassVar[str] = "TIMESTEP"
    Number_of_Timesteps_per_Hour: int = 6

WaterUseEquipment

Bases: BaseObj

WaterUseEquipment object.

Source code in epinterface\interface.py

class WaterUseEquipment(BaseObj, extra="ignore"):
    """WaterUseEquipment object."""

    key: ClassVar[str] = "WATERUSE:EQUIPMENT"
    Name: str
    EndUse_Subcategory: str | None = None
    Peak_Flow_Rate: float
    Flow_Rate_Fraction_Schedule_Name: str | None = None
    Target_Temperature_Schedule_Name: str | None = None
    Hot_Water_Supply_Temperature_Schedule_Name: str | None = None
    Cold_Water_Supply_Temperature_Schedule_Name: str | None = None
    Zone_Name: str | None = None
    Sensible_Fraction_Schedule_Name: str | None = None
    Latent_Fraction_Schedule_Name: str | None = None

ZoneInfiltrationDesignFlowRate

Bases: BaseObj

ZoneInfiltrationDesignFlowRate object.

Source code in epinterface\interface.py

class ZoneInfiltrationDesignFlowRate(BaseObj, extra="ignore"):
    """ZoneInfiltrationDesignFlowRate object."""

    key: ClassVar[str] = "ZONEINFILTRATION:DESIGNFLOWRATE"
    Name: str
    Zone_or_ZoneList_Name: str
    Schedule_Name: str
    Design_Flow_Rate_Calculation_Method: InfDesignFlowRateCalculationMethodType
    Design_Flow_Rate: float | None = None
    Flow_Rate_per_Floor_Area: float | None = None
    Flow_Rate_per_Exterior_Surface_Area: float | None = None
    Air_Changes_per_Hour: float | None = None
    Constant_Term_Coefficient: float = 0.606
    Temperature_Term_Coefficient: float = 3.6359996e-2
    Velocity_Term_Coefficient: float = 0.117765
    Velocity_Squared_Term_Coefficient: float = 0

ZoneList

Bases: BaseModel

ZoneList object.

Source code in epinterface\interface.py

class ZoneList(BaseModel, extra="ignore"):
    """ZoneList object."""

    Name: str
    Names: list[str]

    def add(self, idf: IDF):
        """Add the object to the IDF object.

        Args:
            idf (IDF): The IDF object to add the object to.

        Returns:
            idf (IDF): The updated IDF object.
        """
        names = {
            f"Zone_{i + 1}_Name": zone for i, zone in enumerate(self.Names) if zone
        }
        idf.newidfobject("ZONELIST", Name=self.Name, **names)
        return idf

add(idf)

Add the object to the IDF object.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF object to add the object to.	required

Returns:

Name	Type	Description
idf	IDF	The updated IDF object.

Source code in epinterface\interface.py

def add(self, idf: IDF):
    """Add the object to the IDF object.

    Args:
        idf (IDF): The IDF object to add the object to.

    Returns:
        idf (IDF): The updated IDF object.
    """
    names = {
        f"Zone_{i + 1}_Name": zone for i, zone in enumerate(self.Names) if zone
    }
    idf.newidfobject("ZONELIST", Name=self.Name, **names)
    return idf

add_default_schedules(idf)

Helper to add default schedules to the IDF model.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF model to add the schedules to.	required

Returns:

Name	Type	Description
idf	IDF	The IDF model with the added schedules.
scheds	dict[str, Schedule]	A dictionary of the added schedules.

Source code in epinterface\interface.py

def add_default_schedules(idf: IDF) -> tuple[IDF, dict[str, Schedule]]:
    """Helper to add default schedules to the IDF model.

    Args:
        idf (IDF): The IDF model to add the schedules to.

    Returns:
        idf (IDF): The IDF model with the added schedules.
        scheds (dict[str, Schedule]): A dictionary of the added schedules.
    """
    # create constant scheds
    all_scheds: dict[str, Schedule] = {}
    always_on_schedule = Schedule.constant_schedule(Name="Always_On", value=1)
    always_off_schedule = Schedule.constant_schedule(Name="Always_Off", value=0)
    all_scheds["Always_On"] = always_on_schedule
    all_scheds["Always_Off"] = always_off_schedule
    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)
    all_scheds["Always On"] = always_on_schedule
    all_scheds["Always Off"] = always_off_schedule
    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)
    all_scheds["On"] = always_on_schedule
    all_scheds["Off"] = always_off_schedule
    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="AllOn", value=1)
    always_off_schedule = Schedule.constant_schedule(Name="AllOff", value=0)
    all_scheds["AllOn"] = always_on_schedule
    all_scheds["AllOff"] = always_off_schedule
    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="AlwaysOn", value=1)
    always_off_schedule = Schedule.constant_schedule(Name="AlwaysOff", value=0)
    all_scheds["AlwaysOn"] = always_on_schedule
    all_scheds["AlwaysOff"] = always_off_schedule
    year, *_ = always_on_schedule.to_year_week_day()
    year.to_epbunch(idf)
    year, *_ = always_off_schedule.to_year_week_day()
    year.to_epbunch(idf)

    return idf, all_scheds

add_default_sim_controls(idf)

Helper to add default simulation controls to the IDF model.

Parameters:

Name	Type	Description	Default
idf	IDF	The IDF model to add the simulation controls to.	required

Returns:

Name	Type	Description
IDF	IDF	The IDF model with the added simulation controls.

Source code in epinterface\interface.py

def add_default_sim_controls(idf: IDF) -> IDF:
    """Helper to add default simulation controls to the IDF model.

    Args:
        idf (IDF): The IDF model to add the simulation controls to.

    Returns:
        IDF: The IDF model with the added simulation controls.
    """
    # 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",
        Maximum_Number_of_HVAC_Sizing_Simulation_Passes=2,
    )
    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=6,
    )
    timestep.add(idf)

    sizing = SizingParameters(
        Heating_Sizing_Factor=1.15,
        Cooling_Sizing_Factor=1.15,
    )
    sizing.add(idf)

    return idf