Simplify creation of interface phases

data/diamond.yaml

@@ -22,6 +22,7 @@ phases:
   species: [C(d)]
 - name: diamond_100
   thermo: ideal-surface
+  adjacent-phases: [gas, diamond]
   elements: [H, C]
   species: [c6HH, c6H*, c6*H, c6**, c6HM, c6HM*, c6*M, c6B]
   kinetics: surface

data/lithium_ion_battery.yaml

@@ -149,12 +149,14 @@ phases:
   density: 1.0 kg/m^3
 - name: edge_anode_electrolyte
   thermo: ideal-surface
+  adjacent-phases: [anode, electron, electrolyte]
   species: [(dummy)]
   kinetics: surface
   reactions: [edge_anode_electrolyte-reactions]
   site-density: 0.01 mol/cm^2
 - name: edge_cathode_electrolyte
   thermo: ideal-surface
+  adjacent-phases: [cathode, electron, electrolyte]
   species: [(dummy)]
   kinetics: surface
   reactions: [edge_cathode_electrolyte-reactions]

data/methane_pox_on_pt.yaml

@@ -44,6 +44,7 @@ phases:
     X: {CH4: 0.095, O2: 0.21, AR: 0.79}
 - name: Pt_surf
   thermo: ideal-surface
+  adjacent-phases: [gas]
   elements: [Pt, H, O, C]
   species: [PT(S), H(S), H2O(S), OH(S), CO(S), CO2(S), CH3(S), CH2(S), CH(S),
     C(S), O(S)]

data/ptcombust.yaml

@@ -48,6 +48,7 @@ phases:
     X: {CH4: 0.095, O2: 0.21, AR: 0.79}
 - name: Pt_surf
   thermo: ideal-surface
+  adjacent-phases: [gas]
   elements: [Pt, H, O, C]
   species: [PT(S), H(S), H2O(S), OH(S), CO(S), CO2(S), CH3(S), CH2(S)s,
     CH(S), C(S), O(S)]

data/silane.yaml

@@ -17,7 +17,7 @@ phases:
     SI3H8, SI2, SI3]
   kinetics: gas
   state: {T: 300.0, P: 1 atm}
-  deprecated: >|
+  deprecated: >-
     The input file 'silane.yaml' is deprecated and will be removed after Cantera 2.6.
     The source of the data is unknown, and the NASA polynomials for several species
     contain discontinuities.

data/sofc.yaml

@@ -117,6 +117,7 @@ phases:
   site-density: 0.0176 mol/cm^3
 - name: metal_surface
   thermo: ideal-surface
+  adjacent-phases: [gas]
   elements: [H, O]
   species: [(m), H(m), O(m), OH(m), H2O(m)]
   kinetics: surface
@@ -127,6 +128,7 @@ phases:
   site-density: 2.6e-09
 - name: oxide_surface
   thermo: ideal-surface
+  adjacent-phases: [gas, oxide_bulk]
   elements: [O, H, E]
   species: [(ox), O''(ox), OH'(ox), H2O(ox)]
   kinetics: surface
@@ -137,6 +139,7 @@ phases:
   site-density: 2.0e-09
 - name: tpb
   thermo: edge
+  adjacent-phases: [metal, metal_surface, oxide_surface]
   elements: [H, O]
   species: [(tpb)]
   kinetics: edge

doc/sphinx/yaml/phases.rst

@@ -56,6 +56,17 @@ and optionally reactions that can take place in that phase. The fields of a
     A mapping specifying the thermodynamic state. See
     :ref:`sec-yaml-setting-state`.
 
+``adjacent-phases``
+    For interface phases, specification of adjacent phases that participate in reactions
+    on the interface. This can be:
+
+    - a list of phase names that appear in the ``phases`` section of the file.
+    - A list of single-key mappings of section names to a list of phase names. These
+      sections can be in the same file as the current phase definition, or from another
+      file if written as ``file-path/section-name``. If a relative path is specified,
+      the directory containing the current file is searched first, followed by the
+      Cantera data path.
+
 ``thermo``
     String specifying the phase thermodynamic model to be used. Supported model
     strings are:

include/cantera/base/Interface.h

@@ -0,0 +1,99 @@
+//! @file Interface.h
+
+// 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.
+
+#ifndef CT_INTERFACE_H
+#define CT_INTERFACE_H
+
+#include "cantera/base/Solution.h"
+#include "cantera/thermo/SurfPhase.h"
+#include "cantera/kinetics/InterfaceKinetics.h"
+
+namespace Cantera
+{
+
+//! A container class holding managers for all pieces defining an interface
+class Interface : public Solution
+{
+private:
+    Interface();
+
+public:
+    ~Interface() {}
+    Interface(const Interface&) = delete;
+    Interface& operator=(const Interface&) = delete;
+
+    //! Create an empty Interface object
+    static shared_ptr<Interface> create() {
+        return shared_ptr<Interface>(new Interface());
+    }
+
+    //! Set the reacting phase thermo object
+    void setThermo(shared_ptr<ThermoPhase> thermo) override;
+
+    //! Set the Kinetics object
+    void setKinetics(shared_ptr<Kinetics> kinetics) override;
+
+    //! Get the surface phase thermo object
+    shared_ptr<SurfPhase> thermo() {
+        return m_surf;
+    }
+
+    //! Get the surface phase Kinetics object
+    shared_ptr<InterfaceKinetics> kinetics() {
+        return m_surfkin;
+    }
+
+protected:
+    shared_ptr<SurfPhase> m_surf; //!< Surface phase ThermoPhase manager
+    shared_ptr<InterfaceKinetics> m_surfkin;  //!< Kinetics manager
+};
+
+//! Create and initialize a new Interface from an input file
+/*!
+ * This constructor wraps newPhase() and newKinetics()
+ *
+ * @param infile name of the input file
+ * @param name   name of the surface phase in the file.
+ *               If this is blank, the first phase in the file is used.
+ * @param adjacent vector containing names of adjacent phases that participate in this
+ *                 phases kinetics. If empty, adjacent phases will be instantiated based
+ *                 on the phase definition.
+ * @returns an initialized Interface object.
+ */
+shared_ptr<Interface> newInterface(const std::string& infile,
+    const std::string& name="", const std::vector<std::string>& adjacent={});
+
+
+//! Create and initialize a new Interface from an input file
+/*!
+ * This constructor wraps newPhase() and newKinetics()
+ *
+ * @param infile name of the input file
+ * @param name   name of the phase in the file. If this is the empty string, the first
+ *               phase in the file is used.
+ * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
+ *                 phases will be instantiated based on the phase definition.
+ * @returns an initialized Interface object.
+ */
+shared_ptr<Interface> newInterface(const std::string& infile,
+    const std::string& name, const std::vector<shared_ptr<Solution>>& adjacent);
+
+//! Create and initialize a new Interface from AnyMap objects
+/*!
+ * This constructor wraps newPhase() and newKinetics()
+ *
+ * @param phaseNode the node containing the phase definition (i.e. thermo model,
+ *     list of species, and initial state)
+ * @param rootNode the root node of the tree containing the phase definition, which
+ *     will be used as the default location from which to read species definitions.
+ * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
+ *                 phases will be instantiated based on the phase definition.
+ * @returns an initialized Interface object.
+ */
+shared_ptr<Interface> newInterface(AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),
+    const std::vector<shared_ptr<Solution>>& adjacent={});
+}
+
+#endif

include/cantera/base/Solution.h

@@ -17,13 +17,13 @@ class Kinetics;
 class Transport;
 
 //! A container class holding managers for all pieces defining a phase
-class Solution : public std::enable_shared_from_this<Solution>
+class Solution
 {
-private:
+protected:
     Solution();
 
 public:
-    ~Solution() {}
+    virtual ~Solution() {}
     Solution(const Solution&) = delete;
     Solution& operator=(const Solution&) = delete;
 
@@ -39,13 +39,13 @@ class Solution : public std::enable_shared_from_this<Solution>
     void setName(const std::string& name);
 
     //! Set the ThermoPhase object
-    void setThermo(shared_ptr<ThermoPhase> thermo);
+    virtual void setThermo(shared_ptr<ThermoPhase> thermo);
 
     //! Set the Kinetics object
-    void setKinetics(shared_ptr<Kinetics> kinetics);
+    virtual void setKinetics(shared_ptr<Kinetics> kinetics);
 
     //! Set the Transport object
-    void setTransport(shared_ptr<Transport> transport);
+    virtual void setTransport(shared_ptr<Transport> transport);
 
     //! Accessor for the ThermoPhase pointer
     shared_ptr<ThermoPhase> thermo() {
@@ -62,6 +62,25 @@ class Solution : public std::enable_shared_from_this<Solution>
         return m_transport;
     }
 
+    //! Add a phase adjacent to this phase. Usually this means a higher-dimensional
+    //! phase that participates in reactions in this phase.
+    void addAdjacent(shared_ptr<Solution> adjacent);
+
+    //! Get the Solution object for an adjacent phase by index
+    shared_ptr<Solution> adjacent(size_t i) {
+        return m_adjacent.at(i);
+    }
+
+    //! Get the Solution object for an adjacent phase by name
+    shared_ptr<Solution> adjacent(const std::string& name) {
+        return m_adjacentByName.at(name);
+    }
+
+    //! Get the number of adjacent phases
+    size_t nAdjacent() const {
+         return m_adjacent.size();
+    }
+
     AnyMap parameters(bool withInput=false) const;
 
     //! Access input data associated with header definition
@@ -79,9 +98,33 @@ class Solution : public std::enable_shared_from_this<Solution>
     shared_ptr<Kinetics> m_kinetics;  //!< Kinetics manager
     shared_ptr<Transport> m_transport;  //!< Transport manager
 
+    //! Adjacent phases, for access by index
+    std::vector<shared_ptr<Solution>> m_adjacent;
+
+    //! Adjacent phases, for access by name
+    std::map<std::string, shared_ptr<Solution>> m_adjacentByName;
+
     AnyMap m_header;  //!< Additional input fields; usually from a YAML input file
 };
 
