[Doc] Update some cloning docs / deprecation / TODO notes

speth · speth · commit 566665faaef8 · 2025-10-08T10:18:27.000-04:00
diff --git a/doc/sphinx/yaml/phases.md b/doc/sphinx/yaml/phases.md
@@ -113,6 +113,12 @@ are:
   - `surface` ({ct}`details <InterfaceKinetics>`)
   - `edge` ({ct}`details <EdgeKinetics>`)
 
+(sec-yaml-rate-multipliers)=
+`rate-multipliers`
+: A mapping of reaction indices and multipliers applied to the forward rate
+  constants. The key `default` is used to specify the default rate multiplier, which is
+  used for reactions not specified in the mapping.
+
 (sec-yaml-phase-reactions)=
 `reactions`
 : Source of reactions to include in the phase, if a kinetics model has been specified.
diff --git a/include/cantera/base/Solution.h b/include/cantera/base/Solution.h
@@ -55,16 +55,19 @@ class Solution : public std::enable_shared_from_this<Solution>
         return shared_ptr<Solution>( new Solution );
     }
 
-    //! Create a new Solution object with cloned ThermoPhase and Kinetics objects that
-    //! use the same species definitions, thermodynamic parameters, and reactions as
-    //! this one.
+    //! Create a new Solution object with cloned ThermoPhase, Kinetics, and Transport
+    //! objects that use the same species definitions, thermodynamic parameters, and
+    //! reactions as this one.
     //! @param adjacent  For surface phases, an optional list of new adjacent phases
     //!     to link to the InterfaceKinetics object. Any adjacent phases not provided
     //!     will have their ThermoPhase model automatically cloned.
     //! @param withKinetics  Flag indicating whether to clone the Kinetics object
-    //!    associated with this phase
+    //!    associated with this phase. If `false`, the cloned Solution will not include
+    //!    a kinetics manager.
     //! @param withTransport  Flag indicating whether to clone the Transport object
-    //!    associated with this phase
+    //!    associated with this phase. If `false`, the cloned Solution will not include
+    //!    a transport property manager.
+    //! @since New in %Cantera 3.2.
     shared_ptr<Solution> clone(const vector<shared_ptr<Solution>>& adjacent={},
                                bool withKinetics=true, bool withTransport=true) const;
 
diff --git a/include/cantera/kinetics/Kinetics.h b/include/cantera/kinetics/Kinetics.h
@@ -142,6 +142,7 @@ class Kinetics
     //! @param phases Phases used to specify the state for the newly cloned Kinetics
     //!     object. These can be created from the phases used by this object using the
     //!     ThermoPhase::clone() method.
+    //! @since New in %Cantera 3.2.
     shared_ptr<Kinetics> clone(const vector<shared_ptr<ThermoPhase>>& phases) const;
 
     //! Identifies the Kinetics manager type.
diff --git a/include/cantera/thermo/ThermoPhase.h b/include/cantera/thermo/ThermoPhase.h
@@ -398,6 +398,7 @@ class ThermoPhase : public Phase
 
     //! Create a new ThermoPhase object using the same species definitions,
     //! thermodynamic parameters, and state as this one.
+    //! @since New in %Cantera 3.2.
     shared_ptr<ThermoPhase> clone() const;
 
     //! @name  Information Methods
diff --git a/include/cantera/transport/Transport.h b/include/cantera/transport/Transport.h
@@ -86,6 +86,12 @@ class Transport
     Transport(const Transport&) = delete;
     Transport& operator=(const Transport&) = delete;
 
+    //! Create a new Transport object using the same transport model and species
+    //! transport properties as this one.
+    //! @param phase ThermoPhase used to specify the state for the newly cloned
+    //!     Transport object. Can be created from the phase used by the current
+    //!     Transport object using the ThermoPhase::clone() method.
+    //! @since New in %Cantera 3.2.
     shared_ptr<Transport> clone(shared_ptr<ThermoPhase> thermo) const;
 
     //! Identifies the model represented by this Transport object. Each derived class
diff --git a/include/cantera/zeroD/Reactor.h b/include/cantera/zeroD/Reactor.h
@@ -48,6 +48,8 @@ class Reactor : public ReactorBase
 public:
     Reactor(shared_ptr<Solution> sol, const string& name="(none)");
     Reactor(shared_ptr<Solution> sol, bool clone, const string& name="(none)");
