lue_framework_api

The API libraries provide easy to use, high-level access to low-level functionality. The lue_framework_api_cxx library provides a public API to use when writing C++ code that uses LUE framework functionality. For example, people interested in implementing a simulation model in C++ should first look at the functionality provided by this library. It hides a lot of the complexities of using the lower level libraries. People interested in using C or Python can use the language wrappers provided by the lue_framework_api_c and lue_framework_api_python libraries, respectively.

Note

If language bindings for other languages than C, C++, and Python (e.g. for Fortran, Java, Julia, Lua, R, Rust) interest you, you may want to help us adding them. Do contact us if you want to discuss this.

The idea of the setup of the API libraries is to collect all functionality required by multiple language wrapping APIs in the lue_framework_api_cxx library and make the language wrapper libraries as small as possible, containing only the language-specific wrapper code. The same holds for the documentation. Most documentation must be associated with the lue_framework_api_cxx library, and this should be understandable by users of bindings for other languages.

Design

The algorithms in the lue_framework_api_cxx library hide the fact that they are overloaded for different argument types. The algorithms and the types used in this library are of a higher abstraction level than the libraries they depend on. The Field type is a variant that can be represented by several concrete types, like a lue::PartitionedArray or a lue::Scalar. Algorithms translating fields accept fields and forward the call to the concrete algorithm overload that supports the passed in concrete types. If no such algorithm exists, a general overload is called that will throw an overload error exception.

Using the algorithms from the lue_framework_api_cxx library makes life for the user a lot easier. A (minor) drawback for the user of the API’s of statically typed languages like C and C++ is that overload errors only surface at runtime, not at compile-time.