Configure DeST-to-EnergyPlus conversion

Build a reusable options object for to_idf(). A preset supplies defaults; explicitly named settings override those defaults. The constructor checks option values and dependencies; conversion checks model and target version requirements. Windows use a documented equivalent-glazing or SimpleGlazing approximation and do not promise full DeST solver equivalence.

Usage

destep_opts(
  preset = "objects",
  ...,
  schedule_format = "compact",
  schedule_directory = NULL,
  run_period = c(1L, 365L),
  hvac = "auto",
  hvac_options = NULL,
  surface_convection = "dest",
  ventilation_density = "outdoor",
  occupant_sensible = "nominal",
  ventilation_control = "outdoor_band"
)

Arguments

preset

[string] "objects" selects source input conversion. Necessary moisture EMS remains available.

...

Must be empty. Supply custom settings by their full names.

schedule_format

[string] "compact" (default) writes date-based Schedule:Compact objects, losslessly merging consecutive identical days and equal hourly values. "file" writes all 8760 hourly values to a CSV referenced by Schedule:File objects. Neither uses weekdays to select source values. Both preserve the required unit conversions.

schedule_directory

[string or NULL] Persistent output directory, required with schedule_format = "file". Each conversion writes a unique CSV and returns absolute references; keep this file with the IDF. This directory is independent of the source weather file.

run_period

[integer vector] Inclusive, one-based simulation start and end days, from 1 to 365. Defaults to c(1L, 365L) because a saved DeST simulation range has not been established in the supported schema. Supply the days used for the source simulation when known. Dates are mapped to a non-leap calendar with daylight saving disabled. Schedules always cover the full year, including for a partial run period. Conversion guarantees the initial correspondence only; later user edits to the IDF, files or calendar are not monitored.

hvac

[string] HVAC representation. "auto" (default) reads effective room and system references: unconditioned rooms receive no air system, source load-only controls use IdealLoads, and supported actual systems select physical conversion. Incomplete or mixed source definitions stop rather than silently dropping equipment. Explicit "ideal_loads" produces a load-analysis copy even when the source contains a real system; its conversion audit records that simplification. "physical" groups conditioned rooms by their referenced AC_SYS and generates each supported air loop independently. A one-room AC_SYS_TYPE = 0 system uses a dedicated constant-volume graph. Type-0 systems with multiple rooms use constant-volume fans and fix every terminal minimum flow to its maximum flow. Type-1 systems with one or more rooms retain variable-volume fans and source terminal bounds. Multiple referenced systems may be generated in one model when each has exactly one AHU and satisfies the same documented constraints. All paths accept verified FRESH_AIR_TYPE values 1, 5, or 6. Outdoor-air type 1 uses the DeST minimum as a fixed flow and retains the maximum as a source capacity boundary. Types 5 and 6 map the source minimum and maximum flows to differential dry-bulb and differential enthalpy economizers. The type-1 path proportionally reconciles terminal minimum flows when their sum falls below the system minimum outdoor-air flow by no more than 0.01%, with a warning; larger conflicts stop conversion. Multizone paths require one shared availability schedule per system and map matching AC_SYS.SUPPLY_T_MIN/MAX schedules to the cooling-coil setpoint and use their minimum value for cooling sizing; distinct minimum and maximum trajectories remain unsupported. Physical paths generate baseline objects with the baseline version's local ExpandObjects installation, then use eplusr::transition() for higher requested targets. Necessary classes, emitted fields and the resulting object graph are validated. Baseline syntax is 9.0.1, raised to 9.1 for effective moisture sources; targets older than 9.0.1 are not maintained. Tested baseline versions and upgraded targets are evidence, not a whitelist. Supported models with a selected main water coil and no selected plant use source AHU two/four-pipe water temperature schedules without required hvac_options. Independent heating and cooling water stages are a target equivalent; their autosized performance is approximate. Selected plants and conflicting AHU water-loop ownership currently stop until their mappings are supported. Automatic and physical conversion reject effective AC_SYS_TYPE values other than 0 and 1. Unreferenced system records do not define converted equipment. Populated LIB_* tables are catalogues; they do not establish that a source model selected a chiller, boiler, or cooling tower. Nonzero people or equipment moisture requires the target calling point BeginZoneTimestepBeforeInitHeatBalance, introduced in 9.1.0. Joint physical-system and moisture runs have been checked on 9.1.0; higher versions are obtained by transition. 9.0.1 lacks that calling point and rejects nonzero sources.

hvac_options

