bmi-example-cxx

An example of implementing the C++ bindings for the CSDMS Basic Model Interface (BMI).

Overview

This is an example of implementing a BMI for a simple model that solves the diffusion equation on a uniform rectangular plate with Dirichlet boundary conditions. The model and its BMI are written in C++. Tests of the BMI are provided.

This repository is organized with the following directories:

heat

Holds the model, the BMI for the model, and a sample main program

testing

Tests that cover the BMI of the model

Build/Install

This example can be built on Linux, macOS, and Windows.

Prerequisites:

• A C++ compiler
• CMake
• pkg-config
• The C++ BMI bindings. Follow the build and install directions given in the README in that repository. You can choose to install them from source or through a conda binary.

Linux and macOS

To build and install this example from source with cmake, using the current C++ BMI version, run

mkdir _build && cd _build
export PKG_CONFIG_PATH=<path-to-installation>  # optional: only needed for non-standard install location
cmake .. -DCMAKE_INSTALL_PREFIX=<path-to-installation>
make
make install

where <path-to-installation> is the base directory in which the C++ BMI bindings have been installed (/usr/local is the default). When installing into a conda environment, use the $CONDA_PREFIX environment variable.

The installation will look like (on macOS, using v2.0 of the BMI specification):

.
|-- bin
|   `-- run_bmiheatcxx
|-- include
|   |-- bmi.hxx
|   |-- heat.hxx
|   `-- bmi_heat.hxx
`-- lib
    |-- libbmiheatcxx.dylib
    |-- libheatcxx.dylib
    `-- pkgconfig
        |-- bmicxx.pc
        |-- heatcxx.pc
        `-- bmiheatcxx.pc

4 directories, 9 files

From the build directory, run unit tests on the sample implementation with

ctest

Windows

An additional prerequisite is needed for Windows:

• Microsoft Visual Studio 2017 or Microsoft Build Tools for Visual Studio 2017

To configure this example from source with cmake using the current C++ BMI version, run the following in a Developer Command Prompt

mkdir _build && cd _build
set "PKG_CONFIG_PATH=<path-to-installation>"  &:: optional: only needed for non-standard install location
cmake .. ^
  -G "NMake Makefiles" ^
  -DCMAKE_INSTALL_PREFIX=<path-to-installation> ^
  -DCMAKE_BUILD_TYPE=Release

where <path-to-installation> is the base directory in which the C++ BMI bindings have been installed. The default is "C:\Program Files (x86)". Note that quotes and an absolute path are needed. When using a conda environment, use "%CONDA_PREFIX%\Library".

Then, to build and install:

cmake --build . --target install --config Release

From the build directory, run unit tests on the sample implementation with

ctest

Use

Run the heat model through its BMI with the run_bmiheatcxx program, which takes a model configuration file (see the testing directory for a sample) as a required parameter. If run_bmiheatcxx is in your path, run it with

run_bmiheatcxx config.txt

Output from the model is written to the file bmiheatcxx.out in the current directory.