[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,4 +1,5 @@
 #include "cantera/thermo.h"
+#include <iostream>
 
 using namespace Cantera;
 

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;
 

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.

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
 {

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
 {

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"

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"

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"
 

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

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

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"
 

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

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

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;

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
 {

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"

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;

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;

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;

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>
 

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>
 

test_problems/pureFluidTest/testPureWater.cpp

@@ -1,4 +1,5 @@
 #include "cantera/PureFluid.h"
+#include "cantera/thermo.h"
 #include <cstdio>
 
 using namespace std;

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>