+//! Create and initialize a new Solution from an input file
+/*!
+ * This constructor wraps newPhase(), newKinetics() and newTransportMgr() routines
+ * for initialization.
+ *
+ * @param infile name of the input file
+ * @param name   name of the phase in the file. If this is blank, the first phase
+ *               in the file is used.
+ * @param transport name of the transport model. If blank, the transport model specified
+ *                  in the phase definition is used.
+ * @param adjacent vector containing names of adjacent phases that participate in this
+ *                 phases kinetics. If empty, adjacent phases will be instantiated based
+ *                 on the phase definition.
+ * @returns an initialized Solution object.
+ */
+shared_ptr<Solution> newSolution(const std::string& infile, const std::string& name,
+    const std::string& transport, const std::vector<std::string>& adjacent);
+
 //! Create and initialize a new Solution manager from an input file
 /*!
  * This constructor wraps newPhase(), newKinetics() and
@@ -91,7 +134,8 @@ class Solution : public std::enable_shared_from_this<Solution>
  * @param name   name of the phase in the file.
  *               If this is blank, the first phase in the file is used.
  * @param transport name of the transport model.
- * @param adjacent vector containing adjacent solution objects.
+ * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
+ *                 phases will be instantiated based on the phase definition.
  * @returns an initialized Solution object.
  */
 shared_ptr<Solution> newSolution(const std::string& infile,
@@ -109,13 +153,19 @@ shared_ptr<Solution> newSolution(const std::string& infile,
  * @param rootNode the root node of the tree containing the phase definition, which
  *     will be used as the default location from which to read species definitions.
  * @param transport name of the transport model.
- * @param adjacent vector containing adjacent solution objects.
+ * @param adjacent vector containing adjacent Solution objects. If empty, adjacent
+ *                 phases will be instantiated based on the phase definition.
+ * @param related  vector of phases related to the same root Solution object. Used
+ *                 internally by newSolution() when creating complex interfaces where
+ *                 a phase may be adjacent to multiple other phases but should be
+ *                 instantiated only once.
  * @returns an initialized Solution object.
  */
-shared_ptr<Solution> newSolution(AnyMap& phaseNode,
-                                 const AnyMap& rootNode=AnyMap(),
-                                 const std::string& transport="",
-                                 const std::vector<shared_ptr<Solution>>& adjacent={});
+shared_ptr<Solution> newSolution(
+    const AnyMap& phaseNode, const AnyMap& rootNode=AnyMap(),
+    const std::string& transport="",
+    const std::vector<shared_ptr<Solution>>& adjacent={},
+    const std::map<std::string, shared_ptr<Solution>>& related={});
 
 }
 

include/cantera/base/YamlWriter.h

@@ -28,7 +28,7 @@ class YamlWriter
     void setHeader(const AnyMap& header);
 
     //! Include a phase definition for the specified Solution object
-    void addPhase(shared_ptr<Solution> soln);
+    void addPhase(shared_ptr<Solution> soln, bool includeAdjacent=true);
 
     //! Include a phase definition using the specified ThermoPhase, (optional)
     //! Kinetics, and (optional) Transport objects

include/cantera/thermo/EdgePhase.h

@@ -30,6 +30,14 @@ namespace Cantera
 class EdgePhase : public SurfPhase
 {
 public:
+    //! Construct and initialize an EdgePhase directly from an input file
+    /*!
+     * @param infile name of the input file
+     * @param id     name of the phase id in the file.
+     *               If this is blank, the first phase in the file is used.
+     */
+    explicit EdgePhase(const std::string& infile, const std::string& id="");
+
     //! Constructor
     /*!
      * @param n0  Surface site density (kmol m-1).

include/cantera/thermo/Phase.h

@@ -879,6 +879,7 @@ class Phase
     }
 
     //! Set root Solution holding all phase information
+    //! @deprecated This function has no effect. To be removed after Cantera 2.6.
     virtual void setRoot(std::shared_ptr<Solution> root);
 
     //! Converts a compositionMap to a vector with entries for each species
@@ -1031,9 +1032,6 @@ class Phase
 
     //! Entropy at 298.15 K and 1 bar of stable state pure elements (J kmol-1)
     vector_fp m_entropy298;
-
-    //! reference to Solution
-    std::weak_ptr<Solution> m_root;
 };
 
 }

include/cantera/thermo/ThermoFactory.h

@@ -139,7 +139,7 @@ ThermoPhase* newPhase(XML_Node& phase);
  *     which will be used as the default location from which to read species
  *     definitions.
  */
-unique_ptr<ThermoPhase> newPhase(AnyMap& phaseNode,
+unique_ptr<ThermoPhase> newPhase(const AnyMap& phaseNode,
                                  const AnyMap& rootNode=AnyMap());
 
 //! Create and Initialize a ThermoPhase object from an input file.
@@ -225,7 +225,7 @@ void importPhase(XML_Node& phase, ThermoPhase* th);
  *     which will be used as the default location from which to read species
  *     definitions.
  */
-void setupPhase(ThermoPhase& phase, AnyMap& phaseNode,
+void setupPhase(ThermoPhase& phase, const AnyMap& phaseNode,
                 const AnyMap& rootNode=AnyMap());
 
 //! Add the elements given in an XML_Node tree to the specified phase