Cantera/Adding Python Class Via C++

The following instructions describe how to implement a new C++ class in Cantera 2.1 and make it accessible via Python.

Hopefully this will save you the headaches and streams of expletives that navigating changes between 2.0 and 2.1 caused me.

(Note to Cantera developers: if you break backwards compatibility and change the way the API works, you need to increment the MAJOR version number, not the MINOR version number.)

Overview

To add a new C++ class in Cantera, you will need to follow a couple of steps:

1. Add the C++ code for the class

2. Wrap the new C++ code with the C API

3. Create a Python object that calls the C API code (is this even necessary?)

4. Create a Cython object (this fourth step was added between Cantera 2.0 and Cantera 2.1)

This Example

This example will show you how to extend the FlowController class to create a new mass flow controller type - specifically, a mass flow controller that controls the flow of a single species. (Note that this is analogous to Maxwell's Demon.)

Strategies

Before jumping into Cantera with both feet (and spending hours thrashing around in the code base), it's important that you step back for a moment and strategize how you want to go about adding your class.

FIRST: The Cantera code base has a lot of layers. That means that for every function or object you implement, you'll be writing 3 or 4 APIs for it. That means that complicated input arguments, non-trivial (well, even trivial) class inheritance diagrams, or modifications to existing functionality is NOT RECOMMENDED.

SECOND: Keep it as simple as possible.

THIRD: Don't overthink it.

FOURTH: Did I mention you want to keep it simple?

It is unfortunate that Cantera is so cumbersome to extend, given the philosophy behind Cantera: it was intended to be an easily-extendable library with modular functionality. Dave Goodwin, the creator of Cantera, left many comments and dummy classes to illustrate how Cantera functionality might be extended. However, with the additional layers of the C API, the Python-C wrappers, and most recently, Cython, you end up doing a lot of code gymnastics for even the simplest extensions.