EnergyPlus development: step by step[LINK]
Understanding the general philosophy of EnergyPlus development is important, but it does not guarantee that the code produced by the developer will meet the goals of the project. In order to increase the probability of success, individual developers in conjunction with other team members should use the following detailed software development plan. The intention of this section is not to impose bureaucracy on the developer but to provide methods for handling difficult situations and resolving issues related to other sections of the code.
It may not be necessary or possible to follow all of these steps for each coding task in EnergyPlus. However, developers should consider these steps to help guide them through development of new features to the program. The following scenario may work best in an academic environment though a similar approach may work for others.
Problem/Enhancement Definition. A new feature to be added to EnergyPlus is identified. This can be done formally during a meeting during the discussion of programming topics or it can be done informally when a problem is recognized in a portion of the EnergyPlus code. (Note - there is a template that should be used to document potential new features.)
Team Assembly. Once the project has been defined, primary responsibility for completion of the task must be assigned to one member of the development team. In addition, the primary developer will assemble a team of two other developers to provide project support. One of these should be a developer who has projects that may be interrelated. For example, a coil project should include a central plant expert as an assistant. The other assistant can be selected from any of the remaining development personnel. The assisting team will provide support for the primary developer and will be responsible for checking that all of the software development procedures have been followed.
Planning Stage. The primary developer will make a preliminary investigation and create a plan for all aspects of the development task. This phase must include tracking down any references necessary to complete the project and gather (and becoming familiar with) any legacy code which is available. The primary developer will define the inputs and outputs of the new model (variables and also file input/output issues) during this phase, summarize any record keeping which might be needed, and determine how the module will interact with surrounding programming components. The documents required by this phase will consist of electronic documents which include as a minimum a discussion of the proposed feature, legacy versions or sources for the new feature, a testing plan including data available for verification of the module, system/equipment diagrams, pseudo-code which describes the logic and structure of the modules, the proposed addition or changes to the IDD, the proposed IDF structure, and the variable naming, and output variables that will be added. Note that this document will serve as a starting point for the required additions to Engineering Reference and Input Output Reference, and other documents in step 7 below.
Preliminary Review. The primary developer will present the plan to the team. Exact procedures may be different from group to group. The core of the requirement is this: you must develop a plan, review it with the team, revise, develop initial code and documentation, review/debug, final implementation, review, and documentation.
Initial Programming and Documentation Phase. The primary developer will begin by constructing a skeleton of the new module and programming the interactions with the other modules. The programmer should not yet begin work on the detailed calculations of the module. The resulting skeleton should include all of the comments required by the code template presented in an earlier section. In addition, the primary developer should prepare a draft of the engineering documents.
Initial Code Review. The primary developer will present the results of the preceding phase to the assisting team. They will check to make sure that the developer has stuck to the preliminary plan or can provide justification for changing the plan. Furthermore, they will comment on the draft engineering documents and suggest structure or content changes/additions. Again, if serious problems are uncovered during this review, it may be necessary to return to previous stages of the development process.
Detailed Programming and Documentation Phase. At this point, the primary developer should incorporate the details of the module including any calculations, input/output issues, record keeping, etc. that are necessary. During this phase, the programmer should also complete program documentation and construct a testing plan as the various portions of the module are developed. Documentation tasks include completing in-line comments in the source code and filling in the details of the engineering and interface developers documentation. The testing plan should address both unit testing (ranges of parameters to investigate, etc.) and interaction testing.
Code Review Phase. The assisting team should perform a code walkthrough with the primary developer to insure that the code will perform the desired tasks and conforms to the established EnergyPlus standard. Additionally, the team will discuss and revise, if necessary, the documentation changes and testing plan. Concerns about coding, documentation, or testing strategies should be addressed at this point before continuing with the testing plan.
Testing Phase. The primary developer proceeds with the testing plan documenting the results of the testing plan and modifying the code as needed. The user documentation is also drafted during this phase. Documentation requirements (including format) are discussed in the Guide for Module Developers.
Testing and Documentation Review. One or both of the assisting team members review the testing results and resultant documentation changes. Suggestions for further testing or changes are made, if necessary. Testing requirements, too, are covered in the Guide for Module Developers.
Project Completion Phase. After successful completion of the testing and documentation review, the primary developer is responsible for integrating the changes for this project into the current version of EnergyPlus using the version control system, final testing of the new version of EnergyPlus to insure that the integration was successful, and integration of the various model documents into the EnergyPlus documentation repository. This must include at least one example input file which exercises all the features of the new code. Any problems encountered during this phase should be brought to the attention of the EnergyPlus system integrator.
Final Review. The notified assisting member confirms that the code and documentation has been integrated properly and that the integration of the code into EnergyPlus has not introduced any errors into EnergyPlus or the new module.
EnergyPlus development: step by step[LINK]
Understanding the general philosophy of EnergyPlus development is important, but it does not guarantee that the code produced by the developer will meet the goals of the project. In order to increase the probability of success, individual developers in conjunction with other team members should use the following detailed software development plan. The intention of this section is not to impose bureaucracy on the developer but to provide methods for handling difficult situations and resolving issues related to other sections of the code.
It may not be necessary or possible to follow all of these steps for each coding task in EnergyPlus. However, developers should consider these steps to help guide them through development of new features to the program. The following scenario may work best in an academic environment though a similar approach may work for others.
Problem/Enhancement Definition. A new feature to be added to EnergyPlus is identified. This can be done formally during a meeting during the discussion of programming topics or it can be done informally when a problem is recognized in a portion of the EnergyPlus code. (Note - there is a template that should be used to document potential new features.)
Team Assembly. Once the project has been defined, primary responsibility for completion of the task must be assigned to one member of the development team. In addition, the primary developer will assemble a team of two other developers to provide project support. One of these should be a developer who has projects that may be interrelated. For example, a coil project should include a central plant expert as an assistant. The other assistant can be selected from any of the remaining development personnel. The assisting team will provide support for the primary developer and will be responsible for checking that all of the software development procedures have been followed.
Planning Stage. The primary developer will make a preliminary investigation and create a plan for all aspects of the development task. This phase must include tracking down any references necessary to complete the project and gather (and becoming familiar with) any legacy code which is available. The primary developer will define the inputs and outputs of the new model (variables and also file input/output issues) during this phase, summarize any record keeping which might be needed, and determine how the module will interact with surrounding programming components. The documents required by this phase will consist of electronic documents which include as a minimum a discussion of the proposed feature, legacy versions or sources for the new feature, a testing plan including data available for verification of the module, system/equipment diagrams, pseudo-code which describes the logic and structure of the modules, the proposed addition or changes to the IDD, the proposed IDF structure, and the variable naming, and output variables that will be added. Note that this document will serve as a starting point for the required additions to Engineering Reference and Input Output Reference, and other documents in step 7 below.
Preliminary Review. The primary developer will present the plan to the team. Exact procedures may be different from group to group. The core of the requirement is this: you must develop a plan, review it with the team, revise, develop initial code and documentation, review/debug, final implementation, review, and documentation.
Initial Programming and Documentation Phase. The primary developer will begin by constructing a skeleton of the new module and programming the interactions with the other modules. The programmer should not yet begin work on the detailed calculations of the module. The resulting skeleton should include all of the comments required by the code template presented in an earlier section. In addition, the primary developer should prepare a draft of the engineering documents.
Initial Code Review. The primary developer will present the results of the preceding phase to the assisting team. They will check to make sure that the developer has stuck to the preliminary plan or can provide justification for changing the plan. Furthermore, they will comment on the draft engineering documents and suggest structure or content changes/additions. Again, if serious problems are uncovered during this review, it may be necessary to return to previous stages of the development process.
Detailed Programming and Documentation Phase. At this point, the primary developer should incorporate the details of the module including any calculations, input/output issues, record keeping, etc. that are necessary. During this phase, the programmer should also complete program documentation and construct a testing plan as the various portions of the module are developed. Documentation tasks include completing in-line comments in the source code and filling in the details of the engineering and interface developers documentation. The testing plan should address both unit testing (ranges of parameters to investigate, etc.) and interaction testing.
Code Review Phase. The assisting team should perform a code walkthrough with the primary developer to insure that the code will perform the desired tasks and conforms to the established EnergyPlus standard. Additionally, the team will discuss and revise, if necessary, the documentation changes and testing plan. Concerns about coding, documentation, or testing strategies should be addressed at this point before continuing with the testing plan.
Testing Phase. The primary developer proceeds with the testing plan documenting the results of the testing plan and modifying the code as needed. The user documentation is also drafted during this phase. Documentation requirements (including format) are discussed in the Guide for Module Developers.
Testing and Documentation Review. One or both of the assisting team members review the testing results and resultant documentation changes. Suggestions for further testing or changes are made, if necessary. Testing requirements, too, are covered in the Guide for Module Developers.
Project Completion Phase. After successful completion of the testing and documentation review, the primary developer is responsible for integrating the changes for this project into the current version of EnergyPlus using the version control system, final testing of the new version of EnergyPlus to insure that the integration was successful, and integration of the various model documents into the EnergyPlus documentation repository. This must include at least one example input file which exercises all the features of the new code. Any problems encountered during this phase should be brought to the attention of the EnergyPlus system integrator.
Final Review. The notified assisting member confirms that the code and documentation has been integrated properly and that the integration of the code into EnergyPlus has not introduced any errors into EnergyPlus or the new module.
Documentation content copyright © 1996-2014 The Board of Trustees of the University of Illinois and the Regents of the University of California through the Ernest Orlando Lawrence Berkeley National Laboratory. All rights reserved. EnergyPlus is a trademark of the US Department of Energy.
This documentation is made available under the EnergyPlus Open Source License v1.0.