EnergyPlus Helpdesk Tips
The EnergyPlus team strives to respond to helpdesk tickets within one business day (USA), but there are times when the response time may be delayed due to staff availability or number of support requests. In order to help us serve all users effectively, please use the following tips when submitting a help request. Thank you for your cooperation.
- Read the documentation first, please.
Please consult the EnergyPlus documentation and example files before submitting a help request (ticket). The EnergyPlus document is listed located in the "Documentation\" folder within EnergyPlus' installation directory. You also can use the index.html file in the folder to list all the documentation .pdf files and click open an individual one. - Please be specific in the subject line.
For example “Subject: Chiller Controls” is better than “Subject: EnergyPlus Question”. - Same topic – same ticket
Please submit followup questions on the same subject under the same ticket number (in e-mail use reply – do not edit the subject line). - New topic – new ticket
Please submit questions on a new topic as a new ticket. - Keep ticket posts short
Lengthy descriptions and long lists of questions are difficult for the support team to read and comprehend, slowing response times. Try to limit each post to less than 30 lines (i.e. can you read the entire question without scrolling on a laptop screen?). If you have many questions, try to prioritize the most important first. Once those are resolved, the other questions may no longer be relevant. - Use the latest version of EnergyPlus
Support is provided only for the latest release of EnergyPlus. It is good practice to use the latest release version to take advantage of the best fixes and improvements. But if you are still working with an older version, please transition and run your problem file in the latest release version before asking for help. You may find that the problem has been eliminated due to bug fixes or improved algorithms. If the problem still persists, then please submit the current version idf file. - Please be patient
If you have received the automated reply indicating the ticket number, your question is in the queue and will be answered as soon as possible. Posting the same request multiple times or posting replies which repeat the question does not help you get a faster answer (in fact, this makes it appear that the ticket has already received some attention and may result in a slower response). - Attach the idf file(s)
When asking questions about error messages or other problems with a specific input file, please attach the idf file and indicate what weather file you are using (if applicable). If the idf file uses external files such as schedule files, please include those as well. - Do not attach standard epw files
If you are using a standard epw file from energyplus.gov, please state the name of the weather file but do not attach the epw file (this takes up unnecessary space in the helpdesk database). If your are using a custom epw file or one obtained from a different source, then please attach it. - Zip or RAR multiple or large attachments
If you are attaching more than two or three files, please combine them into a single zip or rar file. Our helpdesk system does not have a “save all” button and we must save each file one at a time. So this helps us be more efficient. - Save incremental versions of idf file
It is very difficult to diagnose a problem which appeared as part of a large set of changes to the idf file. It is good practice to save frequent incremental versions of the idf file, with clear comments documenting what was changed in each version. This gives the user a point to revert to if a problem shows up and helps the support staff diagnose what went wrong. - Attach before and after idf files
If you are having problems with an input file and have a prior version of the input that was working well, please attach both files. - Compare your files
If you find that a single change to your model has caused a very unexpected result, please do a compare of the files to be certain that nothing else was changed at the same time. There are many freeware and shareware file compare utilities (or “diff” programs) available which will highlight the differences between two files. If need be, you can use IDFEditor to re-save idf files in a standard order and format to reduce unimportant differences. - Simplify your model
Keep your model as simple as possible to meet the goals of the simulation. Enormous models with 100s of zones and 1000s of surfaces cause many types of problems (data management, run time, invalid conclusions, difficulty pinpointing problems). If you are modeling the shading/reflections from surrounding buildings, model only the facades which impact your model. A full 3-d neighborhood greatly increases the shading complexities. - Show exactly where the problem is
When possible, set up the input file to run design days only and contain only Output:Variable reports required to highlight the specific problem. Indicate the specific output values (table name and column/row headings, or output variable name, date and time of simulation). A file containing hundreds of output variables or a file with long execution times (annual runs) results in a slower response. If the problem only occurs in a weather file and not during the design days, set up the weather file run period for approximately 1 week (a few days before the problem occurs and a few days after) if that still shows the issue. - Search the EnergyPlus knowledgebase and troubleshooters
The EnergyPlus helpdesk has a knowledgebase. (Note: in transition from the old portal, coming soon...) At present, it is small, but your answer might be there. - Check the unmethours.com Building Energy Modeling Community archives
The unmet hours community support is a user-to-user forum with searchable archives for more general building simulation questions (e.g. OpenStudio, EnergyPlus, and TRNSYS). You might find an answer to your problem there. (https://unmethours.com/questions/) - Remember EnergyPlus is far more complex than UAdeltaT
Users want to have confidence in the software they use, and that is understandable. If you seek to compare EnergyPlus results to other calculations or data, please consider all of the details which may be different between the EnergyPlus model - We have limited resources
The EnergyPlus support team will strive to answer specific questions to help you with your work, but we are not able to edit input files for you or provide general reviews of inputs or results. - Direct interface software questions to the vendor
Questions specific to an interface or other utility which is not part of the EnergyPlus install package should be directed to the support forum for that specific software. For example, DesignBuilder and OpenStudio have separate helpdesks/forums. - Ask the professor first
If you are a student, using EnergyPlus as part of a class or an online tutorial, please consult your instructor first. - Consider hiring a consultant for urgent projects
Standard EnergyPlus support is provided free of charge by the U.S. Department of Energy, as part of the continuing effort to improve this building simulation tool. As such, we have limited resources and must spread the effort among all users. If you have an especially urgent need, you may want to consider seeking other assistance. Expedited, priority support may be available from other sources. For a list of EnergyPlus Consultants, see https://www.buildingenergysoftwaretools.com/?capabilities=Support+Services&keys=EnergyPlus
When you believe a problem exists, check the simulation results to see if you can identify where the error occurs.
Adding specific report variables is especially useful in diagnosing a problem. Report variables can be added to a simulation via the Output:Variable reporting object. You must include the Output:VariableDictionary, IDF; object in your input file to create a report data dictionary file (rdd). Then run a simulation and view the rdd file to see which report variables are available for your simulation. Then add specific report variables to create a custom report.
See the results file (csv) for reports of all requested report variables. Try to organize your report variables to show only the problem at hand and do not include other report variables that do not directly relate to the problem. Also, do not use an annual simulation as an example. The problem can most likely be shown using only 1 or 2 days of simulation and will create an input file that runs much faster, and can therefore be answered quickly.
Follow the next general guidelines when setting up a Defect Input File:
1) add only report variables that are needed to show the problem
2) use sizing period objects (no weather file needed) or short run periods for simulations
3) specify exactly where in the outputs you see the problem (i.e., where in the html or csv)
4) tell us which weather file you are using, if any
5) include any external files (e.g., files specified in the Schedule:File object) needed to run the simulation