Practice Note: Model Management

This practice note is part of a set developed to provide consistency and transparency of river system models used within the Murray–Darling Basin. The complete set of practice notes covers modelling practices, such as naming conventions for folder structures, and model methods, such as flow routing and residual inflow estimation. The practice notes have been developed through a collaboration between the MDBA and Basin States.

This practice note, Model Management, describes the general principles that should be applied when deciding how to store models so organisations can easily reproduce results from different models and different scenario runs. It should be noted that storing scenarios can be complicated and may require some additional thinking about the options available to the modeller.  

Background

Models are constantly being changed and improved. When the model configuration, model inputs or the underlying application are altered, there will be changes to model results. As results from model runs are supplied to stakeholders and are used in decision-making, it is important to be able to quickly identify exactly what caused a difference in results or to be able to reproduce results from particular model runs. Good model management allows you to specify the exact configuration, inputs and code used to generate a set of model results. Model Management is key to reproducing the same results later or identifying the reasons for changes in results from subsequent model runs. 

Good model management is essential to track development changes and ensure that model results are reproducible. A good version control system aids in model management and provides a complete history of all the changes made to the model or model inputs.  The version control system will record:

• who made the change
• the date of the change
• any written notes related to the change (what the change involved, why it was done)
• links to other documentation

This information lets you understand what has changed between model versions and replicate results from a particular model run when required.

For more information on version control, see: https://www.atlassian.com/git/tutorials/what-is-version-control

This note aims to guide model management for the water resource management models being developed using eWater Source for the Murray Darling Basin. However, the general principles below can be applied to any modelling platform. 

General principles

1. Model developers may store the models used to underpin water management decisions in a version-controlled model repository.
2. It is recommended that the structure of the repository is easy for others to understand.
3. The repository structure may break the model into components (e.g. Inputs, Models, Plugins etc.)
4. The protocol within your organisation may need to define the process for committing files to the repository. It may include:
   1. advice on when the model should be committed 
   2. a description of the checks that should be undertaken before the model is committed
   3. Any additional files that should be included with the commit.  
5. A similar repository structure is recommended where organisations or multiple organisations have a large number of models being developed using the same modelling platform (or that may need to be linked together during larger model runs). 
6. Meaningful comments can be added to each commit to the repository, so future users understand the differences in the model code, model configuration, or model inputs from the previous version. 

Suggested Methods for eWater Source Models Management

As these practice notes relate primarily to the development of Source Models, the suggested approach relates specifically to the storage of eWater Source Models. A link to the eWater suggested method can be found here:  /wiki/spaces/SD510/pages/54592056

It is suggested that one repository is created per model. In some situations, it may be appropriate to have additional repositories for the same model. For example, in the Murray Darling Basin, each surface and groundwater model would have a repository maintained by the owners of the model. For example, the Murray-Darling Basin Authority (MDBA) would maintain a repository for the Source Murray Model, while the NSW Department of Planning and Environment (DPE) would maintain a repository for the Murrumbidgee Source Model, and the Victorian Department of Environment, Land, Water and Planning (DELWP) would maintain a repository for the Goulburn-Broken-Campaspe-Coliban-Loddon Source Model.

The typical file structure of these repositories may include the following folders or files shown in the table below. How these are arranged would be a decision of the organisation responsible for the repository.

Produced in collaboration with: