Cantera/Adding Python Class Via C++: Difference between revisions
From charlesreid1
| Line 20: | Line 20: | ||
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 [http://en.wikipedia.org/wiki/Maxwell's_demon Maxwell's Demon].) | 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 [http://en.wikipedia.org/wiki/Maxwell's_demon Maxwell's Demon].) | ||
==Strategies== | ==Strategies== | ||
| Line 25: | Line 26: | ||
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. | 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. | ||
===Keep It Simple=== | |||
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. | |||
===Think Properties=== | |||
===The Way Things Ought To Be=== | |||
'' | 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. 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. | ||
Ultimately, the ideal solution (to quote Rush Limbaugh: "the way things ought to be") is for the library to be implemented in Python, which provides much more flexibility and sanity than C++. Some underlying Cython would add speed, as would some C, but really, you should be interfacing with external Python and/or C libraries for the heavy lifting (ODEs, solvers, matrices, and such). | |||
Numpy does this particularly well. | |||
Revision as of 04:43, 13 August 2014
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.
Keep It Simple
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.
Think Properties
The Way Things Ought To Be
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. 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.
Ultimately, the ideal solution (to quote Rush Limbaugh: "the way things ought to be") is for the library to be implemented in Python, which provides much more flexibility and sanity than C++. Some underlying Cython would add speed, as would some C, but really, you should be interfacing with external Python and/or C libraries for the heavy lifting (ODEs, solvers, matrices, and such).
Numpy does this particularly well.