Deprecate class IonsFromNeutralVPSSTP and class PDSS_IonsFromNeutral

This model has had a request for tests/examples out for many years (#267)
with no response, and the addition of consistency tests revealed multiple
errors in the implementation (documented in #1322). Further, there is no
mathematical description of the model or references to literature to use
as a reference in trying to correct any of these issues.

Resolves #1322.

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``

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/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/PDSS_IonsFromNeutral.h

@@ -30,13 +30,15 @@ class ThermoPhase;
  *
  * This class is for a single Ideal Gas species.
  *
+ * @deprecated To be removed after Cantera 3.0
+ *
  * @ingroup pdssthermo
  */
 class PDSS_IonsFromNeutral : public PDSS_Nondimensional
 {
 public:
     //! Default constructor
-    PDSS_IonsFromNeutral() = default;
+    PDSS_IonsFromNeutral();
 
     //! @name  Molar Thermodynamic Properties of the Species Standard State
     //! @{

src/thermo/IonsFromNeutralVPSSTP.cpp

@@ -28,6 +28,7 @@ namespace Cantera
 
 IonsFromNeutralVPSSTP::IonsFromNeutralVPSSTP(const string& inputFile, const string& id_)
 {
+    warn_deprecated("class IonsFromNeutralVPSSTP", "To be removed after Cantera 3.0");
     initThermoFile(inputFile, id_);
 }
 

src/thermo/PDSS_IonsFromNeutral.cpp

@@ -10,10 +10,16 @@
 #include "cantera/thermo/PDSS_IonsFromNeutral.h"
 #include "cantera/thermo/IonsFromNeutralVPSSTP.h"
 #include "cantera/base/stringUtils.h"
+#include "cantera/base/global.h"
 
 namespace Cantera
 {
 
+PDSS_IonsFromNeutral::PDSS_IonsFromNeutral()
+{
+    warn_deprecated("class PDSS_IonsFromNeutral", "To be removed after Cantera 3.0");
+}
+
 void PDSS_IonsFromNeutral::setParent(VPStandardStateTP* phase, size_t k)
 {
     neutralMoleculePhase_ = dynamic_cast<IonsFromNeutralVPSSTP&>(*phase).getNeutralMoleculePhase();

test/data/consistency-cases.yaml

@@ -373,6 +373,7 @@ ions-from-neutral-molecule:
   setup:
     file: thermo-models.yaml
     phase: ions-from-neutral-molecule
+    ignore-deprecations: true
     known-failures:
       g_eq_h_minus_Ts: "Inconsistent results. See GitHub Issue #1322"
       gk_eq_hk_minus_T_sk: "Inconsistent results. See GitHub Issue #1322"

test/python/test_convert.py

@@ -7,6 +7,8 @@
 import pytest
 
 from . import utilities
+from .utilities import allow_deprecated
+
 import cantera as ct
 from cantera import ck2yaml, cti2yaml, ctml2yaml, yaml2ck
 
@@ -1276,6 +1278,7 @@ def test_Maskell_solid_soln(self):
             yamlPhase.TP = T, ct.one_atm
             self.assertNear(ctmlPhase.density, yamlPhase.density)
 
+    @pytest.mark.usefixtures("allow_deprecated")
     def test_mock_ion(self):
         self.convert("mock_ion")
         ctmlPhase, yamlPhase = self.checkConversion("mock_ion")

test/thermo/consistency.cpp

@@ -67,6 +67,10 @@ class TestConsistency : public testing::TestWithParam<std::tuple<AnyMap, AnyMap>
         setup = get<0>(param);
         AnyMap state = get<1>(param);
 
+        if (setup.getBool("ignore-deprecations", false)) {
+            suppress_deprecation_warnings();
+        }
+
         // For efficiency, cache the instantiated phase object rather than recreating
         // it for every single test case.
         pair<string, string> key = {setup["file"].asString(), setup.getString("phase", "")};
@@ -92,6 +96,10 @@ class TestConsistency : public testing::TestWithParam<std::tuple<AnyMap, AnyMap>
         }
     }
 
+    ~TestConsistency() {
+        make_deprecation_warnings_fatal();
+    }
+
     void SetUp() {
         // See if we should skip this test specific test case
         if (setup.hasKey("known-failures")) {

test/thermo/phaseConstructors.cpp

@@ -78,6 +78,7 @@ shared_ptr<Species> make_const_cp_species(const std::string& name,
 
 TEST(IonsFromNeutralConstructor, fromScratch)
 {
+    suppress_deprecation_warnings();
     // Compare to the "ions-from-neutral-molecule" phase in "thermo-models.yaml"
     auto neutral = make_shared<MargulesVPSSTP>();
     auto sKCl = make_shomate_species("KCl(L)", "K:1 Cl:1", kcl_shomate_coeffs);
@@ -115,6 +116,7 @@ TEST(IonsFromNeutralConstructor, fromScratch)
     EXPECT_NEAR(p.enthalpy_mass(), -14738312.44316336, 1e-6);
     EXPECT_NEAR(mu[0], -4.66404010e+08, 1e1);
     EXPECT_NEAR(mu[1], -2.88157316e+06, 1e-1);
+    make_deprecation_warnings_fatal();
 }
 
 class ConstructFromScratch : public testing::Test

test/thermo/thermoFromYaml.cpp

@@ -198,6 +198,7 @@ TEST(ThermoFromYaml, DebyeHuckel_beta_ij)
 
 TEST(ThermoFromYaml, IonsFromNeutral)
 {
+    suppress_deprecation_warnings();
     auto thermo = newThermo("thermo-models.yaml", "ions-from-neutral-molecule");
     ASSERT_EQ((int) thermo->nSpecies(), 2);
     vector_fp mu(thermo->nSpecies());
@@ -208,10 +209,12 @@ TEST(ThermoFromYaml, IonsFromNeutral)
     EXPECT_NEAR(thermo->enthalpy_mass(), -14738312.44316336, 1e-6);
     EXPECT_NEAR(mu[0], -4.66404010e+08, 1e1);
     EXPECT_NEAR(mu[1], -2.88157316e+06, 1e-1);
+    make_deprecation_warnings_fatal();
 }
 
 TEST(ThermoFromYaml, IonsFromNeutral_fromString)
 {
+    suppress_deprecation_warnings();
     // A little different because we can't re-read the input file to get the
     // phase definition for the neutral phase
     std::ifstream infile("../data/thermo-models.yaml");
@@ -230,6 +233,7 @@ TEST(ThermoFromYaml, IonsFromNeutral_fromString)
     EXPECT_NEAR(thermo->enthalpy_mass(), -14738312.44316336, 1e-6);
     EXPECT_NEAR(mu[0], -4.66404010e+08, 1e1);
     EXPECT_NEAR(mu[1], -2.88157316e+06, 1e-1);
+    make_deprecation_warnings_fatal();
 }
 
 TEST(ThermoFromYaml, IdealSolnGas_liquid)

test/thermo/thermoToYaml.cpp

@@ -143,13 +143,15 @@ TEST_F(ThermoToYaml, Edge)
 
 TEST_F(ThermoToYaml, IonsFromNeutral)
 {
+    suppress_deprecation_warnings();
     setup("thermo-models.yaml", "ions-from-neutral-molecule");
     EXPECT_EQ(data["neutral-phase"], "KCl-neutral");
     EXPECT_FALSE(eosData[0].hasKey("special-species"));
     EXPECT_TRUE(eosData[1]["special-species"].asBool());
     auto multipliers = eosData[1]["multipliers"].asMap<double>();
     EXPECT_EQ(multipliers.size(), (size_t) 1);
     EXPECT_DOUBLE_EQ(multipliers["KCl(l)"], 1.5);
+    make_deprecation_warnings_fatal();
 }
 
 TEST_F(ThermoToYaml, Margules)
@@ -477,10 +479,12 @@ TEST_F(ThermoYamlRoundTrip, IdealSolutionVpss)
 
 TEST_F(ThermoYamlRoundTrip, IonsFromNeutral)
 {
+    suppress_deprecation_warnings();
     roundtrip("thermo-models.yaml", "ions-from-neutral-molecule",
               {"KCl-neutral"});
     skip_cp = true; // Not implemented for IonsFromNeutral
     compareThermo(500, 3e5);
+    make_deprecation_warnings_fatal();
 }
 
 TEST_F(ThermoYamlRoundTrip, LatticeSolid)