Deprecate unused, untested, and obsolete code

doc/SConscript

@@ -2,7 +2,9 @@
 from collections import namedtuple
 from os.path import join as pjoin
 import os
+import subprocess
 from buildutils import *
+from SCons import Errors
 
 Import('env', 'build', 'install')
 
@@ -107,12 +109,16 @@ if localenv['doxygen_docs']:
             '#/build/docs/doxygen/html', exclude=['\\.map', '\\.md5'])
 
 if localenv['sphinx_docs']:
-    localenv['SPHINXBUILD'] = Dir('#build/docs/sphinx')
-    localenv['SPHINXSRC'] = Dir('sphinx')
-
-    sphinxdocs = build(localenv.Command('${SPHINXBUILD}/html/index.html',
-        'sphinx/conf.py',
-        '${sphinx_cmd} ${sphinx_options} -b html -d ${SPHINXBUILD}/doctrees ${SPHINXSRC} ${SPHINXBUILD}/html'))
+    def build_sphinx(target, source, env):
+        cmd = [env['sphinx_cmd']] + env['sphinx_options'].split()
+        cmd += ('-b', 'html', '-d', 'build/docs/sphinx/doctrees', 'doc/sphinx',
+                'build/docs/sphinx/html')
+        code = subprocess.call(cmd, env=env['ENV'])
+        if code:
+            raise Errors.BuildError(target, action=env['sphinx_cmd'])
+
+    sphinxdocs = build(localenv.Command('#build/doc/sphinx/html/index.html',
+        'sphinx/conf.py', build_sphinx))
     env.Alias('sphinx', sphinxdocs)
     env.Depends(sphinxdocs, env['python_module'])
 

doc/sphinx/yaml/phases.rst

@@ -667,6 +667,10 @@ expressed in terms of combinations of the ionic species that represent neutral
 molecules, as
 `described here <https://cantera.org/documentation/dev/doxygen/html/d7/d4a/classCantera_1_1IonsFromNeutralVPSSTP.html#details>`__.
 
+.. deprecated:: 3.0
+
+    This phase model is deprecated and will be removed after Cantera 3.0.
+
 Additional fields:
 
 ``neutral-phase``
@@ -761,6 +765,10 @@ Example::
 A condensed phase non-ideal solution with two species, as
 `described here <https://cantera.org/documentation/dev/doxygen/html/dd/d3a/classCantera_1_1MaskellSolidSolnPhase.html#details>`__.
 
+.. deprecated:: 3.0
+
+    This phase model is deprecated and will be removed after Cantera 3.0.
+
 Additional fields:
 
 ``excess-enthalpy``
@@ -921,7 +929,7 @@ Example::
     - name: isotropic-electron-energy-plasma
       thermo: plasma
       kinetics: gas
-      transport: Ion
+      transport: ionized-gas
       electron-energy-distribution:
         type: isotropic
         shape-factor: 2.0
@@ -930,7 +938,7 @@ Example::
     - name: discretized-electron-energy-plasma
       thermo: plasma
       kinetics: gas
-      transport: Ion
+      transport: ionized-gas
       electron-energy-distribution:
         type: discretized
         energy-levels: [0.0, 0.1, 1.0, 10.0]

doc/sphinx/yaml/species.rst

@@ -383,6 +383,10 @@ A species equation of state model used with the ``ions-from-neutral-molecule``
 phase model, as
 `described here <https://cantera.org/documentation/dev/doxygen/html/d5/df4/classCantera_1_1PDSS__IonsFromNeutral.html#details>`__.
 
+.. deprecated:: 3.0
+
+    This species thermo model is deprecated and will be removed after Cantera 3.0.
+
 Additional fields:
 
 ``special-species``

include/cantera/base/FactoryBase.h

