[Reactor] clarify FlowDevice interface

include/cantera/clib/ctreactor.h

@@ -3,7 +3,7 @@
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
-// at http://www.cantera.org/license.txt for license and copyright information.
+// at https://cantera.org/license.txt for license and copyright information.
 
 #ifndef CTC_REACTOR_H
 #define CTC_REACTOR_H
@@ -55,8 +55,13 @@ extern "C" {
     CANTERA_CAPI int flowdev_setMaster(int i, int n);
     CANTERA_CAPI double flowdev_massFlowRate(int i, double time);
     CANTERA_CAPI int flowdev_setMassFlowRate(int i, double mdot);
-    CANTERA_CAPI int flowdev_setParameters(int i, int n, const double* v);
-    CANTERA_CAPI int flowdev_setFunction(int i, int n);
+    CANTERA_CAPI int flowdev_setParameters(int i, int n, const double* v);  //!< @deprecated To be removed after Cantera 2.5.
+    CANTERA_CAPI int flowdev_setMassFlowCoeff(int i, double v);
+    CANTERA_CAPI int flowdev_setValveCoeff(int i, double v);
+    CANTERA_CAPI int flowdev_setPressureCoeff(int i, double v);
+    CANTERA_CAPI int flowdev_setFunction(int i, int n); //!< @deprecated To be removed after Cantera 2.5.
+    CANTERA_CAPI int flowdev_setPressureFunction(int i, int n);
+    CANTERA_CAPI int flowdev_setTimeFunction(int i, int n);
 
     CANTERA_CAPI int wall_new2(const char* type);
     CANTERA_CAPI int wall_new(int type); //!< @deprecated To be changed after Cantera 2.5.

include/cantera/zeroD/FlowDevice.h

@@ -54,7 +54,7 @@ class FlowDevice
     }
 
     //! Mass flow rate (kg/s).
