Welcome to eprun’s documentation!

eprun is a Python package for running EnergyPlus simulations.

What is eprun?

eprun is a Python package which can be used to run EnergyPlus simulations for modelling the energy and environmental performance of buildings.

eprun contains Python functions and classes which can:

  • run an EnergyPlus simulation within the Python environment

  • view the data in EnergyPlus output files (such as .end, .err and .eso files)

  • create and/or modify EnergyPlus input files (such as .idf, .epJSON and .epw files)

Why use eprun?

eprun enables EnergyPlus to be used entirely within a Python environment. This can be useful for:

  • Using Python statements (such as for loops) to run multiple simulations for batch processing or parametric analysis

  • Analysing the simulation results using Python data analysis tools such as pandas and matplotlib

  • Creating simulation input files from scratch using Python statements

  • Modifying simulation input files and weather files directly for setting up multiple simulation runs

  • Collaborating on and version controlling EnergyPlus workflows (for example using GitHub)

  • Publishing academic papers and reports based on EnergyPlus simulations, with the option to publish the Python code which created the results as part of an Open Science workflow

Quick Demo

eprun uses the runsim function to run an EnergyPlus simulation. The code below runs an EnergyPlus simulation on an EnergyPlus input file (.idf) and an EnergyPlus weather file (.epw).

1>>> from eprun import runsim
2>>> epresult=runsim(ep_dir=r'C:\EnergyPlusV9-6-0',
3>>>                 input_filepath='1ZoneUncontrolled.idf',
4>>>                 epw_filepath='USA_CO_Golden-NREL.724666_TMY3.epw',
5>>>                 sim_dir='simulation_files')
6>>> print(type(epresult))
7<class 'eprun.epresult.EPResult'>

We can see that the simulation was successful by looking at the single line ‘.end’ file, one of the output files produced by the simulation run.

8>>> print(epresult.get_end().line)
9EnergyPlus Completed Successfully-- 0 Warning; 0 Severe Errors; Elapsed Time=00hr 00min  0.64sec

The simulation outputs are located in the ‘.eso’ file, another of the simulation output files. We can see a summary of the interval (hourly) results in the ‘RUN PERIOD 1’ simulation environment section of the eso file by using the EPEsoSimulationEnvironment.get_interval_summary method:

10>>> print(epresult.get_eso().get_environment('RUN PERIOD 1').get_interval_summary())
11Starts at 2001-01-01T00:00:00+00:00, 8760 periods @ 60 minute intervals
127 - Environment - Site Outdoor Air Drybulb Temperature (C)
138 - Environment - Site Total Sky Cover (-)
149 - Environment - Site Opaque Sky Cover (-)
1549 - ZONE ONE - Zone Total Internal Latent Gain Energy (J)
1653 - ZONE ONE - Zone Mean Radiant Temperature (C)
1777 - ZONE ONE - Zone Mean Air Temperature (C)
1878 - ZONE ONE - Zone Air Heat Balance Surface Convection Rate (W)
1979 - ZONE ONE - Zone Air Heat Balance Air Energy Storage Rate (W)

The EPEsoIntervalVariable.plot method can be used to create a quick time series plot of the hourly data. Here the hourly values for the ‘ZONE ONE - Zone Mean Air Temperature’ variable are shown.

18>>> epresult.get_eso().get_environment('RUN PERIOD 1').get_interval_variable(77).plot()
Plot of hourly intervals vs. zone mean air temperature for ZONE ONE.

The next section introduces the eprun package and gives more details and examples of how to use the eprun methods and classes.