How do I submit an improvement to APSIM?
APSIM is under continual development. If you have found a defect in APSIM or would like to see a new feature implemented or are about to commence on some APSIM development then you can create a GitHub issue at one of these two repositories:
Any Improvements to APSIM are required to be unencumbered and the contributing party warrants that the IP being contributed does not and will not infringe any third party IPR rights. This is a requirement of the Non-Commercial R&D Licence as agreed to as part of the download of the APSIM software.
Indicating an intention to develop an improvement to APSIM
It can be useful to notify the APSIM Initiative that you are planning on making an improvement to APSIM. This can often lead to others suggesting ideas or collaborators to work with.
- To do this you need to: Create an issue in GitHub with a description of what you intend doing. This is for APSIM 7.x and APSIM Next Generation.
- When creating an issue, please note that the opening text should provide a Concept Note for the issue – a brief summary the anticipated work. It should include the following:
- What is being developed
- What’s it based on (ie what models, journal articles etc..)
- What data/datasets will be used?
- Comments on how sub-issues will be dealt with
- Any impact the development will have on other models
- Key contributors
- It’s very likely that the issue will become an item in the AI development plan.
For APSIM 7.x
All improvements to APSIM 7.x should be emailed to email@example.com.
For enhancements to existing models, provide:
- All files modified (e.g. source code, xml).
- A description of the modification / enhancement.
- Test simulations, with graphs, that show the enhancement works.
- If appropriate given the nature of the improvement, an example .apsim file that users can use to easily understand how to use the new feature.
For new APSIM models, provide:
- All files modified (e.g. source code, xml).
- Clear, precise documentation in Microsoft Word format that describes the new model. It will need validation / sensibility graphs and a bibliography.
- Simulation files (.apsim) that contain validation and sensibility simulations, with graphs, that show the new model works as expected.
- An example .apsim file that users can use to easily create a new simulation as a starting point to using your new model.
For APSIM Next Generation
- Create a GitHub issue with a description of the improvement.
- Commit, push and raise pull requests on GitHub for all modified files (https://apsimnextgeneration.netlify.com/development/contribute/).
- Once the issue is ready for review, add a ‘ready for review’ label on the issue. The Reference Panel will then assign a reviewer for the improvement.
For enhancements to existing models, commit files to GitHub that show test simulations, with graphs, showing that the enhancement works.
For new models:
- Your new model should be an .apsimx file (e.g. wheat.apsimx), that is committed and pushed to the prototypes directory in GitHub. It should contain validation and sensibility simulations, with graphs, that show the new model works as expected.
- An example .apsimx file that users can use to easily create a new simulation as a starting point to using your new model. This should be in the same folder as your main validation file.
- All documentation is auto-generated. Give your .apsimx file the same name as your model e.g. wheat.apsimx. To generate the documentation for the model, run the user interface, right click on the top level ‘Simulations’ node and select ‘Create documentation’. This will go through your .apsimx file extracting memos and graphs, producing a .pdf file. The reviewer will generate the documentation and review it so ensure that it is formatted correctly and contains the relevant information.
What the reviewer will be looking for
The Reviewer/s will be reviewing and assessing the following:
- Quality of the science.
- Quality of the software.
- Whether the new model / improvement is sufficiently referenced.
- Validation through simulations and graphs. This might involve (i) simulations of crop and/or soil state over time showing simulation trace through time series of data including error bars on observed data, and (ii) comparisons of observed vs. predicted for a range of variables across data sets showing appropriate regression statistics.
- Sensibility tests. As detailed test data sets are often limited in their range (genetic (G), management (M), and environment (E)), simulations to demonstrate prediction generality of the proposed change (i.e. sensibility analysis/plausibility) should be submitted. This might include simulations across a range of G, M, E factors to demonstrate the capacity of the change proposal to simulate anticipated or known response.
- The quality of the example simulation.
- Awareness of existing approaches and underpinning science via reference to existing literature and model