Workplan and Project Goals

[cpritcha]

Goal

The goal of the OMF interoperability project is to be able to combine models written in different languages and environments with a low barrier to entry for model consumers.

Possible User Stories

Bob wants to couple two different models together. One is in Python (a rain routing model) and the other is in Fortran (a crop model). Bob wants to use the crop model as it was created as a command line program. This means Bob first has to figure out the format of any files consumed and produced by the crop model. Then he has to create a wrapper library to make the model easy to call.

Adison wants to couple two different models together. One is in Python (a rain routing model) and the other is in Fortran (a crop model). Adison is more comfortable with Fortran (and with the model itself) so she wants to build the portions of the application she is using as a library. This means Adison has to adapt portions of the application to make it possible to call directly from C, Python etc.

Acme Inc wants to make use of Adison's wrapped crop model in their project. They install the model and can now use it with their project. First they need to understand how the model works so experiment with the model in the REPL using a built in dataset and get documentation about the model's features. Then they integrate the model into their project.

Model Implementations

Model implementations are often implemented in compiled languages as libraries for executables (for C, C++, Fortran) and interpreted/JITed languages (R, Python, Julia, NetLogo). The challenges in creating model wrappers for these types of model implementations are outlined in this section.

Compiled Libraries

• local (in-process/subprocess) wrappers
  • may not need to serialize/deserialize requests if data structures are compatible
  • can be loaded dynamically as shared libraries / dynamic link libraries
  • probably doesn't require it's own container for dependency management since libraries are fairly self contained
  • a local wrapper will not allow multiple instances if the library global mutable state
• remote wrappers
  • deserialize requests and serialize requests
  • clients spawning a instance will need to able to know the model component api interface, be able make requests and deserialize responses. This will be made easier using an existing serialization library like Apache Arrow, Capn Proto or FlatBuffers.
  • probably won't require their own containers since remote models can be built fairly self contained (but may be needed to get around OS requirements in development)

Compiled Executables

• local (in-process/subprocess) wrappers
  • can call command line interface as subprocess. also need to be able to write input files and interpret output files
• remote wrappers
  • deserialize requests and serialize requests. also need to be able to write to somewhere that the executable can read from in a format the executable understand and interpret results produced by the executable into something to serialize.
  • clients spawning a instance will need to able to know the model component api interface, be able make requests and deserialize responses. This will be made easier using an existing serialization library like Apache Arrow, Capn Proto or FlatBuffers.

Interpreted

• local (in-process/subprocess) wrappers
  • depending on the programming language it is possible to make direct calls between them (for example for R to Python there is reticulate and for Python to R there is rpython).
  • setting up a container here is potentially more difficult because it requires unioning dependencies to form an image
• remote wrappers
  • same challenges as remote compiled libraries but much more likely to benefit from a container setup since dependency management for scripting language / JITs is more difficult

Model Metadata

In order to be able find models or know how to connect a model we need to have metadata about a particular model. Ideally this could be dynamic so that when a model instance is created the instance can be queried to determine it's interface.

Work Plan / Roadmap

SimpleCrop / LandLab Example

What has already been done:

• [x] adapt simplecrop for use as a cli
• [x] adapt simplecrop for use in a library
• [x] adapt landlab overland flow for use in a library

What needs to be done (basics):

Short Term:

• [ ] finish wrapping cli interface using pymt interface
• [ ] finish wrapping library using pymt like interface
• [ ] create or make use of a spatial grid abstraction so that crop model can be easily setup and run on multiple sites
• [ ] write a generic data component to replace the weather and irrigation components
• [ ] create a Python wrapper for local and remote simulation creation and scheduling using PyMT
• [ ] add support for interpreted languages using PyO3 etcetera
• [ ] adapt r.watershed / r.terraflow for use in library as a landlab overland flow drop in
• [ ] containerize example models

Medium Term:

• [ ] write a basic metadata library to make it possible to create dynamically create instances
• [ ] write a basic Python wrapper to call the basic metadata library (look at mint project)
• [ ] documentation for libraries

Long Term:

• [ ] tooling to publish and install models
• [ ] create a library to reduce time needed to create local wrappers and simulators
• [ ] create a library to reduce time needed to create remote wrappers and simulators
• [ ] create a library to expose basic simulation interfaces
• [ ] allow model instance APIs to depend on configuration

[cmbarton]

I would add to the goals section: 'with minimal or no coding changes needed in the original model(s)'

[willu47]

Similar (maintained and ongoing) project for coupling of simulation models: https://openresearchsoftware.metajnl.com/articles/10.5334/jors.265/

Source code: https://github.com/nismod/smif

Main application: https://github.com/nismod/nismod2

Recommend looking at https://www.dafni.ac.uk/ as well

[cpritcha]

Thanks @willu47! smif has a lot of overlap. I'll take a look at the docs and paper in more depth and see what questions I have.

[alee]

https://frictionlessdata.io/

https://snakemake.readthedocs.io/en/stable/

https://docs.secure.dafni.rl.ac.uk/docs/how-to/models/how-to-create-a-dafni-ready-model/

[cmbarton]

I would add to the goals section: 'with minimal or no coding changes needed in the original model(s)'

Nothing in the work plan about the hydrology models. That is the other half of the project

[alee]

I think @cpritcha called this the rain routing model in the user story section (which may need some additional refinement :sweat_smile:)

I would add to the goals section: 'with minimal or no coding changes needed in the original model(s)'

Nothing in the work plan about the hydrology models. That is the other half of the project

[cmbarton]

I think @cpritcha called this the rain routing model in the user story section (which may need some additional refinement 😅)

I would add to the goals section: 'with minimal or no coding changes needed in the original model(s)'

Nothing in the work plan about the hydrology models. That is the other half of the project

Nothing in the section entitled "Work Plan / Roadmap" about the hydrology model part