@@ -97,8 +97,9 @@ class Factory : public FactoryBase {
         } else if (m_synonyms.count(name)) {
             return m_synonyms.at(name);
         } else if (m_deprecated_names.count(name)) {
-            warn_deprecated(name,
-                fmt::format("Use '{}' instead.", m_deprecated_names.at(name)));
+            warn_deprecated("FactoryBase::canonicalize",
+                fmt::format("Model name '{}' is deprecated. Use '{}' instead.",
+                            name, m_deprecated_names.at(name)));
             return m_deprecated_names.at(name);
         } else {
             throw CanteraError("Factory::canonicalize", "No such type: '{}'", name);

include/cantera/kinetics/EdgeKinetics.h

@@ -28,7 +28,7 @@ class EdgeKinetics : public InterfaceKinetics
     }
 
     virtual std::string kineticsType() const {
-        return "Edge";
+        return "edge";
     }
 };
 }

include/cantera/kinetics/GasKinetics.h

@@ -34,7 +34,7 @@ class GasKinetics : public BulkKinetics
     GasKinetics(ThermoPhase* thermo);
 
     virtual std::string kineticsType() const {
-        return "Gas";
+        return "gas";
     }
 
     virtual void getThirdBodyConcentrations(double* concm);

include/cantera/kinetics/InterfaceKinetics.h

@@ -75,7 +75,7 @@ class InterfaceKinetics : public Kinetics
     virtual void resizeReactions();
 
     virtual std::string kineticsType() const {
-        return "Surf";
+        return "surface";
     }
 
     //! Set the electric potential in the nth phase

include/cantera/kinetics/Kinetics.h

@@ -128,8 +128,10 @@ class Kinetics
     //! Identifies the Kinetics manager type.
     //! Each class derived from Kinetics should override this method to return
     //! a meaningful identifier.
+    //! @since  Starting in Cantera 3.0, the name returned by this method corresponds
+    //!     to the canonical name used in the YAML input format.
     virtual std::string kineticsType() const {
-        return "None";
+        return "none";
     }
 
     //! Finalize Kinetics object and associated objects
@@ -307,6 +309,8 @@ class Kinetics
      *
      * @param nm   Input string name of the species
      * @param ph   Input string name of the phase.
+     * @deprecated To be removed after Cantera 3.0. Species names should be unique
+     *     across all phases.
      */
     size_t kineticsSpeciesIndex(const std::string& nm,
                                 const std::string& ph) const;
@@ -1010,6 +1014,8 @@ class Kinetics
      *
      * @param i   reaction index
      * @since  Method returned magic number prior to Cantera 3.0.
+     * @deprecated  To be removed after Cantera 3.0. Replace with
+     *     `kin->reaction(i)->type()`
      */
     virtual std::string reactionType(size_t i) const;
 
@@ -1036,13 +1042,19 @@ class Kinetics
      * Return a string representing the reaction.
      *
      * @param i   reaction index
+     * @deprecated To be removed after Cantera 3.0. Replace with
+     *     `kin->reaction(i)->equation()`.
      */
     std::string reactionString(size_t i) const;
 
     //! Returns a string containing the reactants side of the reaction equation.
+    //! @deprecated To be removed after Cantera 3.0. Replace with
+    //!     `kin->reaction(i)->reactantString()`
     std::string reactantString(size_t i) const;
 
     //! Returns a string containing the products side of the reaction equation.
+    //! @deprecated To be removed after Cantera 3.0. Replace with
+    //!     `kin->reaction(i)->productString()`
     std::string productString(size_t i) const;
 
     /**
@@ -1238,6 +1250,7 @@ class Kinetics
      *     reaction mechanism
      * @param phase_data Output array where the values for the the specified
      *     phase are to be written.
+     * @deprecated Unused. To be removed after Cantera 3.0.
      */
     void selectPhase(const double* data, const ThermoPhase* phase,
                      double* phase_data);
@@ -1255,6 +1268,7 @@ class Kinetics
 
     //! Calculate the reaction enthalpy of a reaction which
     //! has not necessarily been added into the Kinetics object
+    //! @deprecated To be removed after Cantera 3.0
     virtual double reactionEnthalpy(const Composition& reactants,
                                     const Composition& products);
 

include/cantera/thermo/BinarySolutionTabulatedThermo.h

@@ -174,7 +174,7 @@ class BinarySolutionTabulatedThermo : public IdealSolidSolnPhase
     explicit BinarySolutionTabulatedThermo(const std::string& infile="", const std::string& id="");
 
     virtual std::string type() const {
-        return "BinarySolutionTabulatedThermo";
+        return "binary-solution-tabulated";
     }
 
     virtual bool addSpecies(shared_ptr<Species> spec);

