Individually as scientists and comparatively as research institute we have the responsibility to carry out research according to scientific standards and in compliance with the regulations of our donors. Benefits of a good documentation of SimComponents and model solutions are:
•Remember / retrace changes which have been carried out in the past
•Facilitate exchange of solutions/SimComponents with others
1. Documentation and quality assurance of SimComponents
SimComponents must contain:
- Variable name
- Unit ontology link
- Variable description
- Min-Value, Max-Value, Default Value
- Data Type (DOUBLE, DATE, CHAR, BOOLEAN etc.)
- Use Type (constant, input, output, state, rate)
- Headers with detailed explanations
- Documentation of equations (citations, use cases etc.)
- Test data sets (link) and unit test case
- Description of the relation to other SimComponents
All the information must be written into the header of a SimComponent or into the descriptions of the variables.
Quality Levels of SimComponents
2. Documentation of Solutions
It is desirable that all solutions/projects have a proper documentation. Minimally, each solution which has produced results which are either:
published or have been delivered to third parties.
MUST be documented according to the following quality assurance criteria.
Solution files must contain:
•Header:
- Author, Title and optionally author url, for which production situation / management conditions (crop, management intensity)
- Applied at which environmental conditions (Climate, Soil)
- Where have results been published?
- Who checked the solution? At which quality level was it registered?
- Short simulation protocol which summarizes the names of the resource files (data, parameter files) and the version number of the SVN directory where all solution and input files have been committed to
- In which projects the solution has been used
- Disclaimer
•Explanation of resources
- Data sources (owners, citations, where archived?) In case data are archived outside SVN they must be linked with absolute path. It is recommended to archive large data which have been used for publications at: \\simplace.net\archive
- Parameters sources (citations, modifications, deviation from default values, where archived?)
- Additional resources from external tools (e.g. project files, R-scripts) which are necessary to reproduce the results obtained with the solution
•SimComponents – documented in the SimComponent class (.java) with the version number of the respective SVN directory
All the information must be written into the header of a solution and into the description of the resources/data.
3. Documentation of projects
Project files must contain:
- Author, Title and optionally author url
- Which solution was used with this project
- In case of complex pre-processing of input data or post-processing of output data, a separate READ ME file should be prepared and committed to the MISC directory in your “SVN\Simplacerun” folder together with the project file
All the information must be written into the header of a project file.
Quality Levels of Solutions/Projects
4. Tools to facilitate the documentation and retrieval of solutions/projects and data
In order to assure quality of documentation and reproducibility of simulation experiments, the institute provides a versioning system supported by a SVN server.
All simulation experiments which produced results that
- have been published
- have been handed over to third parties
MUST be documented on the SVN server using the versioning system of the institute. Therefore, all development and simulation activities must be carried out on the SVN server and changes must be committed regularly.