Autogenerated clib core objects

.gitignore

@@ -40,6 +40,7 @@ environment.y*
 *.mex*
 *.asv
 *.gv*
+*.mod
 .cproject
 .project
 .pydevproject

include/cantera/equil/MultiPhase.h

@@ -88,6 +88,17 @@ class MultiPhase
      */
     void addPhases(MultiPhase& mix);
 
+    //! Add a phase to the mixture.
+    /*!
+     *  This function must be called before the init() function is called,
+     *  which serves to freeze the MultiPhase.
+     *
+     *  @param p pointer to the phase object
+     *  @param moles total number of moles of all species in this phase
+     *  @since New in %Cantera 3.2.
+     */
+    void addPhase(shared_ptr<ThermoPhase> p, double moles);
+
     //! Add a phase to the mixture.
     /*!
      *  This function must be called before the init() function is called,
@@ -575,6 +586,11 @@ class MultiPhase
     //! Vector of the ThermoPhase pointers.
     vector<ThermoPhase*> m_phase;
 
+    //! Vector of shared ThermoPhase pointers.
+    //! Contains valid phase entries if added by addPhase(shared_ptr<ThermoPhase>) and
+    //! null pointers if a phase is added via addPhase(ThermoPhase*).
+    vector<shared_ptr<ThermoPhase>> m_sharedPhase;
+
     //! Global Stoichiometric Coefficient array
     /*!
      * This is a two dimensional array m_atoms(m, k). The first index is the

include/cantera/kinetics/Kinetics.h

@@ -217,6 +217,16 @@ class Kinetics
      */
     shared_ptr<ThermoPhase> reactionPhase() const;
 