[list or NULL] Optional target equipment overrides. Missing fan inputs use EnergyPlus 9.0.1 template defaults: total efficiency 0.7, motor efficiency 0.9, motor-in-air fraction 1; CAV supply/return pressure 600/300 Pa, VAV pressure 1000/500 Pa, and native inlet-vane power coefficients. These are target assumptions, not a conversion of DeST AHU fan-power fields. Accepted names are supply_fan_total_efficiency, supply_fan_delta_pressure_pa, supply_fan_motor_efficiency, supply_fan_motor_in_air_fraction, the corresponding four return_fan_* fields, five return_fan_power_coefficient_1 through _5 fields, zone_exhaust_fan_total_efficiency, zone_exhaust_fan_pressure_rise_pa, and heating_coil_rated_air_water_convection_ratio (native default 0.5). Flow-balancing exhaust and water-loop pumps default to zero pressure head, adding no assumed electricity. Equivalent coil water design temperatures of 7/60 C are sizing assumptions; full source schedules determine operational supply temperatures. Main coil technology, water schedules and plant choices cannot be overridden with this list. Two-pipe equivalent stages use native coil/loop availability derived from source temperatures: water must be strictly below the minimum or above the maximum supply-air bound at each hour. Intermediate or equal temperatures remain unsupported; shared loops require identical stage availability. No calendar-based season rule is inferred. Single-zone constant source supply-air bounds constrain native feedback managers; varying bounds currently stop conversion. Zone outdoor-air design allocation preserves source room minima and system total. zone_outdoor_air_flow_m3_s is an optional named ROOM.ID override, subject to the same total and terminal flow bounds. Effective values and origins are recorded per system in attr(model, "conversion")$hvac$effective_options and IDF comments.

surface_convection

[string] "dest" (default) retains fixed source coefficients on walls, floors, roofs, windows and doors using ordinary EnergyPlus surface-property objects. "energyplus" omits these overrides so EnergyPlus selects its own coefficients. Furniture's internal-mass exchange definition is retained separately.

ventilation_density

[string] "outdoor" retains EnergyPlus's outdoor-density convention; "standard" uses its site standard density, closer to the audited DeST fixed-density air exchange. Standard density currently requires EnergyPlus 26.1 or newer. Humid-air specific heat and site-reference density remain target-engine approximations.

occupant_sensible

[string] "nominal" preserves prescribed sensible watts/person. "temperature_feedback" emits standalone EMS for max(0, nominal + 5.536 * (26 - previous-hour temperature)), using the target's last completed zone-step mean as its hourly endpoint. Moisture remains nominal. The source execution switch is not inferred.

ventilation_control

[string] "outdoor_band" retains the documented temperature-band approximation. "target_prediction" emits standalone EMS using the target's own ThirdOrder air history and one-zone-step-lagged non-air coefficients to select bounded, possibly intermediate natural ventilation, including below the heating lower bound. It requires IdealLoads, standard density and EnergyPlus 26.1 or newer. This is an explicit control approximation; it does not reproduce the DeST coupled solver or guarantee improved annual loads. This option retains Site:Location (including elevation) when weather headers differ, keeping the predictor and standard-density flow on the same site reference. It does not read external simulation results.

Value

An object of class destep_options, accepted by to_idf(options = ).

HVAC support and equivalent representations

