fix: run converted models with EnergyPlus (#22)

* fix: add annual EnergyPlus run period

* fix: order compact schedule day types

* fix: simplify EnergyPlus surface polygons

* fix: convert material thickness to meters

* fix: limit thermostats to conditioned zones

* docs: record EnergyPlus simulation fixes

* test: support eplusr RunPeriod table shapes

Author: hongyuanjia

NEWS.md

@@ -1,5 +1,8 @@
 # destep 0.0.0.9000
 
+- Fixed EnergyPlus simulation initialization for converted DeST models by adding
+  an annual run period and normalizing schedule day types, surface polygons,
+  material thicknesses, and zone thermostat coverage (#22).
 - Added `GROUND_DATA` conversion to
   `Site:GroundTemperature:BuildingSurface` using monthly averages of the
   selected hourly ground-temperature series (#20).

R/conv-const.R

@@ -340,7 +340,9 @@ destep_conv_const <- function(dest, ep) {
                 name                = .(dt_mat$MATERIAL_NAME),
                 # NOTE: here we use "MediumSmooth" for roughness"
                 roughness           = "MediumSmooth",
-                thickness           = .(dt_mat$LENGTH),
+                # DeST construction lengths are stored in millimetres, while
+                # EnergyPlus Material thickness is expressed in metres.
+                thickness           = .(dt_mat$LENGTH / 1000),
                 conductivity        = .(dt_mat$MATERIAL_CONDUCTIVITY),
                 density             = .(dt_mat$MATERIAL_DENSITY),
                 specific_heat       = .(dt_mat$MATERIAL_SPECIFIC_HEAT),

R/conv-schedule.R

@@ -365,6 +365,16 @@ destep_conv_schedule_week <- function(dest, ep, schedule, type_limits, days, pre
                 }
             }
 
+            # EnergyPlus resolves day types in field order. AllOtherDays
+            # therefore has to be the final group, after every explicit type.
+            has_all_other_days <- vapply(compacted, function(daytypes) {
+                any(daytypes == ENUM_SCH_DAYTYPE[["AllOtherDays"]])
+            }, logical(1L))
+            compacted <- c(
+                compacted[!has_all_other_days],
+                compacted[has_all_other_days]
+            )
+
             len_daytype <- collapse::vlengths(compacted, use.names = FALSE)
             list(
                 rleid = rep(rleid, sum(len_daytype)),

R/conv-surface.R

@@ -85,6 +85,7 @@ destep_conv_surface <- function(dest, ep) {
     )
     assert_unique_name(surface$NAME[surface$POINT_NO == 0L], "surface")
     data.table::setDT(surface)
+    data.table::setorderv(surface, c("ID", "POINT_NO"))
 
     # find the adjacent surfaces
     surface[BOUNDARY == "Surface", by = "PLANE", BOUNDARY_OBJECT := rev(NAME)]
@@ -122,6 +123,11 @@ destep_conv_surface <- function(dest, ep) {
         )]
     }
 
+    # Use one minimal vertex sequence for each polygon. EnergyPlus simplifies
+    # adjacent polygons internally; leaving redundant collinear points can make
+    # the two otherwise identical sides end up with different vertex counts.
+    surface <- surface[, destep_simplify_surface_polygon(.SD), by = "ID"]
+
     # TODO: how does DeST handle the case when the surface is both a floor and a ceiling?
     # TODO: how does EnergyPlus handle "empty floor slab"?
 
@@ -180,3 +186,43 @@ destep_conv_surface <- function(dest, ep) {
 
     out
 }
+
+# Remove redundant vertices from one ordered DeST surface polygon while
+# retaining turns and at least the three vertices needed for a valid face.
+destep_simplify_surface_polygon <- function(surface, tolerance = 1e-8) {
+    surface <- data.table::copy(surface)
+
+    repeat {
+        n_vertex <- nrow(surface)
+        if (n_vertex <= 3L) break
+
+        previous <- c(n_vertex, seq_len(n_vertex - 1L))
+        following <- c(seq.int(2L, n_vertex), 1L)
+        coordinates <- as.matrix(surface[, .(POINT_X, POINT_Y, POINT_Z)])
+        incoming <- coordinates - coordinates[previous, , drop = FALSE]
+        outgoing <- coordinates[following, , drop = FALSE] - coordinates
+
+        incoming_length <- sqrt(rowSums(incoming ^ 2))
+        outgoing_length <- sqrt(rowSums(outgoing ^ 2))
+        cross_product <- cbind(
+            incoming[, 2L] * outgoing[, 3L] - incoming[, 3L] * outgoing[, 2L],
+            incoming[, 3L] * outgoing[, 1L] - incoming[, 1L] * outgoing[, 3L],
+            incoming[, 1L] * outgoing[, 2L] - incoming[, 2L] * outgoing[, 1L]
+        )
+        # A vertex is redundant only when the path continues straight through
+        # it. A collinear reversal is retained because it changes the polygon.
+        redundant <- incoming_length <= tolerance |
+            outgoing_length <= tolerance |
+            (
+                sqrt(rowSums(cross_product ^ 2)) <=
+                    tolerance * pmax(1, incoming_length * outgoing_length) &
+                rowSums(incoming * outgoing) > 0
+            )
+
+        if (!any(redundant) || n_vertex - sum(redundant) < 3L) break
+        surface <- surface[!redundant]
+    }
+
+    data.table::set(surface, NULL, "POINT_NO", seq_len(nrow(surface)) - 1L)
+    surface
+}

R/conv-thermostat.R

@@ -15,6 +15,16 @@ destep_conv_thermostat <- function(dest, ep) {
     skip_reason[is.na(thermostat$ROOM_GROUP_ID)] <- "ROOM.OF_ROOM_GROUP does not reference ROOM_GROUP"
     missing_setpoint <- is.na(skip_reason) & !destep_has_thermostat_setpoints(thermostat)
     skip_reason[missing_setpoint] <- "ROOM_GROUP setpoint schedule is zero or missing"
+    # A ZoneControl:Thermostat is valid only for a Zone with equipment. Keep
+    # this predicate aligned with IdealLoads so unconditioned DeST rooms do not
+    # become EnergyPlus controlled zones without EquipmentConnections.
+    unsupported_zone <- is.na(skip_reason) & (
+        is.na(thermostat$IS_AC_ROOM) |
+            thermostat$IS_AC_ROOM == 0L |
+            is.na(thermostat$AC_SCHEDULE_ID) |
+            thermostat$AC_SCHEDULE_ID == 0L
+    )
+    skip_reason[unsupported_zone] <- "ROOM_GROUP does not describe a supported ideal loads zone"
     data.table::set(thermostat, NULL, "SKIP_REASON", skip_reason)
     data.table::set(thermostat, NULL, "CAN_CONVERT", is.na(skip_reason))
     data.table::set(
@@ -28,15 +38,15 @@ destep_conv_thermostat <- function(dest, ep) {
 
     if (any(!thermostat$CAN_CONVERT)) {
         warn(sprintf(
-            "Skipped %i ROOM row(s) that do not have complete ROOM_GROUP thermostat setpoints.",
+            "Skipped %i ROOM row(s) that do not describe supported controlled zones.",
             sum(!thermostat$CAN_CONVERT)
         ))
     }
 
-    thermostat <- thermostat[thermostat$CAN_CONVERT]
-    if (nrow(thermostat) == 0L) return(NULL)
+    converted <- thermostat[thermostat$CAN_CONVERT]
+    if (nrow(converted) == 0L) return(NULL)
 
-    setpoint <- unique(thermostat[, c(
+    setpoint <- unique(converted[, c(
         "SET_T_MIN_SCHEDULE", "HEATING_SCHEDULE_NAME",
         "SET_T_MAX_SCHEDULE", "COOLING_SCHEDULE_NAME",
         "ENERGYPLUS_SETPOINT_NAME"
@@ -45,7 +55,7 @@ destep_conv_thermostat <- function(dest, ep) {
     out <- destep_combine_outputs(list(
         control_type = destep_thermostat_control_type_schedule(dest, ep),
         setpoint = destep_thermostat_setpoint_objects(dest, ep, setpoint),
-        control = destep_thermostat_control_objects(dest, ep, thermostat)
+        control = destep_thermostat_control_objects(dest, ep, converted)
     ), table = thermostat)
 
     out

R/conv.R

@@ -150,6 +150,21 @@ to_eplus <- function(dest, ver = "latest", copy = TRUE, verbose = FALSE) {
         daylighting_reference_point_coordinate_system = "Relative"
     ))
 
+    # DeST stores model inputs but no EnergyPlus simulation period.  Add a
+    # calendar-year period so each converted model can run against an EPW file.
+    ep$add("RunPeriod" := list(
+        name                                   = "Annual",
+        begin_month                            = 1L,
+        begin_day_of_month                     = 1L,
+        end_month                              = 12L,
+        end_day_of_month                       = 31L,
+        use_weather_file_holidays_and_special_days = "Yes",
+        use_weather_file_daylight_saving_period = "Yes",
+        apply_weekend_holiday_rule             = "No",
+        use_weather_file_rain_indicators       = "Yes",
+        use_weather_file_snow_indicators       = "Yes"
+    ))
+
     # update object names and make sure all names are unique
     destep_update_name(tmpdb)
 

tests/testthat/test-conv-const.R

@@ -18,5 +18,11 @@ test_that("can convert 'Construction' and 'Material'", {
             "Construction"
         )
     )
+    material_thickness <- const$value[
+        class_name == "Material" & field_name == "Thickness",
+        value_num
+    ]
+    expect_equal(max(material_thickness, na.rm = TRUE), 0.2)
+    expect_true(any(material_thickness == 0.02))
     expect_s3_class(attr(const, "table"), "data.table")
 })

tests/testthat/test-conv-schedule.R

@@ -70,4 +70,15 @@ test_that("real model schedule week and year references are resolvable", {
         ]),
         0L
     )
+
+    # AllOtherDays matches every still-unassigned day type, so EnergyPlus
+    # requires it to follow the explicit Schedule:Week:Compact assignments.
+    for (week_name in unique(week$name)) {
+        daytypes <- week[
+            name == week_name & grepl("^DayType List", field) & !is.na(value),
+            value
+        ]
+        all_other <- which(daytypes == "For: AllOtherDays")
+        if (length(all_other)) expect_equal(all_other, length(daytypes))
+    }
 })

tests/testthat/test-conv-surface.R

@@ -11,3 +11,25 @@ test_that("can convert 'BuildingSurface:Detailed'", {
     expect_equal(unique(surface$object$class_name), "BuildingSurface:Detailed")
     expect_s3_class(attr(surface, "table"), "data.table")
 })
+
+test_that("surface polygon simplification removes only redundant vertices", {
+    polygon <- data.table::data.table(
+        POINT_NO = 0:5,
+        POINT_X = c(0, 1, 2, 2, 1, 0),
+        POINT_Y = c(0, 0, 0, 1, 1, 1),
+        POINT_Z = 0
+    )
+
+    simplified <- destep_simplify_surface_polygon(polygon)
+
+    expect_equal(nrow(simplified), 4L)
+    expect_equal(simplified$POINT_NO, 0:3)
+    expect_equal(
+        simplified[, .(POINT_X, POINT_Y, POINT_Z)],
+        data.table::data.table(
+            POINT_X = c(0, 2, 2, 0),
+            POINT_Y = c(0, 0, 1, 1),
+            POINT_Z = 0
+        )
+    )
+})

tests/testthat/test-conv-thermostat.R

@@ -39,9 +39,9 @@ test_that("can convert ROOM_GROUP thermostat setpoints with shared dual setpoint
 
     expect_equal(sum(thermostat$object$class_name == "Schedule:Constant"), 1L)
     expect_equal(sum(thermostat$object$class_name == "ThermostatSetpoint:DualSetpoint"), 2L)
-    expect_equal(sum(thermostat$object$class_name == "ZoneControl:Thermostat"), 3L)
+    expect_equal(sum(thermostat$object$class_name == "ZoneControl:Thermostat"), 2L)
 
-    expect_true(all(tab$CAN_CONVERT))
+    expect_equal(tab$CAN_CONVERT, c(TRUE, FALSE, TRUE))
     expect_equal(
         tab$ENERGYPLUS_SETPOINT_NAME,
         c(
@@ -150,14 +150,14 @@ test_that("can convert ROOM_GROUP thermostat setpoints from a real DeST model",
     thermostat <- destep_conv_thermostat(dest, ep)
     tab <- attr(thermostat, "table")
 
-    expect_equal(sum(tab$CAN_CONVERT), 36L)
-    expect_equal(sum(tab$CAN_CONVERT & tab$IS_AC_ROOM == 0L), 9L)
+    expect_equal(sum(tab$CAN_CONVERT), 27L)
+    expect_equal(sum(!tab$CAN_CONVERT & tab$IS_AC_ROOM == 0L), 9L)
     expect_equal(
         unique(tab$ENERGYPLUS_SETPOINT_NAME),
         "DeST Dual Setpoint H10 C7"
     )
     expect_equal(sum(thermostat$object$class_name == "ThermostatSetpoint:DualSetpoint"), 1L)
-    expect_equal(sum(thermostat$object$class_name == "ZoneControl:Thermostat"), 36L)
+    expect_equal(sum(thermostat$object$class_name == "ZoneControl:Thermostat"), 27L)
 })
 
 test_that("to_eplus() includes resolvable thermostat references", {
@@ -177,7 +177,7 @@ test_that("to_eplus() includes resolvable thermostat references", {
     constant_names <- constant$value[constant$field == "Name"]
     year_names <- year$value[year$field == "Name"]
 
-    expect_equal(length(control_names), 36L)
+    expect_equal(length(control_names), 27L)
     expect_equal(length(setpoint_names), 1L)
     expect_true("DeST Dual Setpoint Control Type" %in% constant_names)
     expect_true(all(