FINAM v1.0

[MuellerSeb]

The first stable release of FINAM: Version 1.0 🎉

FINAM is an open-source component-based model coupling framework for environmental models.
It aims at enabling bi-directional online couplings of models for different compartments like geo-, hydro-, pedo- and biosphere.

The framework is built in Python, with well-defined interfaces for data exchange.
This approach allows for coupling of models irrespective of their internal structure, architecture or programming language.

Resources

• FINAM homepage
• FINAM documentation
• FINAM source code
• FINAM GitLab group, containing further related projects

Changelog

Breaking changes

• submodule modules renamed to components for consistency (!289)
• argument modules renamed to components in Composition for consistency (!289)
• Components now implement _next_time instead of the property next_time for consistency (!283)
• All fields of Composition are now private (!273)
• Input.source is private, Input.get_source() becomes property Input.source, Input.set_source becomes a getter (!273)
• Output.targets is private, Output.get_targets() becomes property Output.targets (!273)
• Composition metadata was restructured to hold components and adapters in separate sub-dictionaries (!274)
• Time components implement method _next_time instead of property next_time (!283)
• Info now has properties for grid, time and mask (!286)
• all init-args of Info are now optional (!286)
• Info.accepts has changed signature: renamed ignore_none to incoming_donwstream (!286)
• Info.accepts now only checks: grid, mask and units (other meta data can differ) (!286)
• Grid.to_/from_canonical now allows additional dimensions (!286)
• data_shape now a property of GridBase (!286)
  • NoGrid can be initialized with dim or data_shape now
  • NoGrid.data_shape can have -1 entries for variable size dimensions
  • if only dim given to NoGrid, all entries in data_shape will be -1

Features

• Components and adapters automatically provide default metadata that can be extended by implementations (!274, !276)
• Grid class now have attributes providing connectivity information for the contained cells (!275)
  • cells_connectivity: connectivity array as used by ESMF and VTK
  • cells_definition: cell definition as used by PyVista and legacy VTK
  • cells_offset: location of the start of each cell in cells_connectivity
• added convenience functions and constants to grid_tools (!275)
  • get_cells_matrix: convert cells_connectivity or cells_definition back to the default cells matrix used in the Grid class (can be used to convert VTK-grids into FINAM-grids)
  • INV_VTK_TYPE_MAP: inverse mapping to VTK_TYPE_MAP - FINAM cell type to VTK cell type
  • VTK_CELL_DIM: parametric dimension for each VTK cell type
• Grid class now reusable when having different data locations and better grid type casting (!278)
  • added copy method to grids with optional argument deep (False by default) to create a copy of a grid
  • added setter for data_location in order to set a new data location (e.g. after copying a grid)
  • added class attribute valid_locations in order to check the set data location (esri-grid only supports cells, unstructured-points only support points)
  • added missing casting methods to convert esri to uniform and uniform to rectilinear (when you want to use point data on an esri-grid, you can cast it to uniform first)
  • added axes_attributes also to unstructured grids
• Grid method compatible_with now has a check_location argument to optionally check data location (!280)
• added Mask enum with two options: (!286)
  • Mask.FLEX for flexible masking
  • Mask.NONE to explicitly use plain numpy arrays
• added mask attribute and init-arg to Info : can be a Mask value or a valid mask for numpy.ma.MaskedArray (!286)
• data.tools.prepare now applies masks to data if set in Info object (!286)
• ARegridding now has a out_mask arg (!286)
• RegridNearest and RegridLinear now support explicitly masked data (input doesn't have Mask.FLEX) (!286)
• adapters now have an in_info property (!286)

Bug fixes

• cells for structured grids in 3D are now created correctly (no negative Volume in VTK/ESMF) (!286)
• cf_units.py was broken for pint>=0.24 (!282)

Documentation

• Minor fixes in documentation examples and links (!272)
• Adds a book section on composition, component and adapter metadata (!274)

---

This discussion was created from the release FINAM v1.0.