The Babelizer

The Babelizer: language interoperability for model coupling in the geosciences - Published in JOSS (2022)

https://github.com/csdms/babelizer

Keywords

Scientific Fields

Repository

Transform BMI-wrapped models into Python packages

README.rst

.. image:: https://joss.theoj.org/papers/10.21105/joss.03344/status.svg
    :target: https://doi.org/10.21105/joss.03344

.. image:: https://github.com/csdms/babelizer/workflows/Build/Test%20CI/badge.svg
    :target: https://github.com/csdms/babelizer/actions?query=workflow%3A%22Build%2FTest+CI%22

.. image:: https://anaconda.org/conda-forge/babelizer/badges/version.svg
    :target: https://anaconda.org/conda-forge/babelizer

.. image:: https://readthedocs.org/projects/babelizer/badge/?version=latest
        :target: https://babelizer.readthedocs.io/en/latest/?badge=latest
        :alt: Documentation Status

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
        :target: https://github.com/csdms/babelizer

.. image:: https://coveralls.io/repos/github/csdms/babelizer/badge.svg?branch=develop
    :target: https://coveralls.io/github/csdms/babelizer?branch=develop


The Babelizer: Wrap BMI libraries with Python bindings
======================================================


The *babelizer* is a utility for wrapping a library that exposes a `Basic Model Interface`_ (BMI) so that it can be
imported as a Python package.

Supported languages include:

*  C
*  C++
*  Fortran
*  Python


The Babelizer is part of the CSDMS Workbench
--------------------------------------------

The *babelizer* is an element of the `CSDMS Workbench`_,
an integrated system of software tools, technologies, and standards
for building and coupling models. The Workbench provides two Python
frameworks for model coupling, *pymt* and *landlab*.
The *babelizer* was written to bring models written in other languages into
these frameworks.
However, as long as your model
satisfies the requirements below, you can use the *babelizer*
to bring your model into Python without having to use any of the
other tools in the Workbench.


Should I use the babelizer?
---------------------------

To determine if the
*babelizer* is right for you, first be aware of a few requirements.

1. Your model must be written in C, C++, Fortran, or Python
2. Your model must provide a shared library
3. Your model must expose a `Basic Model Interface`_ through this library

The most difficult of the three requirements is the last--implementing a BMI. This
involves adding a series of functions with prescribed names,
arguments, and return values for querying and controlling your model. We have created
several resources to help you understand the BMI and to guide you
through the implementation process.

BMI resources
^^^^^^^^^^^^^

* The `Basic Model Interface`_ documentation provides an overview of the BMI as well
  as a detailed description of all of the BMI functions.
* The following provide a BMI specification for each of the supported languages:

  * `C spec `_
  * `C++ spec `_
  * `Fortran spec `_
  * `Python spec `_

* The following give examples of a BMI implementation for each of the supported languages:

  * `C example `_
  * `C++ example `_
  * `Fortran example `_
  * `Python example `_

Note
^^^^

There are lots of other good reasons to create a BMI for
your model--not just so you can bring it into Python with the *babelizer*!
Read all about them in the `Basic Model Interface`_ documentation.


Requirements
------------

The *babelizer* requires Python >=3.10.


Apart from Python, the *babelizer* has a number of other requirements, all of which
can be obtained through either *pip* or *conda*, that will be automatically
installed when you install the *babelizer*.

To see a full listing of the requirements, have a look at the project's
*requirements.txt* file.

If you are a developer of the *babelizer* you will also want to install
additional dependencies for running the *babelizer*'s tests to make sure
that things are working as they should. These dependencies are listed
in *requirements-testing.txt*.


Installation
------------

To install the *babelizer*, first create a new environment.
Although this isn't strictly necessary, it
isolates the installation to avoid conflicts with your
base Python installation. This can be done with *conda*:

.. code:: bash

    $ conda create -n babelizer python=3
    $ conda activate babelizer

Stable Release
^^^^^^^^^^^^^^

The *babelizer* and its dependencies are best installed with *conda*:

.. code:: bash

    $ conda install babelizer -c conda-forge

From Source
^^^^^^^^^^^

After downloading the the *babelizer* source code, run the following from
*babelizer*'s top-level directory (the one that contains *setup.py*) to
install *babelizer* into the current environment:

.. code:: bash

    $ pip install -e .

or using *conda*:

.. code:: bash

    $ conda install --file=requirements.txt -c conda-forge


Input file
----------

The *babelizer* requires a single *toml*-formatted input file that describes
the library to wrap. This file is typically named *babel.toml*.
An example of a blank *babel.toml* file:

.. code:: toml

    [library]
    [library.""]
    language = "c"
    library = ""
    header = ""
    entry_point = ""

    [build]
    undef_macros = []
    define_macros = []
    libraries = []
    library_dirs = []
    include_dirs = []
    extra_compile_args = []

    [package]
    name = ""
    requirements = []

    [info]
    github_username = "pymt-lab"
    package_author = "csdms"
    package_author_email = "csdms@colorado.edu"
    package_license = "MIT"
    summary = ""

    [ci]
    python_version = ["3.9"]
    os = ["linux", "mac", "windows"]

You can generate *babel.toml* files using the *babelize generate* command.
For example, the above *babel.toml* was generated with:

.. code:: bash

  $ babelize generate > babel.toml

Library section
^^^^^^^^^^^^^^^

The *library* section specifies information about the library being babelized.

Name
""""

The name of the babelized class.
This will be a Python class,
so it should follow Python naming conventions such as camel-case typing.

Language
""""""""

The programming language of the library (possible values are "c", "c++",
"fortran", and "python").

.. code:: toml

  [library]
  language = "c"

Library
"""""""

The name of the BMI library to wrap.
This is the text passed to the linker through the `-l` option;
for example, use "foo" for a library *libfoo.a*.

Header
""""""

The name of the header file (*.h*, *.hxx*) declaring the BMI class.
This option is only needed when wrapping C and C++ libraries.

Entry point
"""""""""""

