From 14b9454819ca894086046519a8c5b27e72c81525 Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Sat, 14 May 2016 16:10:10 -0400
Subject: [PATCH] [C++] Clean up of top-level headers

These headers should only include general functionality, i.e. base classes and
factory methods. Users working directly with derived types can include the
relevant headers directly.

Deprecate some top-level headers which are not really useful.
---
 doc/sphinx/cxx-guide/demo1a.cpp                |  1 +
 doc/sphinx/cxx-guide/demo1b.cpp                |  6 +++---
 doc/sphinx/cxx-guide/headers.rst               | 13 ++++++++-----
 include/cantera/Edge.h                         |  5 +++--
 include/cantera/Interface.h                    |  2 ++
 include/cantera/electrolyteThermo.h            |  3 +++
 include/cantera/integrators.h                  |  3 +++
 include/cantera/kinetics.h                     | 13 +++++++++----
 include/cantera/numerics.h                     |  8 +++++++-
 include/cantera/onedim.h                       |  5 +----
 include/cantera/surface.h                      |  7 +++++++
 include/cantera/thermo.h                       | 18 ++++++------------
 include/cantera/transport.h                    | 10 +++-------
 samples/cxx/LiC6_electrode/LiC6_electrode.cpp  |  2 +-
 test/kinetics/rates.cpp                        |  3 +++
 test/thermo/phaseConstructors.cpp              |  2 +-
 test_problems/cathermo/stoichSub/stoichSub.cpp |  5 +----
 .../cathermo/testWaterTP/testWaterSSTP.cpp     |  4 +---
 test_problems/diamondSurf/runDiamond.cpp       |  2 ++
 .../mixGasTransport/mixGasTransport.cpp        |  1 +
 .../multiGasTransport/multiGasTransport.cpp    |  2 +-
 test_problems/pureFluidTest/testPureWater.cpp  |  1 +
 .../stoichSolidKinetics.cpp                    |  6 ++----
 23 files changed, 70 insertions(+), 52 deletions(-)

diff --git a/doc/sphinx/cxx-guide/demo1a.cpp b/doc/sphinx/cxx-guide/demo1a.cpp
index 05a87975b..e0883bb5d 100644
--- a/doc/sphinx/cxx-guide/demo1a.cpp
+++ b/doc/sphinx/cxx-guide/demo1a.cpp
@@ -1,4 +1,5 @@
 #include "cantera/thermo.h"
+#include <iostream>
 
 using namespace Cantera;
 
diff --git a/doc/sphinx/cxx-guide/demo1b.cpp b/doc/sphinx/cxx-guide/demo1b.cpp
index c82db13a6..1923cff79 100644
--- a/doc/sphinx/cxx-guide/demo1b.cpp
+++ b/doc/sphinx/cxx-guide/demo1b.cpp
@@ -1,6 +1,6 @@
-#include "cantera/thermo/ThermoFactory.h"
-#include "cantera/kinetics/KineticsFactory.h"
-#include "cantera/transport/TransportFactory.h"
+#include "cantera/thermo.h"
+#include "cantera/kinetics.h"
+#include "cantera/transport.h"
 
 using namespace Cantera;
 
diff --git a/doc/sphinx/cxx-guide/headers.rst b/doc/sphinx/cxx-guide/headers.rst
index f9ff9f6a8..309ab8467 100644
--- a/doc/sphinx/cxx-guide/headers.rst
+++ b/doc/sphinx/cxx-guide/headers.rst
@@ -20,10 +20,8 @@ included by the Cantera core. The headers and their functions are:
     ODE Integrators.
 
 ``kinetics.h``
-    Chemical kinetics.
-
-``numerics.h``
-    Classes for matrices.
+    Base kinetics classes and functions for creating :ct:`Kinetics` objects from
+    input files.
 
 ``onedim.h``
     One-dimensional reacting flows.
@@ -31,8 +29,13 @@ included by the Cantera core. The headers and their functions are:
 ``reactionpaths.h``
     Reaction path diagrams.
 
+``thermo.h``
+    Base thermodynamic classes and functions for creating :ct:`ThermoPhase`
+    objects from input files.
+
 ``transport.h``
-    Transport properties.
+    Base transport property classes and functions for creating :ct:`Transport`
+    objects from input files.
 
 ``zerodim.h``
     Zero-dimensional reactor networks.
diff --git a/include/cantera/Edge.h b/include/cantera/Edge.h
index 54b85d6c5..afcff46fc 100644
--- a/include/cantera/Edge.h
+++ b/include/cantera/Edge.h
@@ -2,9 +2,10 @@
 #ifndef CXX_EDGE
 #define CXX_EDGE
 