+    /**
+     * Return pointer to phase associated with Kinetics by index.
+     * @param n Index of the ThermoPhase being sought.
+     * @since New in %Cantera 3.2.
+     * @see thermo
+     */
+    shared_ptr<ThermoPhase> phase(size_t n=0) const {
+        return m_thermo[n];
+    }
+
     /**
      * This method returns a reference to the nth ThermoPhase object defined
      * in this kinetics mechanism. It is typically used so that member

interfaces/sourcegen/sourcegen/_HeaderFileParser.py

@@ -11,14 +11,15 @@
 
 from ._dataclasses import HeaderFile, Func, Recipe
 from ._helpers import read_config
+from .clib import CLibSourceGenerator
 
 
 _LOGGER = logging.getLogger()
 
 _CLIB_PATH = Path(__file__).parents[3] / "include" / "cantera" / "clib"
 _CLIB_IGNORE = ["clib_defs.h", "ctmatlab.h"]
 
-_DATA_PATH = Path(__file__).parent / "_data"
+_HERE = Path(__file__).parent
 
 class HeaderFileParser:
     """
@@ -38,8 +39,17 @@ def headers_from_yaml(
         ) -> list[HeaderFile]:
         """Parse header file YAML configuration."""
         files = sorted(
-            ff for ff in _DATA_PATH.glob("*.yaml") if ff.name not in ignore_files)
-        return [cls(ff, ignore_funcs.get(ff.name, []))._parse_yaml() for ff in files]
+            ff for ff in (_HERE / "_data").glob("*.yaml")
+            if ff.name not in ignore_files)
+        files = [cls(ff, ignore_funcs.get(ff.name, []))._parse_yaml() for ff in files]
+
+        # preprocess header information (uses CLibSourceGenerator)
+        config = read_config(_HERE / "clib" / "config.yaml")
+        templates = read_config(_HERE / "clib" / "templates.yaml")
+        for key in ["ignore_files", "ignore_funcs"]:
+            config.pop(key)
+        CLibSourceGenerator(None, config, templates).resolve_tags(files)
+        return files
 
     def _parse_yaml(self) -> HeaderFile:
         msg = f"  parsing {self._path.name!r}"

interfaces/sourcegen/sourcegen/_data/README.md

@@ -23,10 +23,11 @@ based on a recipe, which is subsequently used to scaffold API functions using de
 *Jinja* templates. The following recipe/CLib function types are differentiated:
 
 - `function`: Regular function defined in the `Cantera` namespace.
-- `constructor`: A CLib constructor adds new (or existing) C++ objects to CLib storage.
-    As all objects are handled via smart `shared_ptr<>`, a CLib constructor requires a
-    C++ utility functions that returning a pointer to a new object or an object that is
-    not yet added to CLib storage. Constructor names should start with `new`.
+- `constructor`: A CLib constructor adds new C++ objects to CLib storage. Constructor
+    names should start with `new`. As all objects are handled via smart `shared_ptr<>`,
+    CLib constructors require C++ utility functions that return a pointer to a new
+    object. Constructors with the name `new` will use the C++ default constructor.
+- `accessor`: a CLib accessor adds existing or spawned C++ objects to CLib storage.
 - `destructor`: A CLib destructor removes a C++ object from CLib. Destructor names
     should start with `del`.
 - `getter`: Implements a getter method of a C++ class.

interfaces/sourcegen/sourcegen/_data/ct_auto.yaml

@@ -8,21 +8,23 @@ prefix: ct3
 base: ""
 recipes:
 - name: getCanteraVersion
-  implements: version
+  implements: version  # inconsistent API (preexisting)
 - name: getGitCommit
-  implements: gitCommit
+  implements: gitCommit  # inconsistent API (preexisting)
 - name: getCanteraError
 - name: addCanteraDirectory
-  implements: addDirectory
+  implements: addDirectory  # inconsistent API (preexisting)
 - name: getDataDirectories
 - name: findInputFile
-- name: suppress_deprecation_warnings
-- name: make_deprecation_warnings_fatal
-- name: suppress_warnings
-- name: warnings_suppressed
-- name: make_warnings_fatal
-- name: suppress_thermo_warnings
+- name: suppress_deprecation_warnings  # inconsistent API (snake_case; preexisting)
+- name: make_deprecation_warnings_fatal  # inconsistent API (snake_case; preexisting)
+- name: suppress_warnings  # inconsistent API (snake_case; preexisting)
+- name: warnings_suppressed  # inconsistent API (snake_case; preexisting)
+- name: make_warnings_fatal  # inconsistent API (snake_case; preexisting)
+- name: suppress_thermo_warnings  # inconsistent API (snake_case; preexisting)
+- name: use_legacy_rate_constants  # inconsistent API (snake_case; preexisting)
+- name: appdelete
 - name: clearStorage
 - name: resetStorage
-# - name: setLogWriter  # only used by .NET API
-# - name: setLogCallback  # only used by .NET API
+- name: setLogWriter
+- name: setLogCallback

interfaces/sourcegen/sourcegen/_data/ctfunc_auto.yaml

@@ -8,28 +8,29 @@ prefix: func13
 base: Func1
 recipes:
 - name: check
-  implements: checkFunc1
-- name: newBasic
+  implements: checkFunc1  # inconsistent API (preexisting)
+- name: new_basic  # inconsistent API (snake_case; preexisting)
   implements: newFunc1(const string&, double)
-- name: newAdvanced
+- name: new_advanced  # inconsistent API (snake_case; preexisting)
   implements: newFunc1(const string&, const vector<double>&)
-- name: newCompound
+- name: new_compound  # inconsistent API (snake_case; preexisting)
   implements: newFunc1(const string&, const shared_ptr<Func1>, const shared_ptr<Func1>)
-- name: newModified
+- name: new_modified  # inconsistent API (snake_case; preexisting)
   implements: newFunc1(const string&, const shared_ptr<Func1>, double)
-- name: newSum
-  implements: newSumFunction
-- name: newDiff
-  implements: newDiffFunction
-- name: newProd
-  implements: newProdFunction
-- name: newRatio
-  implements: newRatioFunction
+- name: new_sum
+  implements: newSumFunction  # inconsistent API (preexisting)
+- name: new_diff
+  implements: newDiffFunction  # inconsistent API (preexisting)
+- name: new_prod
+  implements: newProdFunction  # inconsistent API (preexisting)
+- name: new_ratio
+  implements: newRatioFunction  # inconsistent API (preexisting)
 - name: type
-- name: eval
-- name: newDerivative
-  what: constructor
-  implements: Func1::derivative
+- name: value
+  implements: eval  # inconsistent API (preexisting)
+- name: derivative
+  what: accessor
+# - name: duplicate  <--- unnecessary: traditional CLib duplicates function
 - name: write
 - name: del
   what: destructor

interfaces/sourcegen/sourcegen/_data/ctkin_auto.yaml

@@ -7,11 +7,48 @@ docstring: |-
 prefix: kin3
 base: Kinetics
 parents: []  # List of parent classes
-derived: []  # List of specializations
+derived: [InterfaceKinetics]  # List of specializations
 recipes:
+- name: getType
+  implements: kineticsType  # inconsistent API (preexisting)
 - name: nReactions
-- name: kineticsType
+- name: reaction  # New in Cantera 3.2
+  uses: nReactions
+  what: accessor
+- name: nPhases
+- name: phase
+  uses: nPhases
+  what: accessor
+- name: reactionPhase  # New in Cantera 3.2
+- name: phaseIndex
+- name: nSpecies
+  implements: nTotalSpecies  # inconsistent API (preexisting)
+- name: reactantStoichCoeff
+- name: productStoichCoeff
 - name: getFwdRatesOfProgress
+- name: getRevRatesOfProgress
+- name: getNetRatesOfProgress
+- name: getEquilibriumConstants
+- name: getFwdRateConstants
+- name: getRevRateConstants
+- name: getCreationRates
+- name: getDestructionRates
+- name: getNetProductionRates
+- name: multiplier
+- name: setMultiplier
+- name: isReversible
+- name: speciesIndex
+  implements: kineticsSpeciesIndex(const string&)  # inconsistent API (preexisting)
+- name: advanceCoverages
+  implements: advanceCoverages(double)
+- name: getDeltaEnthalpy  # previously: part of getDelta
+- name: getDeltaGibbs  # previously: part of getDelta
+- name: getDeltaEntropy  # previously: part of getDelta
+- name: getDeltaSSEnthalpy  # previously: part of getDelta
+- name: getDeltaSSGibbs  # previously: part of getDelta
+- name: getDeltaSSEntropy  # previously: part of getDelta
+# - name: getSourceTerms  # <--- used by MATLAB interface for "massProdRate"
+# - name: start  # <--- unused except for FORTRAN API
 - name: del
   what: noop
   brief: Destructor; required by some APIs although object is managed by Solution.

interfaces/sourcegen/sourcegen/_data/ctmix_auto.yaml

@@ -0,0 +1,51 @@
+# This file is part of Cantera. See License.txt in the top-level directory or
+# at https://cantera.org/license.txt for license and copyright information.
+
+docstring: |-
+  Auto-generated CLib API for %Cantera's MultiPhase class.
+  Implements a replacement for CLib's traditional @c ctmultiphase library.
+prefix: mix3
+base: MultiPhase
+parents: []  # List of parent classes
+derived: []  # List of specializations
+recipes:
+- name: new
+- name: addPhase
+  implements: addPhase(shared_ptr<ThermoPhase>, double)
+- name: init
+- name: updatePhases
+- name: nElements
+- name: elementIndex
+- name: nSpecies
+- name: speciesIndex
+  implements: speciesIndex(size_t, size_t)
+- name: temperature
+- name: setTemperature
+- name: minTemp
+- name: maxTemp
+- name: charge
+- name: phaseCharge
+- name: pressure
+- name: setPressure
+- name: nAtoms
+- name: nPhases
+- name: phaseMoles
+- name: setPhaseMoles
+- name: setMoles
+- name: setMolesByName
+  implements: setMolesByName(const string&)
+- name: speciesMoles
+- name: elementMoles
+- name: equilibrate
+  implements: equilibrate(int, const char*, double, int, int, int)
+- name: getChemPotentials
+- name: enthalpy
+- name: entropy
+- name: gibbs
+- name: cp
+- name: volume
+- name: speciesPhaseIndex
+- name: moleFraction
+- name: del
+- name: cabinetSize
+- name: parentHandle

interfaces/sourcegen/sourcegen/_data/ctrxn_auto.yaml

@@ -0,0 +1,20 @@
+# This file is part of Cantera. See License.txt in the top-level directory or
+# at https://cantera.org/license.txt for license and copyright information.
+
+docstring: |-
+  Auto-generated CLib API for %Cantera's Reaction class.
+  Implements an extension of CLib's traditional @c ct library.
+prefix: rxn3
+base: Reaction
+parents: []  # List of parent classes
+derived: []  # List of specializations
+recipes:
+- name: new
+- name: equation  # previously: ctkin_getReactionString
+- name: type  # previously: ctkin_getReactionType
+- name: usesThirdBody
+- name: valid
+# - name: id  <--- member variable (access not yet implemented)
+- name: del
+- name: cabinetSize
+- name: parentHandle

interfaces/sourcegen/sourcegen/_data/ctsol_auto.yaml

@@ -23,21 +23,15 @@ recipes:
 - name: thermo
 - name: kinetics
 - name: transport
+- name: transportModel
 - name: setTransportModel
-  code: |-
-    try {
-        auto obj = SolutionCabinet::at(handle);
-        TransportCabinet::del(
-            TransportCabinet::index(*(obj->transport()), handle));
-        obj->setTransportModel(model);
-        return TransportCabinet::add(obj->transport(), handle);
-    } catch (...) {
-        return handleAllExceptions(-2, ERR);
-    }
+  uses: [transport]
+  what: accessor
 - name: nAdjacent
 - name: adjacent
-  implements: Solution::adjacent(size_t)
-  uses: [thermo, kinetics, transport]
-  what: constructor  # registers object in CLib storage
+  implements: adjacent(size_t)
+  uses: [nAdjacent, thermo, kinetics, transport]
+  what: accessor
 - name: adjacentName
+- name: source
 - name: cabinetSize