TESTS

Minimal BMI Compliance

To verify that a model is minimally compliant with BMI and can be run from DIMR or by the BasicModelInterfaceLibrary class in Delta Shell, it can be tested using the bmi-runner program. The program runs from a command prompt and takes two arguments: the name of the DLL containing the model, and a configuration file to be read by the model’s initialize() method. Here’s an example:

C:\Test> bmi-runner myModel myConfig.yaml

In response to this command, the bmi-runner program will try to load "myModel.dll" and run its initialize, update, and finalize functions.

A copy of the bmi-runner executable has been uploaded to the Test directory in this repository. This is compiled as a 64-bit Windows exe, so it needs to be run in a 64-bit Windows system, and the DLL needs to be compiled to run in a 64-bit environment.

Functions Tested

The bmi-runner program tests the BMI initialize(), update(), and finalize() functions with direct calls, but in order to stop and start the update() loop, it requires the time control functions get_start_time(), get_end_time(), get_current_time(), and get_time_step(). Bmi-runner also triggers a call to the set_logger() function, but a stub implementation that returns nothing is adequate to satisfy the test programs requirement.

In the example shown above, the initialize() function will be called with the file name "myConfig.yaml" as its argument, and the update() function will be called repeatedly with -1.0 as its argument. In the OpenEarth version of BMI, using -1.0 as an argument for the update() function advances the program one time step, with the time step having the value given by the get_time_step() function.

The needed functions have the following definitions in the bmi.h header file:

/* control functions. These return an error code. */
BMI_API int initialize(const char *config_file);

BMI_API int update(double dt);

BMI_API int finalize();

/* time control functions */
BMI_API void get_start_time(double *t);

BMI_API void get_end_time(double *t);

BMI_API void get_current_time(double *t);

BMI_API void get_time_step(double *dt);

/* set logger by setting a pointer to the log function */
BMI_API void set_logger(Logger logger);

Testing with bmi-runner is an important initial step toward validating a model’s operability in the interoperable models system. Stated in negative terms, if a model does not run through bmi-runner, it cannot possibly run under a DIMR configuration. If, on the other hand, the model (including C or C++ wrappers) can be run through bmi-runner, several important steps toward full BMI compliance have been navigated successfully.