-#include "thermo.h"
-#include "kinetics/EdgeKinetics.h"
+#include "thermo/ThermoFactory.h"
 #include "kinetics/importKinetics.h"
+#include "kinetics/EdgeKinetics.h"
+#include "thermo/EdgePhase.h"
 
 namespace Cantera
 {
diff --git a/include/cantera/Interface.h b/include/cantera/Interface.h
index 837197c19..39326d6e1 100644
--- a/include/cantera/Interface.h
+++ b/include/cantera/Interface.h
@@ -7,6 +7,8 @@
 
 #include "thermo.h"
 #include "kinetics.h"
+#include "cantera/thermo/SurfPhase.h"
+#include "cantera/kinetics/InterfaceKinetics.h"
 
 namespace Cantera
 {
diff --git a/include/cantera/electrolyteThermo.h b/include/cantera/electrolyteThermo.h
index 534a3e462..2aa2e78f1 100644
--- a/include/cantera/electrolyteThermo.h
+++ b/include/cantera/electrolyteThermo.h
@@ -4,11 +4,14 @@
  * Support for thermo property calculation from C++ application programs.
  * This header file includes several headers from the Cantera kernel needed
  * to evaluate thermo properties.
+ * @deprecated To be removed after Cantera 2.3. Include relevant headers directly.
  */
 
 #ifndef CT_ELECTROLYTETHERMO_INCL
 #define CT_ELECTROLYTETHERMO_INCL
 
+#pragma message "Deprecated. electrolyteThermo.h will be removed after Cantera 2.3. Include relevant headers directly."
+
 #include "thermo/electrolytes.h"
 #include "thermo/MolalityVPSSTP.h"
 #include "thermo/VPStandardStateTP.h"
diff --git a/include/cantera/integrators.h b/include/cantera/integrators.h
index f62d0b6fb..79ab687f7 100644
--- a/include/cantera/integrators.h
+++ b/include/cantera/integrators.h
@@ -1,10 +1,13 @@
 /**
  * @file integrators.h
  * ODE integrators. Currently, the only integrator is CVODE.
+ * @deprecated To be removed after Cantera 2.3. Include relevant headers directly.
  */
 #ifndef CT_INTEG_H_INCL
 #define CT_INTEG_H_INCL
 
+#pragma message "Deprecated. integrators.h will be removed after Cantera 2.3. Include relevant headers directly."
+
 #include "numerics/Integrator.h"
 #include "numerics/DAE_Solver.h"
 #include "numerics/IDA_Solver.h"
diff --git a/include/cantera/kinetics.h b/include/cantera/kinetics.h
index 743a6b17a..0740f148b 100644
--- a/include/cantera/kinetics.h
+++ b/include/cantera/kinetics.h
@@ -1,11 +1,16 @@
+/**
+ * @file kinetics.h
+ *
+ * Support for chemical kinetics calculation from C++ application programs.
+ * This header file includes headers needed to create and use objects for
+ * evaluating chemical kinetic mechanisms.
+ */
+
 #ifndef CXX_INCL_KINETICS
 #define CXX_INCL_KINETICS
 
-#include "thermo.h"
-
 #include "kinetics/Kinetics.h"
-#include "kinetics/InterfaceKinetics.h"
-#include "kinetics/GasKinetics.h"
+#include "kinetics/Reaction.h"
 #include "kinetics/KineticsFactory.h"
 #include "kinetics/importKinetics.h"
 
diff --git a/include/cantera/numerics.h b/include/cantera/numerics.h
index 4950b6d19..392f155f0 100644
--- a/include/cantera/numerics.h
+++ b/include/cantera/numerics.h
@@ -1,9 +1,15 @@
+/**
+ * @file numerics.h
+ * @deprecated To be removed after Cantera 2.3. Include relevant headers
+ *     directly.
+ */
 #ifndef CT_NUM_H_INCL
 #define CT_NUM_H_INCL
 
+#pragma message "Deprecated. numerics.h will be removed after Cantera 2.3. Include relevant headers directly."
+
 #include "numerics/DenseMatrix.h"
 #include "numerics/BandMatrix.h"
 #include "numerics/SquareMatrix.h"
-#include "numerics/NonlinearSolver.h"
 
 #endif
diff --git a/include/cantera/onedim.h b/include/cantera/onedim.h
index f24f7c705..3a62ccead 100644
--- a/include/cantera/onedim.h
+++ b/include/cantera/onedim.h
@@ -12,11 +12,8 @@
 #define CT_INCL_ONEDIM_H
 
 #include "oneD/Sim1D.h"
-#include "oneD/OneDim.h"
 #include "oneD/Domain1D.h"
 #include "oneD/Inlet1D.h"
-#include "oneD/MultiNewton.h"
-#include "oneD/MultiJac.h"
 #include "oneD/StFlow.h"
-#endif
 
+#endif
diff --git a/include/cantera/surface.h b/include/cantera/surface.h
index d3d16ab47..71dc6cbc3 100644
--- a/include/cantera/surface.h
+++ b/include/cantera/surface.h
@@ -1,6 +1,13 @@
+/**
+ * @file surface.h
+ * @deprecated To be removed after Cantera 2.3.
+ */
+
 #ifndef CT_SURFACE_INCL
 #define CT_SURFACE_INCL
 
+#pragma message "Deprecated. surface.h will be removed after Cantera 2.3. Include relevant headers directly."
+
 #include "thermo/SurfPhase.h"
 #include "kinetics/InterfaceKinetics.h"
 
diff --git a/include/cantera/thermo.h b/include/cantera/thermo.h
index 9d93f4ef5..f405025dd 100644
--- a/include/cantera/thermo.h
+++ b/include/cantera/thermo.h
@@ -2,23 +2,17 @@
  * @file thermo.h
  *
  * Support for thermo property calculation from C++ application programs.
- * This header file includes several headers from the Cantera kernel needed
- * to evaluate thermo properties.
+ * This header file includes several headers needed to create and use objects
+ * which evaluate thermo properties.
  */
 
 #ifndef CT_THERMO_INCL
 #define CT_THERMO_INCL
 
+#include "thermo/ThermoPhase.h"
+#include "thermo/Species.h"
 #include "thermo/ThermoFactory.h"
-#include "thermo/SurfPhase.h"
-#include "thermo/EdgePhase.h"
-
-#include "thermo/GibbsExcessVPSSTP.h"
-#include "thermo/MargulesVPSSTP.h"
-
-#include "electrolyteThermo.h"
-
-#include "thermo/LatticePhase.h"
-#include "thermo/LatticeSolidPhase.h"
+#include "thermo/SpeciesThermoInterpType.h"
+#include "thermo/SpeciesThermoFactory.h"
 
 #endif
diff --git a/include/cantera/transport.h b/include/cantera/transport.h
index cebb14171..385e42fe2 100644
--- a/include/cantera/transport.h
+++ b/include/cantera/transport.h
@@ -2,17 +2,13 @@
  * @file transport.h
  *
  * Support for transport property calculation from C++ application programs.
- * This header file includes several headers from the Cantera kernel needed
- * to evaluate transport properties.
+ * This header file includes headers needed to create and use objects for
+ * evaluating transport properties.
  */
 
 #ifndef CT_TRANSPORT_INCL
 #define CT_TRANSPORT_INCL
 
 #include "transport/TransportFactory.h"
-#include "transport/DustyGasTransport.h"
-#include "transport/MultiTransport.h"
-#include "transport/MixTransport.h"
-#include "transport/LiquidTransport.h"
-#include "transport/HighPressureGasTransport.h"
+
 #endif
diff --git a/samples/cxx/LiC6_electrode/LiC6_electrode.cpp b/samples/cxx/LiC6_electrode/LiC6_electrode.cpp
index b83cc79bc..b1a71e6bf 100644
--- a/samples/cxx/LiC6_electrode/LiC6_electrode.cpp
+++ b/samples/cxx/LiC6_electrode/LiC6_electrode.cpp
@@ -1,5 +1,5 @@
 #include "cantera/thermo.h"
-#include "cantera/thermo/RedlichKisterVPSSTP.h"
+#include <iostream>
 #include <fstream>
 
 using namespace Cantera;
diff --git a/test/kinetics/rates.cpp b/test/kinetics/rates.cpp
index c655bca7d..b7048f175 100644
--- a/test/kinetics/rates.cpp
+++ b/test/kinetics/rates.cpp
@@ -1,6 +1,9 @@
 #include "gtest/gtest.h"
+#include "cantera/thermo.h"
 #include "cantera/kinetics.h"
 #include "cantera/thermo/IdealGasPhase.h"
+#include "cantera/thermo/SurfPhase.h"
+#include "cantera/kinetics/GasKinetics.h"
 
 namespace Cantera
 {
diff --git a/test/thermo/phaseConstructors.cpp b/test/thermo/phaseConstructors.cpp
index 51ce0664c..6502a4b83 100644
--- a/test/thermo/phaseConstructors.cpp
+++ b/test/thermo/phaseConstructors.cpp
@@ -1,6 +1,6 @@
 #include "gtest/gtest.h"
-#include "cantera/thermo/FixedChemPotSSTP.h"
 #include "cantera/thermo/ThermoFactory.h"
+#include "cantera/thermo/FixedChemPotSSTP.h"
 #include "cantera/thermo/NasaPoly2.h"
 #include "cantera/thermo/IdealGasPhase.h"
 #include "cantera/base/ctml.h"
diff --git a/test_problems/cathermo/stoichSub/stoichSub.cpp b/test_problems/cathermo/stoichSub/stoichSub.cpp
index ad270131f..e69e0032d 100644
--- a/test_problems/cathermo/stoichSub/stoichSub.cpp
+++ b/test_problems/cathermo/stoichSub/stoichSub.cpp
@@ -3,12 +3,9 @@
  *  @file HMW_graph_1.cpp
  */
 
-#include "cantera/thermo.h"
 #include "cantera/thermo/StoichSubstance.h"
-
 #include "TemperatureTable.h"
-
-#include <cstdio>
+#include <iostream>
 
 using namespace std;
 using namespace Cantera;
diff --git a/test_problems/cathermo/testWaterTP/testWaterSSTP.cpp b/test_problems/cathermo/testWaterTP/testWaterSSTP.cpp
index 7236e4a9b..5a9017859 100644
--- a/test_problems/cathermo/testWaterTP/testWaterSSTP.cpp
+++ b/test_problems/cathermo/testWaterTP/testWaterSSTP.cpp
@@ -1,7 +1,5 @@
-#include "cantera/thermo.h"
 #include "cantera/thermo/WaterSSTP.h"
-
-#include <cstdio>
+#include <iostream>
 
 using namespace std;
 using namespace Cantera;
diff --git a/test_problems/diamondSurf/runDiamond.cpp b/test_problems/diamondSurf/runDiamond.cpp
index fe055466e..e44f34c28 100644
--- a/test_problems/diamondSurf/runDiamond.cpp
+++ b/test_problems/diamondSurf/runDiamond.cpp
@@ -10,7 +10,9 @@
 // user-friendly. This could be rewritten using class Interface to
 // make things simpler.
 
+#include "cantera/thermo.h"
 #include "cantera/kinetics.h"
+#include "cantera/kinetics/InterfaceKinetics.h"
 
 using namespace std;
 using namespace Cantera;
diff --git a/test_problems/mixGasTransport/mixGasTransport.cpp b/test_problems/mixGasTransport/mixGasTransport.cpp
index 58230b734..452c3c96c 100644
--- a/test_problems/mixGasTransport/mixGasTransport.cpp
+++ b/test_problems/mixGasTransport/mixGasTransport.cpp
@@ -18,6 +18,7 @@
 // perhaps, later, an analytical solution could be added
 
 #include "cantera/transport.h"
+#include "cantera/transport/MixTransport.h"
 #include "cantera/IdealGasMix.h"
 #include <cstdio>
 
diff --git a/test_problems/multiGasTransport/multiGasTransport.cpp b/test_problems/multiGasTransport/multiGasTransport.cpp
index 37094db81..8acf357a4 100644
--- a/test_problems/multiGasTransport/multiGasTransport.cpp
+++ b/test_problems/multiGasTransport/multiGasTransport.cpp
@@ -18,8 +18,8 @@
 // perhaps, later, an analytical solution could be added
 
 #include "cantera/transport.h"
+#include "cantera/transport/MultiTransport.h"
 #include "cantera/IdealGasMix.h"
-#include "cantera/transport/TransportFactory.h"
 
 #include <cstdio>
 
diff --git a/test_problems/pureFluidTest/testPureWater.cpp b/test_problems/pureFluidTest/testPureWater.cpp
index b68faf3fd..95c38d094 100644
--- a/test_problems/pureFluidTest/testPureWater.cpp
+++ b/test_problems/pureFluidTest/testPureWater.cpp
@@ -1,4 +1,5 @@
 #include "cantera/PureFluid.h"
+#include "cantera/thermo.h"
 #include <cstdio>
 
 using namespace std;
diff --git a/test_problems/stoichSolidKinetics/stoichSolidKinetics.cpp b/test_problems/stoichSolidKinetics/stoichSolidKinetics.cpp
index 771bc804d..ef6802b34 100644
--- a/test_problems/stoichSolidKinetics/stoichSolidKinetics.cpp
+++ b/test_problems/stoichSolidKinetics/stoichSolidKinetics.cpp
@@ -1,8 +1,6 @@
-#include "cantera/electrolyteThermo.h"
+#include "cantera/thermo.h"
 #include "cantera/kinetics.h"
-#include "cantera/thermo/MargulesVPSSTP.h"
-#include "cantera/thermo/IonsFromNeutralVPSSTP.h"
-#include "cantera/IdealGasMix.h"
+#include "cantera/kinetics/InterfaceKinetics.h"
 
 #include <iomanip>
 #include <sstream>