Room terminal reheat retains ROOM.SET_TERMINAL_MAX in total W and explicit ROOM ROOM_REHEATER_TYPE; positive capacity with an absent type uses a disclosed converter electric default. Single-zone CAV and multizone paths place electric reheat at the room terminal, with the source capacity ceiling and native target zone-demand control. Hot-water terminals and central AHU reheat remain unsupported. No fictitious electric preheat, chiller, boiler or cooling tower is generated for a source that only specifies its water boundary. The existing physical path supports single-zone electric steam humidification with source room-RH schedules and target autosizing. Source humidifiers with zero room and supply minimum RH are recorded as inactive. Single-zone and multizone CAV room-RH upper bounds use native temperature/humidity control on the existing cooling coil, independently of humidifier presence. Source temperature targets remain, but native humidity control can supersede them; unmet temperature/RH requirements are possible. DeST AHU optimization is not reproduced and no reheat is added for humidity control. Single-zone electric humidification also retains a source supply-RH lower bound: necessary EMS converts it using current supply-fan outlet temperature and barometric pressure, taking the larger of the room and supply minimum humidity-ratio targets without changing equipment capacity. Supply-RH upper bounds remain unsupported. An absent source humidifier stays absent; positive room lower RH then produces a warning and an audit record, without inventing equipment. Active external-steam or spray humidifiers remain unsupported. Multizone CAV/VAV electric humidification preserves a humidistat per source room and uses native critical-zone control on the shared air loop. Its target numerical humidity-ratio guards are 1e-9 and 1 kg/kg, not DeST input limits; demands outside this interval are not represented. Native low-load behavior, capacity and saturation can leave room targets unmet. Multizone CAV room upper RH uses the native critical-zone maximum humidity manager on the existing cooling coil with the same numerical guards. VAV room lower RH uses the same native minimum manager and preserves source terminal flow bounds. Active VAV dehumidification remains unsupported because native humidity override probes failed to converge. Multizone supply-RH bounds remain unsupported. Single-zone sensible heat recovery retains equal seasonal maximum coefficients when minima are zero and no source duct network or nonzero recovery pressure loss is specified. A native plate exchanger uses constant effectiveness, zero auxiliary power, and native economizer lockout. No HX outlet temperature limit or frost protection is inferred; these target assumptions and unmapped pressure loss are audited. The recovery exhaust equals the zone outdoor-air supply; this balanced exhaust topology is an equivalent assumption, not a detailed source duct-network mapping. Equal seasonal maxima do not establish constant DeST operating effectiveness. Total-heat, unequal-seasonal, and multizone recovery remain unsupported. Unsupported inputs are diagnosed rather than silently disabled. Selected positive AHU duct-network references remain unsupported, even when rated fan parameters can be read. Diagnostics identify the system, AHU and duct network; unused AHUs do not block conversion. Detailed coil performance, selected central plants, independent water loops and unresolved room-group terminal inheritance remain outside the supported subsets. Target defaults never override selected source equipment that has no implemented mapping.

People inputs and interzone surfaces

Conversion retains nominal O_DAMP_PER_PERSON. Sensible heat uses the selected nominal or target-temperature-feedback representation. Nonzero people moisture requires EnergyPlus 9.1 or newer. An unmetered OtherEquipment companion uses target vapor enthalpy to express nominal g/h/person as latent watts. Rapid temperature changes can leave a one-zone-step mass residual. People carries sensible heat only: its activity is not a comfort-model metabolic input and its latent-gain reports exclude the independent moisture source. Interzone surfaces retain their paired surface references and constructions; no neighbor-air equivalent-temperature boundary is generated.

Window and radiation representation

Windows use one direct equivalent representation; no optical prepass or weather-bound window-source schedules are generated. Supported positive-type N2 windows retain SC-derived angular optics, effective resistance and ordered emissivities. Other supported windows use the declared SimpleGlazing approximation. EnergyPlus allocates indoor solar and radiant internal gains; DeST receiving-surface weights are retained for audit, not applied by the target solver. Native window absorption nodes and glass heat capacity remain unrepresented. See to_idf() for the saved input diagnostics.

See also

to_idf()

Examples

destep_opts()
#> $preset
#> [1] "objects"
#> 
#> $schedule_format
#> [1] "compact"
#> 
#> $schedule_directory
#> NULL
#> 
#> $run_period
#> [1]   1 365
#> 
#> $hvac
#> [1] "auto"
#> 
#> $hvac_options
#> NULL
#> 
#> $surface_convection
#> [1] "dest"
#> 
#> $ventilation_density
#> [1] "outdoor"
#> 
#> $occupant_sensible
#> [1] "nominal"
#> 
#> $ventilation_control
#> [1] "outdoor_band"
#> 
#> attr(,"class")
#> [1] "destep_options"
# File schedules remain annual even when simulating days 59 through 61.
destep_opts(schedule_format = "file", schedule_directory = "schedules",
    run_period = c(59L, 61L))
#> $preset
#> [1] "objects"
#> 
#> $schedule_format
#> [1] "file"
#> 
#> $schedule_directory
#> [1] "schedules"
#> 
#> $run_period
#> [1] 59 61
#> 
#> $hvac
#> [1] "auto"
#> 
#> $hvac_options
#> NULL
#> 
#> $surface_convection
#> [1] "dest"
#> 
#> $ventilation_density
#> [1] "outdoor"
#> 
#> $occupant_sensible
#> [1] "nominal"
#> 
#> $ventilation_control
#> [1] "outdoor_band"
#> 
#> attr(,"class")
#> [1] "destep_options"
opts <- destep_opts(
    "objects",
    surface_convection = "energyplus"
)
# to_idf(dest, "23.1", options = opts)