The name of the BMI entry point into the library.
For object-oriented languages,
this is typically the name of a class that implements the BMI.
For procedural languages,
this is typically a function.

An example of a C++ library (*bmi_child*), exposing a class *BmiChild* (which
implements a BMI) might look like the following:

.. code:: toml

   [library]
   [library.Child]
   language = "c++"
   library = "bmi_child"
   header = "bmi_child.hxx"
   entry_point = "BmiChild"

whereas a C library (*bmi_cem*), exposing a function *register_bmi_cem* (which
implements a BMI) might look like:

.. code:: toml

   [library]
   [library.Cem]
   language = "c"
   library = "bmi_cem"
   header = "bmi_cem.h"
   entry_point = "register_bmi_cem"

Build section
^^^^^^^^^^^^^

In the build section the user can specify flags to pass to the compiler
when building the extension.

Package section
^^^^^^^^^^^^^^^

Name and extra requirements needed to build the babelized library.

Name
""""

Name to use for the wrapped package. This is used when creating the new
package **. For example, the following will create
a new package, *pymt_foo*.

.. code:: toml

  [package]
  name = "pymt_foo"

Requirements
""""""""""""

List of packages required by the library being wrapped. For example, the
following indicates that the packages *foo* and *bar* are dependencies
for the package.

.. code:: toml

  [package]
  requirements = [ "foo", "bar",]

Info section
^^^^^^^^^^^^

Descriptive information about the package.

Github username
"""""""""""""""

The GitHub username or organization where this package will be hosted. This
is used in generating links to the CI, docs, etc.

Author
""""""

Author of the wrapped package. Note that this is not the author of the
library being wrapped, just the code generated by the *babelizer*.

Email
"""""

Contact email to use for the wrapped package.

License
"""""""

Specify the Open Source license for the wrapped package. Note that this is not the
license for the library being wrapped, just for the code generated by the *babelizer*.

Summary
"""""""

A short description of the wrapped library.

Ci section
^^^^^^^^^^

Information about how to set up continuous integration.

.. code:: toml

    [ci]
    python_version = ["3.7", "3.8", "3.9"]
    os = ["linux", "mac", "windows"]


Python version
""""""""""""""

A list of Python versions to build and test the generated project with.

Operating system
""""""""""""""""

A list of operating systems to build the generate project on. Supported values are
*linux*, *mac*, and *windows*.

Example babel.toml
^^^^^^^^^^^^^^^^^^

Below is an example of a *babel.toml* file that describes a shared library,
written in C. In this example, the library, *bmi_hydrotrend*, exposes the
function *register_bmi_hydrotrend* that implements a BMI for a component
called *hydrotrend*.

.. code:: toml

    [library]
    [library.Hydrotrend]
    language = "c"
    library = "bmi_hydrotrend"
    header = "bmi_hydrotrend.h"
    entry_point = "register_bmi_hydrotrend"

    [build]
    undef_macros = []
    define_macros = []
    libraries = []
    library_dirs = []
    include_dirs = []
    extra_compile_args = []

    [package]
    name = "pymt_hydrotrend"
    requirements = ["hydrotrend"]

    [info]
    github_username = "pymt-lab"
    package_author = "csdms"
    package_author_email = "csdms@colorado.edu"
    package_license = "MIT"
    summary = "PyMT plugin for hydrotrend"

    [ci]
    python_version = ["3.7", "3.8", "3.9"]
    os = ["linux", "mac", "windows"]

You can use the ``babelize sample-config`` command to generate
a sample *babel.toml* file to get you started. For example,
the above *babel.toml* can be generated with the following,

.. code:: bash

    babelize sample-config

Use
---

Generate Python bindings for a library that implements a BMI,
sending output to the current directory

.. code:: bash

    babelize init babel.toml

Update an existing repository

.. code:: bash

  babelize update

For a complete example of using the *babelizer*
to wrap a C library exposing a BMI,
see the User Guide of the `documentation`_.


.. Links:

.. _Basic Model Interface: https://bmi.readthedocs.io/
.. _CSDMS Workbench: https://csdms.colorado.edu/wiki/Workbench
.. _documentation: https://babelizer.readthedocs.io/
.. _BMI C: https://github.com/csdms/bmi-c/
.. _BMI C++: https://github.com/csdms/bmi-cxx/
.. _BMI Fortran: https://github.com/csdms/bmi-fortran/
.. _BMI Python: https://github.com/csdms/bmi-python/
.. _BMI example C: https://github.com/csdms/bmi-example-c/
.. _BMI example C++: https://github.com/csdms/bmi-example-cxx/
.. _BMI example Fortran: https://github.com/csdms/bmi-example-fortran/
.. _BMI example Python: https://github.com/csdms/bmi-example-python/

Owner

JOSS Publication

The Babelizer: language interoperability for model coupling in the geosciences

Published

March 19, 2022

DOI

10.21105/joss.03344

Volume 7, Issue 71, Page 3344

Authors

Eric W.h. Hutton
Community Surface Dynamics Modeling System, University of Colorado Boulder

Mark D. Piper
Community Surface Dynamics Modeling System, University of Colorado Boulder

Gregory E. Tucker
Community Surface Dynamics Modeling System, University of Colorado Boulder, Cooperative Institute for Research in Environmental Sciences (CIRES), University of Colorado Boulder, Department of Geological Sciences, University of Colorado Boulder

Editor

Kristen Thyng

Tags

C++ geosciences modeling interface

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages