Finam packages/structure

Proposal, derived from the discussion on Oct. 14, 2021. See backlog item management#56.

Guideline proposal

Core package

Repository: finam

• Contains only:

  • framework interfaces and their (abstract) general-purpose implementations
  • framework driver(s) (i.e. scheduling of models)
  • Basic MPI management (distribute nodes/communicators to components/models)

• Does not contain:

  • any components (like models, IO, ...)
  • any adapters

Should be installable as a Python package using pip.

Commonly used components and adapters

Repository: finam-tools

• Contains generic components and adapters with are commonly used in a wide range of coupling scenarios
• Component examples:
  • File I/O (e.g. NetCDF, CSV, ...)
  • Generic live visualizations (e.g. time series plots)
• Adapter examples
  • Temporal interpolation and integration
  • Raster resampling
  • Geographic re-projection

Should be installable as a Python package using pip.

Other components and adapters

Components and adapters that are not of high generality are placed into separate repositories. This can be one repository per component/adapter, or collections of related components and/or adapters

Individual components, adapters or collections should be installable using pip.

Models, bindings and wrappers

A model prepared for use in Finam can be seen as three layers:

• The model itself
• Python bindings
• Finam interface implementations

Model owners/developers are free to decide whether to put these layers into the model repository, or to separate them.

The wrapped model should be installable using pip in one go. I.e. pip install mhm-finam should install all three layers.

Coupling setups

A coupling setup is a Python script that assembles components (models) and adapters into a coupling setup and runs it using the Finam driver.

Coupling setups are highly use-case specific. Thus, from the perspective of Finam development, no guidelines are required here. We could, however, create a repository with examples / demo setups.

However, LandTrans can be seen as one (or a sub-set) of the possible coupling use cases. Therefore, further discussion on sharing and re-using coupling setups may be necessary.

Dependencies

Arrows denote imports. I.e. they point from the imported package to the importing package.

graph TD
  finam[Finam core]
  finam-tools[Finam tools]
  setup[Coupling setup script]
  other-comps[Other components/adapters]
  
  subgraph model[Wrapped model]
    model-core[Model core]
    py-bindings[Python bindings]
    finam-impl[Finam interface impl.]
    
    model-core --> py-bindings
    py-bindings  --> finam-impl
  end
  
  finam --> finam-tools
  finam --> other-comps
  finam --> finam-impl
  finam --> setup
  
  finam-impl --> setup
  finam-tools -.-> setup
  other-comps -.-> setup

Next steps

• Move this guide to document CONTRIBUTING.md
• Create GitLab group finam
• Move prototype to group finam and rename it to finam/finam
• Move code not related to the finam core package to separate repositories or to models
• Make finam installable as package voa pip