[Doc] Warn about problems with multiphase equilibrium solver

include/cantera/equil/MultiPhase.h

@@ -28,6 +28,11 @@ class ThermoPhase;
  * thermodynamic object, in contrast to the ThermoPhase object, which is an
  * "intrinsic" thermodynamic object.
  *
+ * @warning The multiphase equilibrium solvers currently have a number of problems that
+ *     lead to solver failures or incorrect results for some inputs. See the
+ *     [list of issues on GitHub](https://github.com/Cantera/cantera/issues?q=is%3Aopen+is%3Aissue+label%3AEquilibrium)
+ *     for more information.
+ *
  * MultiPhase may be considered to be "upstream" of the ThermoPhase objects in
  * the sense that setting a property within MultiPhase, such as temperature,
  * pressure, or species mole number, affects the underlying ThermoPhase

interfaces/cython/cantera/mixture.pyx

@@ -10,7 +10,6 @@ from ._utils cimport *
 
 cdef class Mixture:
     """
-
     Class Mixture represents mixtures of one or more phases of matter.  To
     construct a mixture, supply a list of phases to the constructor, each
     paired with the number of moles for that phase::
@@ -30,6 +29,17 @@ cdef class Mixture:
     this phase. Mixture objects, on the other hand, represent the full
     extensive state.
 
+    .. caution::
+       The Mixture class exists mainly for the purpose of providing input for multiphase
+       equilibrium calculations. Its functionality for modifying the state of the
+       mixture and computing properties is quite limited. Mixture objects cannot be used
+       in conjunction with reactor networks.
+
+       Furthermore, the multiphase equilibrium solvers currently have a number of
+       problems that lead to solver failures or incorrect results for some inputs. See
+       the `list of issues on GitHub <https://github.com/Cantera/cantera/issues?q=is%3Aopen+is%3Aissue+label%3AEquilibrium>`_
+       for more information.
+
     Mixture objects are 'lightweight' in the sense that they do not store
     parameters needed to compute thermodynamic or kinetic properties of the
     phases. These are contained in the ('heavyweight') phase objects. Multiple

samples/python/multiphase/plasma_equilibrium.py

@@ -7,6 +7,11 @@ and multiple condensed phases.
 
 Requires: cantera >= 2.5.0, matplotlib >= 2.0
 
+.. warning::
+   The results of this example are incorrect due to known issues with the multiphase
+   equilibrium solver. See GitHub Issue
+   `#270 <https://github.com/Cantera/cantera/issues/270>`_.
+
 .. tags:: Python, equilibrium, multiphase, plasma, saving output
 """
 

test/python/test_equilibrium.py

@@ -157,6 +157,10 @@ class TestKOH_Equil(utilities.CanteraTest):
 
             data[i,1:] = self.mix.species_moles
 
+        # The reference values for this test are all completely non-physical, due to the
+        # VCS solver extrapolating thermo polynomials outside of their valid range. See
+        # https://github.com/Cantera/cantera/issues/270. The results show ice at
+        # temperatures of over 1000 K, and liquid water for temperatures of 2000-5000 K.
         self.compare(data, self.test_data_path / "koh-equil-TP.csv")
 
     @utilities.slow_test