include/cantera/thermo/DebyeHuckel.h

@@ -429,7 +429,7 @@ class DebyeHuckel : public MolalityVPSSTP
     //! @{
 
     virtual std::string type() const {
-        return "DebyeHuckel";
+        return "Debye-Huckel";
     }
 
     //! @}

include/cantera/thermo/EdgePhase.h

@@ -39,7 +39,7 @@ class EdgePhase : public SurfPhase
     explicit EdgePhase(const std::string& infile="", const std::string& id="");
 
     virtual std::string type() const {
-        return "Edge";
+        return "edge";
     }
 };
 }

include/cantera/thermo/HMWSoln.h

@@ -797,7 +797,7 @@ class HMWSoln : public MolalityVPSSTP
     //! @{
 
     virtual std::string type() const {
-        return "HMWSoln";
+        return "HMW-electrolyte";
     }
 
     //! @}

include/cantera/thermo/IdealGasPhase.h

@@ -262,7 +262,7 @@ class IdealGasPhase: public ThermoPhase
                            const std::string& id="");
 
     virtual std::string type() const {
-        return "IdealGas";
+        return "ideal-gas";
     }
 
     virtual bool isIdeal() const {

include/cantera/thermo/IdealMolalSoln.h

@@ -80,7 +80,7 @@ class IdealMolalSoln : public MolalityVPSSTP
                             const std::string& id="");
 
     virtual std::string type() const {
-        return "IdealMolalSoln";
+        return "ideal-molal-solution";
     }
 
     virtual bool isIdeal() const {

include/cantera/thermo/IdealSolidSolnPhase.h

@@ -57,7 +57,7 @@ class IdealSolidSolnPhase : public ThermoPhase
                                  const std::string& id="");
 
     virtual std::string type() const {
-        return "IdealSolidSoln";
+        return "ideal-condensed";
     }
 
     virtual bool isIdeal() const {

include/cantera/thermo/IonsFromNeutralVPSSTP.h

@@ -63,6 +63,8 @@ enum IonSolnType_enumType {
  *
  *  This object can translate between any of the four mole fraction
  *  representations.
+ *
+ *  @deprecated To be removed after Cantera 3.0.
  */
 class IonsFromNeutralVPSSTP : public GibbsExcessVPSSTP
 {

include/cantera/thermo/LatticePhase.h

@@ -193,7 +193,7 @@ class LatticePhase : public ThermoPhase
                           const std::string& id="");
 
     virtual std::string type() const {
-        return "Lattice";
+        return "lattice";
     }
 
     virtual bool isCompressible() const {

include/cantera/thermo/LatticeSolidPhase.h

@@ -108,7 +108,7 @@ class LatticeSolidPhase : public ThermoPhase
     LatticeSolidPhase() = default;
 
     virtual std::string type() const {
-        return "LatticeSolid";
+        return "compound-lattice";
     }
 
     //! String indicating the mechanical phase of the matter in this Phase.

include/cantera/thermo/MaskellSolidSolnPhase.h

@@ -23,11 +23,14 @@ namespace Cantera
  * 231-235, 1983.
  *
  * @ingroup thermoprops
+ *
+ * @deprecated To be removed after Cantera 3.0. This class has numerous thermodynamic
+ *    inconsistencies. See https://github.com/Cantera/cantera/issues/1321.
  */
 class MaskellSolidSolnPhase : public VPStandardStateTP
 {
 public:
-    MaskellSolidSolnPhase() = default;
+    MaskellSolidSolnPhase();
 
     virtual std::string type() const {
         return "MaskellSolidsoln";

include/cantera/thermo/MetalPhase.h

@@ -26,7 +26,7 @@ class MetalPhase : public ThermoPhase
     // Overloaded methods of class ThermoPhase
 
     virtual std::string type() const {
-        return "Metal";
+        return "electron-cloud";
     }
 
     virtual bool isCompressible() const {

include/cantera/thermo/MixtureFugacityTP.h

@@ -115,10 +115,6 @@ class MixtureFugacityTP : public ThermoPhase
      */
     virtual int reportSolnBranchActual() const;
 
-    virtual void getdlnActCoeffdlnN_diag(doublereal* dlnActCoeffdlnN_diag) const {
-        throw NotImplementedError("MixtureFugacityTP::getdlnActCoeffdlnN_diag");
-    }
-
     //! @}
     //! @name Molar Thermodynamic properties
     //! @{

include/cantera/thermo/PDSS.h

@@ -247,18 +247,22 @@ class PDSS
 
     //! Get the difference in the standard state enthalpy
     //! between the current pressure and the reference pressure, p0.
+    //! @deprecated To be removed after Cantera 3.0
     virtual doublereal enthalpyDelp_mole() const;
 
     //! Get the difference in the standard state entropy between
     //! the current pressure and the reference pressure, p0
+    //! @deprecated To be removed after Cantera 3.0
     virtual doublereal entropyDelp_mole() const;
 
     //! Get the difference in the standard state Gibbs free energy
     //! between the current pressure and the reference pressure, p0.
+    //! @deprecated To be removed after Cantera 3.0
     virtual doublereal gibbsDelp_mole() const;
 
     //! Get the difference in standard state heat capacity
     //! between the current pressure and the reference pressure, p0.
+    //! @deprecated To be removed after Cantera 3.0
     virtual doublereal cpDelp_mole() const;
 
     //! @}
@@ -360,18 +364,10 @@ class PDSS
     /*!
      * @param  temp     Temperature (Kelvin)
      * @param  rho      Density (kg m-3)
-     * @deprecated  To be removed after Cantera 3.0; renamed to setState_TD()
+     * @deprecated  To be removed after Cantera 3.0
      */
     virtual void setState_TR(doublereal temp, doublereal rho);
 
-    //! Set the internal temperature and density
-    /*!
-     * @param  temp     Temperature (Kelvin)
-     * @param  rho      Density (kg m-3)
-     * @since  New in Cantera 3.0.
-     */
-    virtual void setState_TD(double temp, double rho);
-
     //! critical temperature
     virtual doublereal critTemperature() const;
 
@@ -440,6 +436,7 @@ class PDSS
      * @param minTemp   output - Minimum temperature
      * @param maxTemp   output - Maximum temperature
      * @param refPressure output - reference pressure (Pa).
+     * @deprecated To be removed after Cantera 3.0. Use getParameters() instead.
      */
     virtual void reportParams(size_t& kindex, int& type, doublereal* const c,
                               doublereal& minTemp, doublereal& maxTemp,

include/cantera/thermo/PDSS_ConstVol.h

@@ -39,7 +39,7 @@ class PDSS_ConstVol : public PDSS_Nondimensional
     virtual void setPressure(doublereal pres);
     virtual void setTemperature(doublereal temp);
     virtual void setState_TP(doublereal temp, doublereal pres);
-    virtual void setState_TD(double temp, double rho);
+    virtual void setState_TR(double temp, double rho);
     virtual doublereal satPressure(doublereal t);
 
     //! @}

include/cantera/thermo/PDSS_HKFT.h

@@ -45,6 +45,7 @@ class PDSS_HKFT : public PDSS_Molar
      *  Note this is just an extra routine to check the arithmetic
      *
      * @returns the species standard state enthalpy in J kmol-1
+     * @deprecated To be removed after Cantera 3.0
      */
     doublereal enthalpy_mole2() const;
 
@@ -160,6 +161,7 @@ class PDSS_HKFT : public PDSS_Molar
     //! between the reference state at Tr, Pr and T,P
     /*!
      *  This is an extra routine that was added to check the arithmetic
+     * @deprecated To be removed after Cantera 3.0
      */
     doublereal deltaH() const;
 

include/cantera/thermo/PDSS_IdealGas.h

@@ -43,7 +43,7 @@ class PDSS_IdealGas : public PDSS_Nondimensional
     virtual void setPressure(doublereal pres);
     virtual void setTemperature(doublereal temp);
     virtual void setState_TP(doublereal temp, doublereal pres);
-    virtual void setState_TD(double temp, double rho);
+    virtual void setState_TR(double temp, double rho);
 
     //! @}
     //! @name Initialization of the Object