Split Cantera into core and toolbox libraries

[ischoegl]

Cantera is quite large, and mixes core and toolbox objects within the same libraries. Some users may only be interested in linking to core objects (species, reactions and their YAML importers), but may not require reactor networks and one-dimensional simulations.

Within C++, a core C++ cantera library would be much leaner than application toolboxes (no sundials, etc.), which may be attractive for those working with OpenFOAM, or any other 3rd party application. I personally do not believe that a split into multiple repositories makes sense whatsoever, as zerod and onedim toolboxes are an integral part of Cantera.

For Python, all objects are currently available at the root level

import cantera as ct
...

where users pick what they need. As an alternative, objects could be topically sorted

from cantera.core import Solution
from cantera.zerod import Reactor
...

which may be more intuitive/instructive to new users. I do realize that the same is possible by writing from cantera import Solution, Reactor, but my point is that those are really two different contexts. Splitting the Python API actually would not require a corresponding split at the C++ level, but doing both would be consistent.

One of the main questions here is the difficulty of splitting libcantera into multiple libraries for core and zerod/onedim? Outside of stock cantera, it is relatively straight-forward to compile against cantera headers and libraries (which I have done several times over the years; as an aside, code compiles much faster), so the question is whether it is feasible to do this the same repository.

This certainly would be a long-term aspirational project,.

PS: The discussion was originally started in #93, but per @bryanwweber and @speth feedback deserves its own thread.

[speth]

Separating this out in the Python user interface is certainly possible, although I don't know how much of a benefit that would provide. There would certainly be a cost in muscle memory for all current users who are used to the current structure. As a point of comparison, the cantera namespace currently includes 130 names, versus 600 in the base numpy namespace, which does break out capabilities into various modules like np.random and np.linalg, so I don't think the cantera namespace is too bloated right now.

On the C++ side, you and others who have been using Cantera for long enough may remember a time when Cantera was actually compiled into separate libraries corresponding to different "modules". This had the very unfortunate effect of needing to specify something like -lctcxx -luser -loneD -lzeroD -lequil -lkinetics -ltransport -lthermo -lctnumerics -lctmath -ltpx -lconverters -lctbase -lcvode -lctlapack -lctblas -lctf2c as part of your compiler command line to link a Cantera program that used a full range of Cantera's features. And of course it was all but impossible to get the order of these right to satisfy the arcane search rules followed by the linker. Hence why I introduced the monolithic libcantera. At least in the case of static linking, the end result is exactly the same: your executable will only contain the functions that are actually called (directly or indirectly) from your code.

And while I recognize that there are users who don't use significant parts of Cantera, I think the cost of having those parts always available is pretty small. The biggest one is probably the fact that the reactor network code requires Sundials, but I hope that we've made that pretty hassle-free with the git submodule. I don't think there are many other use cases where our other dependencies could be made optional. Other than that, the cost is maybe an additional minute of compile time to compile the 0D/1D code. Is there some other cost that I'm missing? Without debug symbols the whole of libcantera.a weighs in at about 16 MB for me, which doesn't seem like that much.

[ischoegl]

The proper way to do this would be to link against the shared library, but that's currently difficult on non-Linux systems because all the C++ symbols aren't exported by default. At a minimum, we'd have to go through and decorate all of the API functions used by the Cython module with __declspec(dllexport) or extern (likely managed by some macro), and I believe there's also some fiddly stuff that has to be done to export the standard library types that interact with any of these functions. This would be broadly more invasive, but would have the upshot of giving us a more usable cantera.dll for Windows (which currently just exports the much simpler C API).

Looks like those are the details that I need to read 3 times before being able to appreciate! I guess I'm too used to the convenience of Linux ... (and not sufficiently familiar with building for Windows). I have compiled against cantera libraries many times (including extensions on Python), and assumed that this approach won't be too different on other OSs.

[bryanwweber]

A book that I have found extremely helpful to wrap my head around this stuff is called Linkers and Loaders by John Levine. It's a little old, but that's kind of an advantage because things were simpler 20+ years ago when it was written, but close enough to how things work today that nothing is really wrong with the description. You can find it on Amazon or he published the pre-copy-editing version on his website: https://www.iecc.com/linker/

[ischoegl]

I guess it’s time to go back to my little toy example (ctapp) and finally get it to compile on windows. It works quite well on Linux - setuptools are straightforward - but thus far I had only tried to link it to the stock conda libraries and headers (with the well known road blocks 😁). As I have my development branch compiled it would be simple to try it that way ... but it’s not a priority at the moment.

It’s obviously more difficult to do the same for all of Cantera, but it would count as a proof of concept.

[ischoegl]

I am replying here as I have the suspicion that what was said above may apply to the MATLAB C++ interface also (at least if one would like to tap into the shared library). FWIW, decorations for __declspec appear to be pretty efficient for classes, see Microsoft Docs.

[ischoegl]

To add more context, the MATLAB C++ interface indeed appears to require __declspec. See cppshrhelp.hpp in their examples, which declares.

#ifdef _MSC_VER
# define DLL_EXPORT __declspec(dllexport)
#elif __GNUC__ >= 4
# define DLL_EXPORT __attribute__ ((visibility("default")))
#else
# define DLL_EXPORT
#endif

