RFC 0.96

jornbr edited this page May 27, 2018 · 16 revisions

[this RFC is under development and subject to change; please do not comment on it until announced on fabm-devel]

Request For Comments: FABM API 0.96

This is the first update in preparation for the 1.0 release of FABM. It includes changes to FABM's host API, that is, the set of interfaces that link FABM and its host (typically a hydrodynamic model). These changes are designed to simplify the API, eliminate inconsistencies, and at the same time make the API more powerful. The FABM couplers developed for most hydrodynamic models will require small changes to become compatible with FABM 0.96. As the 0.96 update does not change FABM's biogeochemical API, biogeochemical models included in/linked to FABM do not require any change at this time.

Renamed public methods and types

To ensure that use fabm does not import names that might already exist in the host namespace, all public FABM types are prefixed with type_fabm_, just like public methods are prefixed with fabm_. Additional name changes are implemented for consistency (type_bulk_variable_id) and simplicity (type_external_variable, type_horizontal_state_variable_info).

Old name New name
type_model type_fabm_model
type_external_variable type_fabm_variable
type_horizontal_state_variable_info type_fabm_horizontal_state_variable
type_bulk_variable_id type_fabm_interior_variable_id
type_horizontal_variable_id type_fabm_horizontal_variable_id
type_scalar_variable_id type_fabm_scalar_variable_id

Model creation

To improve the performance of object-oriented access to a FABM model, it needs to be declared as class pointer, for instance:

class (type_fabm_model), pointer :: model

At the same time, the name and syntax of the model creation function is changed from

call fabm_create_model_from_yaml_file(model, ...)

to

model => fabm_create_model(...)

Access API methods through the model object

As soon as the model object is created (by calling fabm_create_model), access to FABM APIs should happen by calling methods associated with the model object. Typically, this means that calls such as call fabm_set_domain(model, ...) need to be replaced by call model%set_domain(model, ...).

Old syntax New syntax
fabm_initialize(model, ...) model%initialize(...)
fabm_set_domain(model, ...) model%set_domain(...)
fabm_check_ready(model, ...) model%start(...)
fabm_initialize_state(model, ...) model%initialize_interior_state(...)
fabm_initialize_surface_state(model, ...) model%initialize_surface_state(...)
fabm_initialize_bottom_state(model, ...) model%initialize_bottom_state(...)
fabm_do(model, ...) model%get_interior_sources(...)
fabm_do_surface(model, ...) model%get_surface_sources(...)
fabm_do_bottom(model, ...) model%get_bottom_sources(...)
fabm_get_vertical_movement(model, ...) model%get_vertical_movement(...)
fabm_check_state(model, ...) model%check_interior_state(...)
fabm_check_surface_state(model, ...) model%check_surface_state(...)
fabm_check_bottom_state(model, ...) model%check_bottom_state(...)
fabm_get_conserved_quantities(model, ...) model%get_interior_conserved_quantities(...)
fabm_get_horizontal_conserved_quantities(model, ...) model%get_horizontal_conserved_quantities(...)

The following are removed altogether:

fabm_get_light_extinction fabm_get_albedo fabm_get_drag fabm_get_light

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.