A rich toolkit of using the whole building simulation program 'EnergyPlus'(< https://energyplus.net>), which enables programmatic navigation, modification of 'EnergyPlus' models and makes it less painful to do parametric simulations and analysis.
eplusr provides a rich toolkit of using whole building energy simulation program EnergyPlus directly in R, which enables programmatic navigation, modification of EnergyPlus, conducts parametric simulations and retrieves outputs. More information about EnergyPlus can be found at its website.
A comprehensive introduction to eplusr can be found using
vignette("eplusr")
.
You can learn more about eplusr at
https://hongyuanjia.github.io/eplusr, along with full package
documentation.
You can install the latest stable release of eplusr from CRAN.
install.packages("eplusr")
Alternatively, you can install the development version from GitHub.
# install.packages("remotes")remotes::install_github("hongyuanjia/eplusr")
Since running the IDF files requires EnergyPlus (https://energyplus.net), EnergyPlus has to be installed if you want to run EnergyPlus models in R. There are helper functions in eplusr to download and install it automatically on major operating systems (Windows, macOS and Linux):
# install the latest version (currently v9.1.0)eplusr::install_eplus("latest")# OR download the latest version (currently v9.1.0) and run the installer# manually by yourselfeplusr::download_eplus("latest", dir = tempdir())
Note that the installation process in install_eplus()
requires
administrative privileges. You have to run R with administrator (or
with sudo if you are on macOS or Linux) to make it work if you are not
in interactive mode.
Below shows the class structure in eplusr.
Basically, eplusr uses Idf
class to present the whole IDF file and
IdfObject
class to present a single object in an IDF. Both Idf
and
IdfObject
class contain member functions for helping modify the data
in IDF so it complies with the underlying EnergyPlus IDD (Input Data
Dictionary). Similarly, IDD file is wrapped into two classes, i.e. Idd
and IddObject
.
Besides, Epw
class is used to present EnergyPlus Weather files;
EplusJob
to run single EnergyPlus simulation and collect outputs,
ParametricJob
to run parametric EnergyPlus simulations and collect all
outputs.
It is highly recommended to read the documentation to get a thorough understanding on each class.
library(eplusr)# parse IDDidd <- use_idd(8.8, download = "auto")#> IDD v8.8.0 has not been parsed before.#> Try to locate `Energy+.idd` in EnergyPlus v8.8.0 installation folder `/usr/local/EnergyPlus-8-8-0`.#> IDD file found: `/usr/local/EnergyPlus-8-8-0/Energy+.idd`.#> Start parsing...#> Parsing completed.# read IDFidf <- read_idf(system.file("extdata/1ZoneUncontrolled.idf", package = "eplusr"))# print idfidf#> ── EnergPlus Input Data File ──────────────────────────────────────────────#> * Path: `/tmp/RtmptLtk5U/temp_libpath6ffe2e3be6cb/eplusr/extdata/1Zon...#> * Version: `8.8.0`#>#> Group: <Simulation Parameters>#> ├─ [01<O>] Class: <Version>#> │─ [01<O>] Class: <SimulationControl>#> │─ [01<O>] Class: <Building>#> │─ [01<O>] Class: <SurfaceConvectionAlgorithm:Inside>#> │─ [01<O>] Class: <SurfaceConvectionAlgorithm:Outside>#> │─ [01<O>] Class: <HeatBalanceAlgorithm>#> └─ [01<O>] Class: <Timestep>#>#> Group: <Location and Climate>#> ├─ [01<O>] Class: <Site:Location>#> │─ [02<O>] Class: <SizingPeriod:DesignDay>#> └─ [01<O>] Class: <RunPeriod>#>#> Group: <Schedules>#> ├─ [02<O>] Class: <ScheduleTypeLimits>#> └─ [01<O>] Class: <Schedule:Constant>#>#> Group: <Surface Construction Elements>#> ├─ [01<O>] Class: <Material>#> │─ [02<O>] Class: <Material:NoMass>#> └─ [03<O>] Class: <Construction>#>#> Group: <Thermal Zones and Surfaces>#> ├─ [01<O>] Class: <GlobalGeometryRules>#> │─ [01<O>] Class: <Zone>....# extract objectidf$Material_NoMass$R13LAYER#> <IdfObject: `Material:NoMass`> [ID:12] `R13LAYER`#> Class: <Material:NoMass>#> ├─ 1: "R13LAYER", !- Name#> │─ 2: "Rough", !- Roughness#> │─ 3: 2.290965, !- Thermal Resistance {m2-K/W}#> │─ 4: 0.9, !- Thermal Absorptance#> │─ 5: 0.75, !- Solar Absorptance#> └─ 6: 0.75; !- Visible Absorptance# get object relationidf$object_relation("R13LAYER", "all")#> ── Refer to Others ────────────────────────────────────────────────────────#> Target(s) does not refer to any other field.#>#> ── Referred by Others ─────────────────────────────────────────────────────#> Class: <Material:NoMass>#> └─ Object [ID:12] <R13LAYER>#> └─ 1: "R13LAYER"; !- Name#> ^~~~~~~~~~~~~~~~~~~~~~~~~#> └─ Class: <Construction>#> └─ Object [ID:15] <R13WALL>#> └─ 2: "R13LAYER"; !- Outside Layer#># extract field valueidf$RunPeriod[[1]][c("Begin Month", "End Month")]#> $`Begin Month`#> [1] 1#>#> $`End Month`#> [1] 12# add new objectidf$add(RunPeriod = list("run_period", 3, 1, 4, 1))#> $run_period#> <IdfObject: `RunPeriod`> [ID:54] `run_period`#> Class: <RunPeriod>#> ├─ 01: "run_period", !- Name#> │─ 02: 3, !- Begin Month#> │─ 03: 1, !- Begin Day of Month#> │─ 04: 4, !- End Month#> │─ 05: 1, !- End Day of Month#> │─ 06: "UseWeatherFile", !- Day of Week for Start Day#> │─ 07: "Yes", !- Use Weather File Holidays and Special Days#> │─ 08: "Yes", !- Use Weather File Daylight Saving Period#> │─ 09: "No", !- Apply Weekend Holiday Rule#> │─ 10: "Yes", !- Use Weather File Rain Indicators#> └─ 11: "Yes"; !- Use Weather File Snow Indicators# get possible values for fieldsidf$Construction$FLOOR$value_possible("Outside Layer")#> ── 2: Outside Layer ───────────────────────────────────────────────────────#> * Auto value: <NA>#> * Default: <NA>#> * Choice: <NA>#> * Source:#> - "C5 - 4 IN HW CONCRETE"#> - "R13LAYER"#> - "R31LAYER"# read EPWpath_epw <- file.path(eplus_config(8.8)$dir, "WeatherData/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw")epw <- read_epw(path_epw)# print weatherepw#> ══ EnergyPlus Weather File ════════════════════════════════════════════════#> [Location ]: San Francisco Intl Ap, CA, USA#> {N 37°37'}, {W 122°24'}, {UTC-08:00}#> [Elevation]: 2m above see level#> [Data Src ]: TMY3#> [WMO Stat ]: 724940#> [Leap Year]: FALSE#> [Interval ]: 60 mins#>#> ── Data Periods ───────────────────────────────────────────────────────────#> Name StartDayOfWeek StartDay EndDay#> 1: Data Sunday 1/ 1 12/31#>#> ───────────────────────────────────────────────────────────────────────────# get location(loc <- epw$location())#> $city#> [1] "San Francisco Intl Ap"#>#> $state_province#> [1] "CA"#>#> $country#> [1] "USA"#>#> $data_source#> [1] "TMY3"#>#> $wmo_number#> [1] "724940"#>#> $latitude#> [1] 37.62#>#> $longitude#> [1] -122.4#>#> $time_zone#> [1] -8#>#> $elevation#> [1] 2# update Site:Location according to EPW LOCATION headeridf$Site_Location$set(name = paste(loc$city, loc$state_province, loc$country),loc$latitude, loc$longitude, loc$time_zone, loc$elevation)#> <IdfObject: `Site:Location`> [ID:9] `San Francisco Intl Ap CA USA`#> Class: <Site:Location>#> ├─ 1: "San Francisco Intl Ap CA USA", !- Name#> │─ 2: 37.62, !- Latitude {deg}#> │─ 3: -122.4, !- Longitude {deg}#> │─ 4: -8, !- Time Zone {hr}#> └─ 5: 2; !- Elevation {m}# save the IDFidf$save(file.path(tempdir(), "model.idf"), overwrite = TRUE)# extract weather data(weather <- head(epw$data()))#> datetime year month day hour minute#> 1: 2017-01-01 01:00:00 1999 1 1 1 0#> 2: 2017-01-01 02:00:00 1999 1 1 2 0#> 3: 2017-01-01 03:00:00 1999 1 1 3 0#> 4: 2017-01-01 04:00:00 1999 1 1 4 0#> 5: 2017-01-01 05:00:00 1999 1 1 5 0#> 6: 2017-01-01 06:00:00 1999 1 1 6 0#> datasource dry_bulb_temperature#> 1: ?9?9?9?9E0?9?9?9?9?9?9?9?9?9?9?9?9?9?9?9*9*9?9?9?9 7.2#> 2: ?9?9?9?9E0?9?9?9?9?9?9?9?9?9?9?9?9?9?9?9*9*9?9?9?9 7.2#> 3: ?9?9?9?9E0?9?9?9?9?9?9?9?9?9?9?9?9?9?9?9*9*9?9?9?9 6.7#> 4: ?9?9?9?9E0?9?9?9?9?9?9?9?9?9?9?9?9?9?9?9*9*9?9?9?9 6.1#> 5: ?9?9?9?9E0?9?9?9?9?9?9?9?9?9?9?9?9?9?9?9*9*9?9?9?9 4.4#> 6: ?9?9?9?9E0?9?9?9?9?9?9?9?9?9?9?9?9?9?9?9*9*9?9?9?9 4.4#> dew_point_temperature relative_humidity atmospheric_pressure#> 1: 5.6 90 102200#> 2: 5.6 90 102100#> 3: 5.0 89 102200#> 4: 5.0 93 102200#> 5: 3.9 97 102200#> 6: 3.9 97 102200#> extraterrestrial_horizontal_radiation#> 1: 0#> 2: 0#> 3: 0#> 4: 0#> 5: 0#> 6: 0#> extraterrestrial_direct_normal_radiation#> 1: 0....# a date time column added with correct start day of week typeepw$period()$start_day_of_week#> [1] 7weekdays(weather$datetime)#> [1] "Sunday" "Sunday" "Sunday" "Sunday" "Sunday" "Sunday"# run simulationjob <- idf$run(epw)#> ── Info ───────────────────────────────────────────────────────────────────#> Adding object `Output:SQLite` and setting `Option Type` to `SimpleAndTabular` in order to create SQLite output file.#>#> ── Info ───────────────────────────────────────────────────────────────────#> Replace the existing IDF located at /tmp/RtmptLtk5U/model.idf.#>#> ExpandObjects Started.#> No expanded file generated.#> ExpandObjects Finished. Time: 0.005#> EnergyPlus Starting#> EnergyPlus, Version 8.8.0-7c3bbe4830, YMD=2019.05.03 16:13#> Processing Data Dictionary#> Processing Input File#> Initializing Simulation#> Reporting Surfaces#> Beginning Primary Simulation#> Initializing New Environment Parameters#> Warming up {1}#> Warming up {2}#> Warming up {3}#> Warming up {4}#> Warming up {5}#> Warming up {6}#> Warming up {7}#> Warming up {8}#> Warming up {9}#> Warming up {10}#> Warming up {11}#> Warming up {12}#> Warming up {13}....# print simulation errorjob$errors()#> ══ EnergyPlus Error File ══════════════════════════════════════════════════#> * EnergyPlus version: 8.8.0 (7c3bbe4830)#> * Simulation started: 2019-05-03 16:13:00#> * Terminated: FALSE#> * Successful: TRUE#> * Warning[W]: 2#>#> ── During Simulation Initiation ───────────────────────────────────────────#> [W 1/2] SetUpDesignDay: Entered DesignDay Barometric Pressure=81198 differs#> by more than 10% from Standard Barometric Pressure=101301.#> ...occurs in DesignDay=DENVER CENTENNIAL GOLDEN N ANN HTG 99%#> CONDNS DB, Standard Pressure (based on elevation) will be used.#> [W 2/2] SetUpDesignDay: Entered DesignDay Barometric Pressure=81198 differs#> by more than 10% from Standard Barometric Pressure=101301.#> ...occurs in DesignDay=DENVER CENTENNIAL GOLDEN N ANN CLG 1% CONDNS#> DB=>MWB, Standard Pressure (based on elevation) will be used.# get report dataresults <- job$report_data("zone one", "zone mean air temperature",case = "example", month = 1:6, hour = 1, day_type = "Monday",all = TRUE)str(results)#> Classes 'data.table' and 'data.frame': 29 obs. of 21 variables:#> $ case : chr "example" "example" "example" "example" ...#> $ datetime : POSIXct, format: "2019-01-07 01:00:00" "2019-01-14 01:00:00" ...#> $ month : int 1 1 1 1 2 2 2 2 3 3 ...#> $ day : int 7 14 21 28 4 11 18 25 4 11 ...#> $ hour : int 1 1 1 1 1 1 1 1 1 1 ...#> $ minute : int 0 0 0 0 0 0 0 0 0 0 ...#> $ dst : int 0 0 0 0 0 0 0 0 0 0 ...#> $ interval : int 60 60 60 60 60 60 60 60 60 60 ...#> $ simulation_days : int 7 14 21 28 35 42 49 56 63 70 ...#> $ day_type : chr "Monday" "Monday" "Monday" "Monday" ...#> $ environment_name : chr "San Francisco Intl Ap CA USA TMY3 WMO#=724940" "San Francisco Intl Ap CA USA TMY3 WMO#=724940" "San Francisco Intl Ap CA USA TMY3 WMO#=724940" "San Francisco Intl Ap CA USA TMY3 WMO#=724940" ...#> $ is_meter : int 0 0 0 0 0 0 0 0 0 0 ...#> $ type : chr "Avg" "Avg" "Avg" "Avg" ...#> $ index_group : chr "Zone" "Zone" "Zone" "Zone" ...#> $ timestep_type : chr "HVAC System" "HVAC System" "HVAC System" "HVAC System" ...#> $ key_value : chr "ZONE ONE" "ZONE ONE" "ZONE ONE" "ZONE ONE" ...#> $ name : chr "Zone Mean Air Temperature" "Zone Mean Air Temperature" "Zone Mean Air Temperature" "Zone Mean Air Temperature" ...#> $ reporting_frequency: chr "Hourly" "Hourly" "Hourly" "Hourly" ...#> $ schedule_name : chr NA NA NA NA ...#> $ units : chr "C" "C" "C" "C" ...#> $ value : num 10.8 11.8 13.1 10.5 11.9 ...#> - attr(*, ".internal.selfref")=<externalptr># a date time column added with correct day of week typeall(weekdays(results$datetime) == results$day_type)#> [1] TRUE# get tabular datajob$tabular_data(table_name = "site and source energy", row_name = "total site energy")#> index report_name report_for#> 1: 1 AnnualBuildingUtilityPerformanceSummary Entire Facility#> 2: 5 AnnualBuildingUtilityPerformanceSummary Entire Facility#> 3: 9 AnnualBuildingUtilityPerformanceSummary Entire Facility#> table_name column_name#> 1: Site and Source Energy Total Energy#> 2: Site and Source Energy Energy Per Total Building Area#> 3: Site and Source Energy Energy Per Conditioned Building Area#> row_name units value#> 1: Total Site Energy GJ 89.81#> 2: Total Site Energy MJ/m2 386.67#> 3: Total Site Energy MJ/m2
I would like to thank many open source projects who have heavily inspired the development of eplusr package, especially these below:
Hongyuan Jia
The project is released under the terms of MIT License.
Copyright © 2016-2019 Hongyuan Jia
This is a patch update mainly to fix CRAN check errors on a strict Latin locale, with a bug fix.
$report_data()
method in EplusSql
class now correctly returns data if
even if key_value
is not given (#37)This is a patch update mainly to fix CRAN check errors, with few bug fixes.
$set()
method in Idf
class now does not try to convert all input strings
into numbers (#32)$del()
method in Idf
class now also respects validation settings.
You should be able to delete any object if current validation level does not
include reference checking$del()
method in Idf
class now will only print object relation only if
.ref_to
or .ref_by
is TRUE
$set()
method in Epw
class will correctly reset leap year flag in the
header (#32)$save()
method in Epw
class returns the path of saved file invisiblyeplusr v0.10.0 introduces dozens of improvements, unfortunately also has some break changes. Detailed updates per class are as follow:
Idd
Class$object()
now takes a single class name and returns an IddObject
.
New method $objects()
is added as the successor of $object()
in previous
versions.
New method $object_relation()
and $objects_in_relation()
are added to get
all objects that have relation (one refer to others or one referred by others).
$object_in_group()
has been deprecated in flavor of $objects_in_group()
.
New method $to_table()
and $to_string()
are added to help easily extract
internal IDD data in data.table
format and string format respectively.
$clone()
method is now deprecated.
S3 method str.Idd()
, format.Idd()
are added.
IddObject
ClassA constructor idd_object()
has been added to help directly create
IddObject
. It takes a parent IDD version or an Idd
object and a valid
class name or class index, e.g. idd_object(8.8, "Material")
,
idd_object(use_idd(8.8), "Construction")
New method $version()
is added to extract the version of parent IDD.
New method $field_relation()
is added to extract the field relation in
current class with other class fields.
New method $has_ref()
, $has_ref_to()
, and $has_ref_by()
are added to
help to detect field relations
New method $is_real_field()
is added to detect if specified fields should
have values of real numbers but not integers.
New method $has_ref()
, $has_ref_by()
, $has_ref_to()
are added to detect
if specified fields refer to other fields or can be referred by other field in
other classes.
New method $to_table()
and $to_string()
are added to help easily extract
internal IDD data in data.table
format and string format respectively.
field_possible()
now does not need IdfObject
data to run.
Argument lower
in $field_name()
has been deprecated.
$field_reference()
in IddObject
class has been deprecated in flavor of
$field_relation()
.
A brief
argument is added in $print()
with default value of FALSE
. If
TRUE
, only the class name of the IddObject
is printed.
$clone()
method is now deprecated.
S3 method format.IddObject()
, as.character.IddObject()
and
str.IddObject()
are added which calls $to_string()
and $print()
.
Idf
ClassAn argument sorted
is added in $class_name()
and $group_name()
to control
whether to sort the returned value according to the occurrence in IDD or not.
$definition()
now only accepts one class name and returns a single
IddObject
, not a list of IddObject
.
$object()
now takes a single object ID or name and returns an IdfObject
.
New method $objects()
is added as the successor of $object()
in previous
versions.
New method $object_unique()
is added which returns an IdfObject
in
unique-object class, e.g. SimulaSimulationContrl
. This makes it easy to
directly extract and modify those objects, e.g.
model$object_unique("SimulationContrl")$set(...)
.
$object_in_class()
now is deprecated in flavor of $objects_in_class()
.
New method $objects_in_group()
is added to get all objects in specified group.
$search_object()
, $search_value()
and $replace_value()
now can take same
arguments as base::grepl()
to further control the way it searches objects.
$replace_value()
now will perform validations when replacing value.
Now all methods in Idf
class that return IdfObject
s will not convert
object names into valid R names. The former conversion behavior is unnecessary
and a little bit confusing.
$add_object()
, $set_object()
, $del_object()
, $ins_object()
and
$del_object()
are now all deprecated. Please use $add()
, $set()
,
$del()
and insert()
instead, which provide much cleaner syntax.
New method $rename()
is added which helps to modify only object names.
New method $paste()
is added which will parse contents that copied from IDF
Editor using the Copy Obj
button and directly insert them into current Idf
.
$validate()
and $is_valid()
now accepts an argument level
. Also, a
helper custom_validate()
is added to customize what kind of validations to
check.
$string()
is deprecated in flavor of $to_string()
in Idf
class.
New method $to_table()
is added which can extract object data into a
data.table
.
The default value of deep
argument in $clone()
method is set to TRUE
. As
in almost all cases, a total cloned object is desired when calling $clone()
.
plain
argument is deprecated in $print()
in IDF class. Because the same
thing can be achieved using $to_string()
and base::cat()
. New argument
zoom
and order
are added, which give more control on how detailed should
the model be printed.
New method $object_relation()
and $objects_in_relation()
are added to
extract all objects in relation.
IdfObject
ClassNew constructor idf_object()
is added.
New method $version()
is added to get the underlying version of IDD.
$get_comment()
, $get_value()
now have been deprecated in flavor of
$comment()
and $value()
$comment()
(former $get_comment()
) now returns NULL
if the object does
not have any comment.
$set_value()
now has been deprecated in flavor of $set()
$possible_value()
now has been deprecated in flavor of $value_possible()
.
$ref_from_object()
and $has_ref_from()
now have been deprecated in flavor
of $ref_to_object()
and $has_ref_to()
.
$has_ref_by()
, $has_ref_to()
and $has_ref()
now return a logical vector
of the same length as field numbers.
$validate()
and $is_valid()
now accepts an argument level
. Also, a
helper custom_validate()
is added to customize what kind of validations to
check.
$string()
and $table()
are now deprecated in flavor of $to_string()
and
$to_table()
.
$clone()
method is now deprecated.
S3 methods format.IdfObject()
, as.character.IdfObject()
and
str.IdfObject()
are added, which calls $to_string()
and $value()
.
Epw
ClassEpw
class has been totally rewritten which provides much more
functionalities. Please refer to package documentation for details.
All headers are parsed and can be retrieve in Epw
class.
The default value of deep
in $clone()
has been change to TRUE
.
EplusSql
ClassNew method $path_idf()
is added to return the parent IDF file path.
New arguments period
, month
, day
, hour
, minute
, interval
,
simulation_days
, day_type
and environment_name
are added in
$report_data()
which provide extra subsetting on the SQL file.
New arguments report_name
, report_for
, table_name
, column_name
and
row_name
are added in $tabular_data()
which provide extra subsetting on
the SQL file.
$clone()
method is now deprecated.
EplusJob
ClassNew method $path()
is added to return the path of IDF and/or EPW file of
the job.
New method $list_table()
, $read_table()
are added which provide the same
functionalities as they are in EplusSql
class.
$clone()
is now deprecated.
New arguments period
, month
, day
, hour
, minute
, interval
,
simulation_days
, day_type
and environment_name
are added in
$report_data()
which provide extra subsetting on the SQL file.
New arguments report_name
, report_for
, table_name
, column_name
and
row_name
are added in $tabular_data()
which provide extra subsetting on
the SQL file.
$clone()
method is now deprecated.
ParametricJob
ClassNew arguments force
and copy_external
are added in $run()
which have the
same effect as in $run()
method in Idf
class.
New arguments period
, month
, day
, hour
, minute
, interval
,
simulation_days
, day_type
and environment_name
are added in
$report_data()
which provide extra subsetting on the SQL file.
New arguments report_name
, report_for
, table_name
, column_name
and
row_name
are added in $tabular_data()
which provide extra subsetting on
the SQL file.
$clone()
method is now deprecated.
Function read_err()
is added which takes a path of an .err
file, parses it
and returns an ErrFile
object.
Functions is_eplus_ver()
, is_idd_ver()
, is_eplus_path()
, is_idd()
,
is_idf()
, is_iddobject()
, is_idfobject()
and is_epw()
are now exported.
Function custom_validate()
and level_checks()
are added to customize
validation.
Right now, all returned object and field names will remain what they are as in
the IDF, instead of converting them into underscore
style names in the
returned lists.
The num_digits
option has been deprecated as formatting of numeric fields
are now handled by R itself.
Error will be given instead of warning if there is no build tag or multiple build tags found in input IDD.
eplusr_option()
accepts custom validate level using newly-added function
custom_validate()
.
download_weather()
. It takes a regular
expression as input, searches through EnergyPlus weather data base (stored
in this package), download corresponding files and return the saved paths.
Below are some examples:
"los angeles"
and "tmy"
, return a
menu to select which one(s) to download. Once selected, download both
corresponding weather file(s) and design day file(s):download_weather("los angeles.*tmy", type = "all", ask = TRUE)
la.epw(ddy)
,
la_1.epw(ddy)
, la_2.epw(ddy)
:download_weather("los angeles.*tmy", filename = "la", type = "all", ask = TRUE)
"beijing"
and "cswd"
. If no more
than 3 results found, directly download all weather files and save them to
temporary directory.download_weather("beijing.*cswd", dir = tempdir(), type = "epw", ask = FALSE, max_match = 3)
clean_wd()
is run before every call to EnergyPlus.$clone()
method has been refactored for Idf
and Idd
class. This fix the
issue that internal shared environments were not cloned in version 0.9.3.
Fix the error that $save()
and $string()
in Idf
class did not respect
format
argument.
Fix the error that $apply_measure()
in ParametricJob
class did not
respect .names
argument.
$clone()
method in R6 in
order to be compatible with (#19). After this, deep
has to be set to TRUE
if a completed cloned copy is desired. Also, documentations on $clone()
method in Epw
, EplusJob
, ParametricJob
have been added.clean_wd()
is called internally when running EnergyPlus models. This
guarantees that the old output file from last simulation is cleaned up before
the new simulation starts.A new class EplusSql
has been added. This makes it possible to directly
retrieve simulation results without creating an EplusJob
object which can
only get simulation outputs after the job was successfully run before. It can
be easily created using eplus_sql()
function. However, it should be noted
that, unlike EplusJob
, there is no checking on whether the simulation is
terminated or completed unsuccessfully, or the parent Idf has been changed
since last simulation. This means that you may encounter some problems when
retrieve data from an unsuccessful simulation. It is suggested to carefully go
through the .err
file to make sure the output data in the SQLite is correct
and reliable. Currently, there are only few methods in EplusSql
class which
have some overlaps with theses in EplusJob
, but more methods may be added in
the future. For more details, please see the documentation of EplusSql
.
A new method $is_double_field()
is added to IddObject
class to check if
specified fields should be double numbers
dir
is not NULL
in $run()
in
Idf
class.Fix the error when checking invalid extensible fields in value validation.
Fix the error that value references did not get updated when setting values to
NA
in $set_value()
in IdfObject
and $set_object()
in Idf
.
parallel_backend
argument in run_multi()
has been removed, due to the
reason that supporting remote parallel computing is out of the scope of this
package. This makes it possible to remove both future
and furrr
package
dependencies. The default behavior of run_multi()
does not change if
running on local machine, as it still runs multiple EnergyPlus instances in
parallel.
In run_idf()
and run_multi()
, eplus
argument has been moved to be the
last argument with default value setting to NULL
. This will make them a
little bit more convenient to run EnergyPlus without explicitly specify the
version. If NULL
, the version of EnergyPlus is automatically detected using
the version field of input model. For example:
# beforerun_idf(8.8, model.idf, weather.epw) # afterrun_idf(model.idf, weather.epw)
Both argument echo
and wait
have been added to run_idf()
and
run_multi()
. Unlike the behavior in eplusr 0.8.3 when echo
is TRUE
in
run_idf()
, right now echo
only control whether to show the output from
EnergyPlus command line interface. Please use wait
to control whether to wait
until the simulation is complete or not.
Package documentation has been heavily updated. Examples of every exported
class and most functions have been added. Also, an example IDF file
"1ZoneUncontrolled.idf"
from EnergyPlus v8.8.0 is included in the package,
which makes it possible to run most examples without installing EnergyPlus. Of
cause, for examples in EplusJob
and ParametricJob
class, EnergyPlus
installation is needed to run them successfully.
The brilliant package crayon is
used to support colorful printing of Idd
, Idf
, IddObject
, IdfObject
,
Epw
, EplusJob
and ParametricJob
classes.
A new type of "character"
validation has been added, which will check if
field values should be characters but are not.
A new option copy_external
has been added in $run()
in Idf
class. If
TRUE
, the external files will also be copied into the output directory.
Currently, only Schedule:File
class is supported. This ensures that the
output directory will have all files needed for the model to run.
$validate()
in Idf
and IdfObject
class will also check incomplete
extensible groups. Extensible groups that only contain any empty field are
treated as invalid.
New methods $field_reference()
and $field_possible()
have been added into
IddObject
class. $field_possible()
is basically the same as the
$possible_value()
in IdfObject
class. This makes it possible to show all
available references for a class that does not have any object yet.
$field_reference()
only returns all available reference values for specified
fields. NOTE: $field_reference()
and $field_possible()
can only be
used in IddObject
s that are created using $definition()
in Idf
class and
IdfObject
class, and cannot be used in IddObject
s that are created using
$object()
or equivalent in Idd
class. This is because both methods need
shared Idf value data to collect all reference values.
use_eplus()
now returns an invisible list of EnergyPlus configure data
instead of NULL
.
The default value of dir
argument in download_eplus()
has been removed,
which enforce the user to explicitly specify the directory to save
EnergyPlus installer file, as per CRAN reviewer comment.
A new option "auto"
for download
argument in use_idd()
has been added,
which will automatically download corresponding EnergyPlus IDD file if the
file or Idd object is currently not available.
The dir
argument in install_eplus()
has been removed, as per CRAN reviewer
comments. The EnergyPlus installer file will be saved into tempdir()
.
The default value of dir
argument in $run()
in Idf
class has been
removed, as per CRAN reviewer comments. Users can explicitly set dir
to
NULL
if they want to use the directory of input IDF file.
The default value of echo
in run_idf()
has been changed to TRUE
, which
will always show EnergyPlus simulation process to the console.
Fix the error of output_dir
argument checking in rum_multi()
.
Now an informative error message is given when there is no SQL output found
when trying to read simulation output using $report_data()
,
$report_data_dict
and tabular_data()
in EplusJob
class.
run_idf()
and run_multi()
now does not call clean_wd()
as this is
automatically handled by EnergyPlus itself.
Fix errors when try to get units $field_name()
, $field_unit()
and
$field_default()
in IddObject
class.
Fix the error that $get_value()
and $table()
in IdfObject
class did not
return all field values even all
was set to TRUE
.
Fix the error that $table()
in IdfObject
class did not return field units
even unit
was set to TRUE
.
Fix the error that $replace_value()
in Idf
class did not update object
names.
Fix the error when unit
is set to TRUE
in $get_data()
in Epw
class.
Fix the error that $state_province
in Epw
class always returns NULL
.
Fix the error of missing expanded IDF files which occurred randomly in
run_multi()
.
A new method $possible_value()
has been added into IdfObject
class, which
will return all possible values for selected fields, including auto-value
(autosize or autocalculate), default, range, choices and references.
New parameter dir
has been added to install_eplus()
, which makes it
possible for keeping the downloaded EnergyPlus installation file.
$dup_object()
in Idf
class now can duplicate one object multiple times.
The names of returned list of $get_value()
in IdfObject
is "underscore"
name, not lower name. This makes its behavior being consistent with
$object()
in Idf
class.
When wait
is FALSE
, $run()
in EplusJob
and ParametricJob
will
return itself instead of the time when simulation started.
A clear message will be given when trying to run $kill()
in ParametricJob
,
which inform the user that currently $kill()
does not for parametric
simulations.
A warning will be given if no configuration data found in eplus_config()
.
Now the names of returned list from $search_object()
in Idf
class will
also be underscore-style object names, which makes its behavior being
consistent with $object()
and $object_in_class()
. Also, if no results
found, $search_object()
now will return invisible NULL
and give a message.
$dup_object()
will give an error if given new_name
is the an existing
object name.
Fix errors in $status()
, $output_dir()
and $locate_output()
in
ParametricJob
class when which
arg is not given (#12).
Fix idf input version parsing in param_job
(#13).
Fix EnergyPlus downloading and installing errors on Linux and macOS (#14, #17).
Fix run_idf()
and run_multi()
errors on Linux and macOS (#14).
Fix missing name attribute in class NodeList
(#16).
Fix errors in use_eplus()
when input is an EnergyPlus installation path (#18).
$get_value()
in IdfObject
class new has a new argument simplify
. If
TRUE
, a character vector will be returned instead of a named list. Default
is FALSE
.$get_value()
in IdfObject
is "underscore"
name, not lower name. This makes its behavior being consistent with
$object()
in Idf
class.Fix warning messages of column type coercion from data.table in Idf
and
IdfObject
.
$set_value()
in IdfObject
and $set_object()
in Idf
now will delete empty
fields with empty value. This fix the error when trying to reassign only some
empty fields which have been deleted before.