-    doublereal massFlowRate(double time = -999.0) {
+    double massFlowRate(double time = -999.0) {
         if (time != -999.0) {
             updateMassFlowRate(time);
         }
@@ -63,14 +63,14 @@ class FlowDevice
 
     //! Update the mass flow rate at time 'time'. This must be overloaded in
     //! subclassess to update m_mdot.
-    virtual void updateMassFlowRate(doublereal time) {}
+    virtual void updateMassFlowRate(double time) {}
 
     //! Mass flow rate (kg/s) of outlet species k. Returns zero if this species
     //! is not present in the upstream mixture.
-    doublereal outletSpeciesMassFlowRate(size_t k);
+    double outletSpeciesMassFlowRate(size_t k);
 
     //! specific enthalpy
-    doublereal enthalpy_mass();
+    double enthalpy_mass();
 
     //! Install a flow device between two reactors.
     /*!
@@ -93,28 +93,64 @@ class FlowDevice
         return *m_out;
     }
 
-    //! set parameters. Generic function used only in the Matlab interface. From
-    //! Python or C++, device-specific functions like Valve::setPressureCoeff
-    //! should be used instead.
+    //! Set parameters. Generic function formerly used in the Matlab interface.
+    //! @deprecated To be removed after Cantera 2.5.
     virtual void setParameters(int n, const double* coeffs) {
-        m_coeffs.resize(n);
-        std::copy(coeffs, coeffs + n, m_coeffs.begin());
+        warn_deprecated("FlowDevice::setParameters()",
+                        "To be removed after Cantera 2.5. "
+                        "Use device-specific functions (e.g. "
+                        "Valve::setValveCoeff) instead.");
+        m_coeff = coeffs[0]; // vectorized coefficients are not used
     }
 
     //! Set a function of a single variable that is used in determining the
     //! mass flow rate through the device. The meaning of this function
     //! depends on the parameterization of the derived type.
-    void setFunction(Func1* f);
+    //! @deprecated To be removed after Cantera 2.5.
+    void setFunction(Func1* f) {
+        warn_deprecated("FlowDevice::setFunction()",
+                        "To be removed after Cantera 2.5. "
+                        "Use FlowDevice::setTimeFunction or "
+                        "FlowDevice::setPressureFunction instead.");
+        if (typeStr()=="MassFlowController") {
+            setTimeFunction(f);
+        } else if (typeStr()=="Valve") {
+            setPressureFunction(f);
+        }
+    }
+
+    //! Set a function of pressure that is used in determining the
+    //! mass flow rate through the device. The evaluation of mass flow
+    //! depends on the derived flow device class.
+    virtual void setPressureFunction(Func1* f);
+
+    //! Set a function of time that is used in determining
+    //! the mass flow rate through the device. The evaluation of mass flow
+    //! depends on the derived flow device class.
+    virtual void setTimeFunction(Func1* g);
 
     //! Set the fixed mass flow rate (kg/s) through the flow device.
-    void setMassFlowRate(doublereal mdot) {
+    //! @deprecated To be removed after Cantera 2.5.
+    void setMassFlowRate(double mdot) {
+        warn_deprecated("FlowDevice::setMassFlowRate()",
+                        "To be removed after Cantera 2.5. "
+                        "Use device-specific functions (e.g. "
+                        "Valve::setValveCoeff) instead.");
         m_mdot = mdot;
     }
 
 protected:
-    doublereal m_mdot;
-    Func1* m_func;
-    vector_fp m_coeffs;
+    double m_mdot;
+
+    //! Function set by setPressureFunction; used by updateMassFlowRate
+    Func1* m_pfunc;
+
+    //! Function set by setTimeFunction; used by updateMassFlowRate
+    Func1* m_tfunc;
+
+    //! Coefficient set by derived classes; used by updateMassFlowRate
+    double m_coeff;
+
     int m_type; //!< @deprecated To be removed after Cantera 2.5.
 
 private:

include/cantera/zeroD/flowControllers.h

@@ -7,6 +7,7 @@
 #define CT_FLOWCONTR_H
 
 #include "FlowDevice.h"
+#include "cantera/base/ctexceptions.h"
 
 namespace Cantera
 {
@@ -28,6 +29,27 @@ class MassFlowController : public FlowDevice
         return FlowDevice::ready() && m_mdot >= 0.0;
     }
 
+    //! Set the mass flow coefficient.
+    /*!
+     * *m* has units of kg/s. The mass flow rate is computed as:
+     * \f[\dot{m} = m g(t) \f]
+     * where *g* is a function of time that is set by `setTimeFunction`.
+     * If no function is specified, the mass flow rate defaults to:
+     * \f[\dot{m} = m \f]
+     */
+    void setMassFlowCoeff(double m) {
+        m_coeff = m;
+    }
+
+    //! Get the mass flow coefficient.
+    double getMassFlowCoeff() {
+        return m_coeff;
+    }
+
+    virtual void setPressureFunction(Func1* f) {
+        throw NotImplementedError("MassFlowController::setPressureFunction");
+    }
+
     /// If a function of time has been specified for mdot, then update the
     /// stored mass flow rate. Otherwise, mdot is a constant, and does not
     /// need updating.
@@ -49,21 +71,34 @@ class PressureController : public FlowDevice
     }
 
     virtual bool ready() {
-        return FlowDevice::ready() && m_master != 0 && m_coeffs.size() == 1;
+        return FlowDevice::ready() && m_master != 0;
     }
 
     void setMaster(FlowDevice* master) {
         m_master = master;
     }
 
+    virtual void setTimeFunction(Func1* g) {
+        throw NotImplementedError("PressureController::setTimeFunction");
+    }
+
     //! Set the proportionality constant between pressure drop and mass flow
     //! rate
     /*!
      * *c* has units of kg/s/Pa. The mass flow rate is computed as:
+     * \f[\dot{m} = \dot{m}_{master} + c f(\Delta P) \f]
+     * where *f* is a functions of pressure drop that is set by
+     * `setPressureFunction`. If no functions is specified, the mass flow
+     * rate defaults to:
      * \f[\dot{m} = \dot{m}_{master} + c \Delta P \f]
      */
     void setPressureCoeff(double c) {
-        m_coeffs = {c};
+        m_coeff = c;
+    }
+
+    //! Get the pressure coefficient.
+    double getPressureCoeff() {
+        return m_coeff;
     }
 
     virtual void updateMassFlowRate(double time);
@@ -88,18 +123,37 @@ class Valve : public FlowDevice
         return "Valve";
     }
 