This is likely a larger discussion; I don't want to comment on #102 beyond what I already said as I'm not sufficiently familiar.

[bryanwweber]

I'm posting this as a new followup, although it's more related to what @speth said. Quoting from his reply:

The biggest one is probably the fact that the reactor network code requires Sundials, but I hope that we've made that pretty hassle-free with the git submodule.

I wonder if it makes sense to have a library that only includes thermo, transport, and kinetics, and leaves out the SUNDIALS dependency. I'm imagining this would be in addition to having a single library for the whole thing (so we distribute 2 .so files). The reason I wonder if this would be useful is for coupling with CFD codes, where they won't be using SUNDIALS or any of the Reactor/1D stuff at all. Not so much for the file size difference, but just to simplify the linking for any downstream code.

[speth]

Yes, most CFD applications won't use large parts of Cantera, but I still don't see a significant benefit in not having a little bit of unused code in libcantera.a. Do you want options to disable all the thermo models besides ideal gas, too? Equilibrium solvers? What if you don't care about transport? Every option or variant just adds complexity to the build system and increases testing needs.

The one situation where I think the Sundials requirement can be a little annoying is if you are compiling from the .tar.gz release rather than a Git checkout, in an environment where there isn't an easy way to install a packaged copy of Sundials. I think we could improve this case pretty easily by distributing a tarball that includes checkouts of the git submodules.

I think creating multiple library files to be used in different situations would just increase the complexity of linking to Cantera, and doesn't do anything to reduce build requirements. I know it's a bit of an extreme example, but do you think you could reliably figure out which of the libraries from the Cantera 1.7 era you needed to link to?

I can maybe see the value of a build option to disable compilation of the 0D/1D solvers along with the other language interfaces. I think anything more than that will be a big mess.

[bryanwweber]

I still don't see a significant benefit in not having a little bit of unused code in libcantera.a.

At least from my perspective (with the caveat that I haven't ever tried to link Cantera with any CFD codes), the bigger issue is the link-time requirement for SUNDIALS, if you want to do dynamic linking rather than static linking. I'm not sure which method CFD softwares tend to use, though.

I think the other relevant case is for HPC/cluster type installers, who tend to use a system installation of SUNDIALS. That would mean that they have to include SUNDIALS when linking other software, if it's linked to Cantera, right?

I guess your point is that if you're compiling Cantera yourself from a git checkout, you've got a copy of all the necessary parts of libsundials anyways, right? Do those get installed by scons install?

Do you want options to disable all the thermo models besides ideal gas, too? Equilibrium solvers? What if you don't care about transport? Every option or variant just adds complexity to the build system and increases testing needs. ... I can maybe see the value of a build option to disable compilation of the 0D/1D solvers along with the other language interfaces. I think anything more than that will be a big mess.

I agree, this is a slippery slope in terms of the number of options we allow. I was thinking of something along the lines of what you've suggested at the end here. You either get the whole thing, or you get everything that doesn't rely on SUNDIALS, which is the only external dependency (maybe Eigen too?) that we can easily split out due to the limited use of it. I agree that providing a ton of options would be a huge mess.

Maybe it'd be worth identifying and trying to talk to a few people who use Cantera in this kind of situation? Rather than guessing at what they need.

[ischoegl]

Do you want options to disable all the thermo models besides ideal gas, too? Equilibrium solvers? What if you don't care about transport? Every option or variant just adds complexity to the build system and increases testing needs.

I don't think that the idea should be to go back to Cantera 1.7, but rather to create a clear separation between objects that provide input to solvers (i.e. the "core", including all thermo, kinetics, transport, etc.), and applications (e.g. Cantera's reaction network, 1D examples). To put this into Python terms, this would roughly follow the separation of Solution, ReactorNet, and FlameBase.

As an aside, the topic of equilibrium is interesting and not completely clear, as it's legacy code that hasn't been touched in a long time. It technically isn't core, but untangling this is honestly another question. Similarly, the entire area of PureFluid is imho a wart that remains to be worked out as it blocks a range of applications. Both are probably separate discussions.

[speth]

Eigen is a header-only library, and is needed even for transport properties and equilibrium calculations.

If you compile using the submodule for Sundials, then everything is baked into libcantera.a and libcantera_shared.so (or their equivalents), and there is nothing else to specify when linking to Cantera.

At least from my perspective (with the caveat that I haven't ever tried to link Cantera with any CFD codes), the bigger issue is the link-time requirement for SUNDIALS, if you want to do dynamic linking rather than static linking.

When linking to the shared library, it is not necessary to explicitly link to any of Cantera's dependencies [1], because we specify those libraries when creating cantera_shared. On a Linux machine, you can see this by running ldd on the .so file (I forget what the equivalent is on macOS). We used to not do this correctly, so that you were forced to specify all of the downstream dependencies when linking to the Cantera library.

[1] Caveat: It appears that fmt does need to be explicitly linked in the current development version, but I think that's a specific bug, not a general requirement.

[ischoegl]

Linking a question on the UG

[ischoegl]

Superseded by #153