+    //! TODO: Remove after %Cantera 3.2 -- all derived classes should use Solution-based
+    //! constructors.
     using ReactorBase::ReactorBase; // inherit constructors
 
     string type() const override {
diff --git a/include/cantera/zeroD/ReactorBase.h b/include/cantera/zeroD/ReactorBase.h
@@ -48,6 +48,7 @@ struct SensitivityParameter
 class ReactorBase
 {
 public:
+    //! @deprecated After %Cantera 3.2, this constructor will become protected
     explicit ReactorBase(const string& name="(none)");
 
     //! Instantiate a ReactorBase object with Solution contents.
diff --git a/include/cantera/zeroD/ReactorFactory.h b/include/cantera/zeroD/ReactorFactory.h
@@ -61,21 +61,42 @@ shared_ptr<ReactorBase> newReactor(
     const string& model, shared_ptr<Solution> contents, const string& name="(none)");
 
 //! Create a Reactor object of the specified type and contents
+//! @param  model  Reactor type to be created. See [this list of reactor
+//!     types](../reference/reactors/index.html) for available options.
+//! @param  contents  Solution object to model the thermodynamic properties and
+//!     reactions occurring in the reactor
+//! @param clone  Determines whether to clone `sol` so that the internal state of this
+//!     reactor is independent of the original Solution object and any Solution objects
+//!     used by other reactors in the network.
+//! @param name  Name of the reactor.
 //! @since  New in %Cantera 3.2. Transitional method returning a `Reactor` object.
 shared_ptr<Reactor> newReactor4(
     const string& model, shared_ptr<Solution> contents, bool clone=true,
     const string& name="(none)");
 
 //! Create a Reservoir object with the specified contents
+//! @param  contents  Solution object to model the contents of this reservoir
+//! @param clone  Determines whether to clone `sol` so that the internal state of this
+//!     reservoir is independent of the original Solution object and any Solution
+//!     objects used by other reactors in the network.
+//! @param name  Name of the reservoir.
 //! @since New in %Cantera 3.2.
 shared_ptr<Reservoir> newReservoir(
     shared_ptr<Solution> contents, bool clone=true, const string& name="(none)");
 
 //! Create a ReactorSurface object with the specified contents and adjacent reactors
 //! participating in surface reactions.
+//! @param  contents  Solution (Interface) object to model the thermodynamic properties
+//!     and reactions occurring in the reactor
+//! @param  reactors  List of Reactors adjacent to this surface, whose contents
+//!     participate in reactions occurring on this surface.
+//! @param clone  Determines whether to clone `sol` so that the internal state of this
+//!     surface is independent of the original Interface object and any Solution objects
+//!     used by other reactors in the network except those in the `reactors` list.
+//! @param name  Name of the reactor surface.
 //! @since  New in %Cantera 3.2.
 shared_ptr<ReactorSurface> newReactorSurface(
-    shared_ptr<Solution> soln, const vector<shared_ptr<ReactorBase>>& reactors,
+    shared_ptr<Solution> contents, const vector<shared_ptr<ReactorBase>>& reactors,
     bool clone=true, const string& name="(none)");
 
 //! @}
diff --git a/src/zeroD/Reactor.cpp b/src/zeroD/Reactor.cpp
@@ -22,6 +22,8 @@ namespace bmt = boost::math::tools;
 namespace Cantera
 {
 
+// TODO: After Cantera 3.2, this method can be replaced by delegating to
+// Reactor::Reactor(sol, true, name)
 Reactor::Reactor(shared_ptr<Solution> sol, const string& name)
     : ReactorBase(sol, name)
 {
diff --git a/src/zeroD/ReactorBase.cpp b/src/zeroD/ReactorBase.cpp
@@ -17,6 +17,8 @@ ReactorBase::ReactorBase(const string& name) : m_name(name)
 {
 }
 
+// TODO: After Cantera 3.2, this method can be replaced by delegating to
+// ReactorBase::ReactorBase(sol, true, name)
 ReactorBase::ReactorBase(shared_ptr<Solution> sol, const string& name)
     : ReactorBase(name)
 {
diff --git a/src/zeroD/ReactorFactory.cpp b/src/zeroD/ReactorFactory.cpp
@@ -110,6 +110,10 @@ shared_ptr<ReactorBase> newReactor(
 {
     warn_deprecated("newReactor", "Behavior changes after Cantera 3.2, when a "
         "'shared_ptr<Reactor>' is returned.\nFor new behavior, use 'newReactor4'.");
+    warn_deprecated("newReactor", "`clone` argument not specified; Default behavior "
+        "will change from `clone=False` to `clone=True` after Cantera 3.2.\n"
+        "Use the transitional newReactor4() function to provide a value for the clone "
+        "argument");
     return newReactorBase(model, contents, false, name);
 }
 
@@ -137,10 +141,10 @@ shared_ptr<Reservoir> newReservoir(
     return reservoir;
 }
 
-shared_ptr<ReactorSurface> newReactorSurface(shared_ptr<Solution> soln,
+shared_ptr<ReactorSurface> newReactorSurface(shared_ptr<Solution> contents,
     const vector<shared_ptr<ReactorBase>>& reactors, bool clone, const string& name)
 {
-    return make_shared<ReactorSurface>(soln, reactors, clone, name);
+    return make_shared<ReactorSurface>(contents, reactors, clone, name);
 }
 
 }

Original file line number	Diff line number	Diff line change
`@@ -48,6 +48,7 @@ struct SensitivityParameter`
`48`	`48`	`class ReactorBase`
`49`	`49`	`{`
`50`	`50`	`public:`
	`51`	`+ //! @deprecated After %Cantera 3.2, this constructor will become protected`
`51`	`52`	`explicit ReactorBase(const string& name="(none)");`
`52`	`53`
`53`	`54`	`//! Instantiate a ReactorBase object with Solution contents.`
Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,8 @@ namespace bmt = boost::math::tools;`
`22`	`22`	`namespace Cantera`
`23`	`23`	`{`
`24`	`24`
	`25`	`+// TODO: After Cantera 3.2, this method can be replaced by delegating to`
	`26`	`+// Reactor::Reactor(sol, true, name)`
`25`	`27`	`Reactor::Reactor(shared_ptr<Solution> sol, const string& name)`
`26`	`28`	`: ReactorBase(sol, name)`
`27`	`29`	`{`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,8 @@ ReactorBase::ReactorBase(const string& name) : m_name(name)`
`17`	`17`	`{`
`18`	`18`	`}`
`19`	`19`
	`20`	`+// TODO: After Cantera 3.2, this method can be replaced by delegating to`
	`21`	`+// ReactorBase::ReactorBase(sol, true, name)`
`20`	`22`	`ReactorBase::ReactorBase(shared_ptr<Solution> sol, const string& name)`
`21`	`23`	`: ReactorBase(name)`
`22`	`24`	`{`