-    virtual bool ready() {
-        return FlowDevice::ready() && (m_coeffs.size() == 1 || m_func);
+    //! Set the proportionality constant between pressure drop and mass flow
+    //! rate
+    /*!
+     * *c* has units of kg/s/Pa. The mass flow rate is computed as:
+     * \f[\dot{m} = c \Delta P \f]
+     */
+    //! @deprecated To be removed after Cantera 2.5.
+    void setPressureCoeff(double c) {
+        warn_deprecated("Valve::setParameters()",
+                        "To be removed after Cantera 2.5. "
+                        "Use Valve::setValveCoeff instead.");
+        m_coeff = c;
     }
 
     //! Set the proportionality constant between pressure drop and mass flow
     //! rate
     /*!
      * *c* has units of kg/s/Pa. The mass flow rate is computed as:
+     * \f[\dot{m} = c g(t) f(\Delta P) \f]
+     * where *g* and *f* are functions of time and pressure drop that are set
+     * by `setTimeFunction` and `setPressureFunction`, respectively. If no functions are
+     * specified, the mass flow rate defaults to:
      * \f[\dot{m} = c \Delta P \f]
      */
-    void setPressureCoeff(double c) {
-        m_coeffs = {c};
+    void setValveCoeff(double c) {
+        m_coeff = c;
+    }
+
+    //! Get the valve coefficient.
+    double getValveCoeff() {
+        return m_coeff;
     }
 
     /// Compute the currrent mass flow rate, based on the pressure difference.

interfaces/cython/cantera/_cantera.pxd

@@ -585,17 +585,22 @@ cdef extern from "cantera/zerodim.h" namespace "Cantera":
         string typeStr()
         double massFlowRate(double) except +translate_exception
         cbool install(CxxReactorBase&, CxxReactorBase&) except +translate_exception
-        void setFunction(CxxFunc1*)
+        void setPressureFunction(CxxFunc1*) except +translate_exception
+        void setTimeFunction(CxxFunc1*) except +translate_exception
 
     cdef cppclass CxxMassFlowController "Cantera::MassFlowController" (CxxFlowDevice):
         CxxMassFlowController()
+        void setMassFlowCoeff(double)
+        double getMassFlowCoeff()
 
     cdef cppclass CxxValve "Cantera::Valve" (CxxFlowDevice):
-        void setPressureCoeff(double)
         CxxValve()
+        double getValveCoeff()
+        void setValveCoeff(double)
 
     cdef cppclass CxxPressureController "Cantera::PressureController" (CxxFlowDevice):
         CxxPressureController()
+        double getPressureCoeff()
         void setPressureCoeff(double)
         void setMaster(CxxFlowDevice*)
 
@@ -1032,6 +1037,7 @@ cdef class Wall(WallBase):
 cdef class FlowDevice:
     cdef CxxFlowDevice* dev
     cdef Func1 _rate_func
+    cdef Func1 _time_func
     cdef str name
     cdef ReactorBase _upstream
     cdef ReactorBase _downstream

interfaces/cython/cantera/examples/reactors/ic_engine.py

@@ -125,15 +125,15 @@ def piston_speed(t):
     # define opening and closing of valves and injector
     if (np.mod(crank_angle(t_i) - inlet_open, 4 * np.pi) <
             np.mod(inlet_close - inlet_open, 4 * np.pi)):
-        inlet_valve.set_valve_coeff(inlet_valve_coeff)
+        inlet_valve.valve_coeff = inlet_valve_coeff
         test[n1] = 1
     else:
-        inlet_valve.set_valve_coeff(0)
+        inlet_valve.valve_coeff = 0.
     if (np.mod(crank_angle(t_i) - outlet_open, 4 * np.pi) <
             np.mod(outlet_close - outlet_open, 4 * np.pi)):
-        outlet_valve.set_valve_coeff(outlet_valve_coeff)
+        outlet_valve.valve_coeff = outlet_valve_coeff
     else:
-        outlet_valve.set_valve_coeff(0)
+        outlet_valve.valve_coeff = 0.
     if (np.mod(crank_angle(t_i) - injector_open, 4 * np.pi) <
             np.mod(injector_close - injector_open, 4 * np.pi)):
         injector_mfc.set_mass_flow_rate(injector_mass / injector_t_open)