README
¶
Catchment Resilience Exploration Modeller (CREM)
Overview:
This repository produces two key applications:
- The CREMExplorer
- The CREMEngine
Both applications are configured via TOML files, based on a 'convention over configuration' approach.
CREMExplorer:
The CREMExplorer is a highly configurable modelling platform that wraps a river catchment model in either a single or multi-objective simulated annealer to explore stakeholder objectives around river catchment resilience.
The river catchment model tracks the following stakeholder objectives:
- Sediment Produced
- Particulate Nitrogen Produced
- Dissolved Nitrogen Produced
- Management Action Implementation Cost
- Management Action Opportunity Cost
This river catchment model allows management actions to be applied in order to mitigate pollutants entering a river system. The following management actions have been implemented:
- Riparian revegetation
- predominately targeting sediment and particulate nitrogen
- Gully Restoration
- predominately targeting sediment
- Hillslope revegetation
- predominately targeting sediment and particulate nitrogen
- Wetland establishment
- predominately targeting dissolved nitrogen
Single-objective simulated annealing is used to find optimised solutions to minimising/maximising a particular stakeholder objective, optionally limited by a 2nd objective. For instance, a scenario can be configured to answer a question like "Find a near-optimal minimised sediment producted for a budget of $10M in implementation costs."
Multi-objective simulated annealing is used to explore trade-offs between all the supplied stakeholder objectives, optionally limited by one of those objectives. For instance, a scenario can be configured to answer a question like "Find me a set of tradeoffs between Sediment and Dissolved Nitrogen produced for a budget of $10M in implementation costs"
CREMEngine:
The CREMEngine wraps the river catchment model described above in a web-server interface, allowing the following:
- The river catchment model can be deployed independent of the annealing, and manipulated it in real-time for visualiation purposes.
- Ability to configure the model to run exactly as per scenario definitions supplied to the CREMExplorer.
- Ability to set the model's state to match solutions produced by the CREMExplorer, to showcase optimised solutions, or individual tradeoff solutions of interest.
Getting Started:
CREM makes use of a number of 3rd-party libraries that are not included in this source repository. Go's built-in 3rd-party module support is used to track and integrate needed 3rd-party libraries. Once you've git-cloned this repository, run:
> cd <new CREM repository folder>
> go mod vendor
to download compatible versions of the libraries CREM depends on as vendor libraries.
From there a go build from
within cmd/cremexplorer should produce
a cremexplorer.exe executable. Then run your new executable from the command-line, specifying a scenario config file
like this:
> cremexplorer.exe --ScenarioFile <someScenarioFile>
You'll find a simple test scenario configuration here. Further detail on configuring a scenario can be found in the wiki.
General Usage Notes:
-
This software was constructed and tested on a 64-bit Windows 10 platform using GoLang 1.16.
-
Continuous integration via travis-ci is also employed.
Contact Information:
-
This software is produced on behalf of Griffith University within the Australian Rivers Institute, and originally authored by Dr Lindsay Bradford.
-
E-Mail: ari@griffith.edu.au, or l.bradford@griffith.edu.au
-
Voice: +61 7 3735 7402, or +61 7 3735 6598
Copyright:
The Catchment Resilience Exploration Modeller (CREM) software is licensed under a BSD 3-clause "New" or "Revised" licence, detailed in LICENCE.md.
Dependencies:
The following 3rd-party libraries are required for this code-base:
- Gomega for a Fluent-API based approach to test assertions
- go-ole for I/O via Excel files
- BurntSushi/toml for TOML config file support
- pkg/errors For error wrapping
- nu7hatch/gouuid for UUID generation
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
internal
|
|
|
pkg/annealing/observer
observer package contains Reporting implementations that capture annealing events and log them to various destinations in potentially very different formats (as dictated by loggers passed to a logger at build-time)
|
observer package contains Reporting implementations that capture annealing events and log them to various destinations in potentially very different formats (as dictated by loggers passed to a logger at build-time) |
|
pkg/annealing/observer/filters
modulators package supplies a number of observer modulators for managing the chattiness of loggers.
|
modulators package supplies a number of observer modulators for managing the chattiness of loggers. |
|
pkg/model/action
action package contains interfaces and behaviour for general-purpose "management actions" that change a model's decision variables based on their activation status.
|
action package contains interfaces and behaviour for general-purpose "management actions" that change a model's decision variables based on their activation status. |
|
pkg/model/variable
Variable package supplies generalised model variables that allow watchers of models to make decisions on those models by reacting the changes in model decision variables.
|
Variable package supplies generalised model variables that allow watchers of models to make decisions on those models by reacting the changes in model decision variables. |
|
pkg
|
|
|
archive
Package archive offers support for the compact storage and retrieval of state in memory.
|
Package archive offers support for the compact storage and retrieval of state in memory. |
|
attributes
Attribs package offers up a flexible approach to attaching Attribs that then be used to avoid the brittle parameter problem.
|
Attribs package offers up a flexible approach to attaching Attribs that then be used to avoid the brittle parameter problem. |
|
errors
Package errors offers an extension of functionality to the default golang errors package.
|
Package errors offers an extension of functionality to the default golang errors package. |
|
logging
logging package defines loggers responsible for formatters log entries (delegated to Formatter) and delivering the formatted entries to whatever log destinations are needed.
|
logging package defines loggers responsible for formatters log entries (delegated to Formatter) and delivering the formatted entries to whatever log destinations are needed. |
|
logging/formatters
Package formatters defines observer formatters that take Attributes and convert them into observer-ready strings.
|
Package formatters defines observer formatters that take Attributes and convert them into observer-ready strings. |
|
name
name package offers a suite of interfaces and structs, allowing uniform naming/identification of entities.
|
name package offers a suite of interfaces and structs, allowing uniform naming/identification of entities. |
|
strings
Package strings offers an extension of functionality to the default golang strings package.
|
Package strings offers an extension of functionality to the default golang strings package. |
|
threading
threading supplies support in terms of forcing functions to run on the OS thread via a bound main goroutine (some behaviour, like OLE function invocations, demand this).
|
threading supplies support in terms of forcing functions to run on the OS thread via a bound main goroutine (some behaviour, like OLE function invocations, demand this). |