Reading and running IDF files¶
trnslator is packed up with some built-in workflows to read, edit and run EnergyPlus files.
Reading¶
To read an IDF file, simply call load_idf()
with the path name. For example:
>>> from trnslator import get_eplus_dirs, load_idf
>>> eplus_dir = get_eplus_dirs("9-2-0") # Getting EnergyPlus install path
>>> eplus_file = eplus_dir / "ExampleFiles" / "BasicsFiles" / "AdultEducationCenter.idf" # Model path
>>> idf = load_idf(eplus_file) # IDF load
You can optionally pass the weather file path as well:
>>> weather = eplus_dir / "WeatherData" / "USA_IL_Chicago-OHare.Intl.AP.725300_TMY3.epw" # Weather file path
>>> idf = load_idf(eplus_file, weather_file=weather) # IDF load
Editing¶
Editing IDF files is based on the eppy package. The IDF
object returned by
load_idf()
exposes the EnergyPlus objects that make up the IDF file. These objects can be
edited and new objects can be created. See the eppy documentation for
more information on how to edit IDF files.
Hint
Pre-sets
EnergyPlus outputs can be quickly defined using the trnslator.idfclass.OutputPrep
class. This class
and its methods handle adding predefined or custom outputs to an IDF object. For example, the
idf object created above can be modified by adding a basic set of outputs:
>>> from trnslator import OutputPrep
>>> OutputPrep(idf=idf, save=True).add_basics()
See OutputPrep
for more details on all possible methods.
Running¶
Running an EnerguPlus file can be done in two ways. The first way is to call the trnslator.idfclass.run_eplus()
function with the path of the IDF file and the path of the weather file. The second method is to call the
run_eplus()
method on an IDF
object that has been
previously read. In both cases, users can also specify run options as well as output options. For example, instead of
creating an OutputPrep object, one can specify custom outputs in the
trnslator.idfclass.run_eplus.prep_outputs
attribute. These outputs will be appended to the IDF file before
the simulation is run. See run_eplus()
for other parameters to pass to run_eplus.
For the same IDF object above, the following:
>>> idf.run_eplus(weather_file=weather)
is equivalent to:
>>> from trnslator import run_eplus
>>> run_eplus(eplus_file, weather)
Hint
Caching system.
When running EnergyPlus simulations, a caching system can be activated to reduce the number of calls to the
EnergyPlus executable. This can be helpful when trnslator is called many times. This caching system will save
simulation results in a folder identified by a unique identifier. This identifier is based on the content of the IDF
file, as well as the various run_eplus()
options. If caching is activated, then
subsequent calls to the run_eplus()
method will return the cached results.
The caching system is activated by calling the trnslator.utils.config()
method, which can also be used to
set a series of package-wide options. config
would typically be put at the top of a python script:
>>> from trnslator import config
>>> config(use_cache=True)