Imporved documentation (#58)

thermohub · Dec 24, 2022 · bdbc9ee · bdbc9ee
1 parent 9a701c9
commit bdbc9ee
Show file tree

Hide file tree

Showing 20 changed files with 269 additions and 141 deletions.
diff --git a/.hdoc.toml b/.hdoc.toml
@@ -0,0 +1,32 @@
+[project]
+name = "thermofun"
+version = "0.4.2"
+
+# Optional, adding this will enable direct links from the documentation
+# to your source code.
+git_repo_url = "https://github.com/thermohub/thermofun/"
+git_default_branch = "master"
+
+[paths]
+compile_commands = "build/compile_commands.json"
+# output_dir = "docs/hdoc-output"
+
+[pages]
+homepage = "docs/index.md"
+
+[ignore]
+# Symbols from any of the following path fragments will be ignored
+ignore_private_members = true
+paths = [
+  "/python/",
+  "/pytests/",
+  "/tests/",
+  "/Common/",
+  "OptimizationUtils.h",
+  "/Substances/Solvent/Reaktoro/",
+  "/Substances/Gases/s_solmod_.cpp",
+  "/Substances/Gases/s_solmod_.h",
+  "/Substances/Gases/s_solmod2_.cpp",
+  "/Substances/Gases/verror.h"
+  # more paths can be added as needed
+]
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -8,7 +8,7 @@ set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules")
 include(CCache)
 
 # Set the name of the project
-project(ThermoFun VERSION 0.4.1 LANGUAGES CXX)
+project(ThermoFun VERSION 0.4.2 LANGUAGES CXX)
 
 # Define variables with the GNU standard installation directories
 include(GNUInstallDirs)

diff --git a/README.md b/README.md
@@ -5,6 +5,7 @@ Linux, OSX, Windows
 
 A code for calculating the standard state thermodynamic properties of substances and reactions at a given temperature and pressure.
 
+- [Code documentation](https://docs.hdoc.io/dmiron/thermofun/?target=_blank)
 - [Simple C++ API example](#simple-c-api-example)
 - [Try ThermoFun](#try-thermofun-in-your-browser-click-launch-binder)
 - [Python example](#simple-python-api-example)

diff --git a/ThermoFun/Batch/OutputBatch.h b/ThermoFun/Batch/OutputBatch.h
@@ -23,14 +23,14 @@ class Output
 
     /**
      * @brief toCSV write results to CSV file
-     * with substances/reactions on rows and proeprties on columns
+     * with substances/reactions on rows and properties on columns
      * @param filename
      */
     auto toCSV                  (std::string filename) -> void;
 
     /**
      * @brief toCSVTransposed write results to CSV file in a special transposed format.
-     * with substances/reactions on columns and proeprties on rows
+     * with substances/reactions on columns and properties on rows
      * @param filename
      */
     auto toCSVTransposed        (std::string filename) -> void;

diff --git a/ThermoFun/Batch/ThermoBatch.cpp b/ThermoFun/Batch/ThermoBatch.cpp
@@ -615,5 +615,24 @@ auto ThermoBatch::results() -> const vvThScalar
     return pimpl->results;
 }
 
+auto ThermoBatch::temperatureIncrement() -> const std::map<std::string, double>&
+{
+    return pimpl->Tincrement;
+}
+
+auto ThermoBatch::pressureIncrement() -> const std::map<std::string, double>&
+{
+    return pimpl->Pincrement;
+}
+
+auto ThermoBatch::propertyUnits () -> const std::map<std::string, std::string>&
+{
+    return pimpl->givenPropertyUnits;
+}
+auto ThermoBatch::propertyDigits() -> const std::map<std::string, int>&
+{
+    return pimpl->givenPropertyDigits;
+}
+
 }
 
diff --git a/ThermoFun/Batch/ThermoBatch.h b/ThermoFun/Batch/ThermoBatch.h
@@ -28,7 +28,7 @@ typedef std::vector<ThermoPropertiesSubstance> vtps;
 typedef std::vector<ThermoPropertiesReaction>  vtpr;
 
 /**
- * @brief The OutputOptions struct holds the options for outputing results
+ * @brief The OutputOptions struct holds the options for outputting results
  */
 struct BatchPreferences
 {
@@ -68,17 +68,17 @@ struct BatchPreferences
 ///
 /// \brief The Interface class provides an interface to C++ codes coupled to ThermoFunk library for performing
 /// calculations related to the standard state properties of substances and reactions at different temperatures
-/// and pressures, and retriveve the results as CSV output file, 2D vector (of double or ThrmoScalar types), or
+/// and pressures, and retrieve the results as CSV output file, 2D vector (of double or ThrmoScalar types), or
 /// single value (of double or ThermoScalar types) for one property-substance-T-P calculation.
 ///
-/// The class provides several functions for adding the symbol of the substance or reaction (or lists of symblos)
+/// The class provides several functions for adding the symbol of the substance or reaction (or lists of symbols)
 /// for which the calculations will be performed.
 ///
 /// The class provides several functions for adding the temperature and pressure points at which the calculations
 /// will be performed.
 ///
-/// The class provides several functions for setting the unist in which the results are dysplayed and the
-/// siginifincat digits (or precision) in which the values will be written in the output CSV file.
+/// The class provides several functions for setting the units in which the results are displayed and the
+/// siginificant digits (or precision) in which the values will be written in the output CSV file.
 ///
 /// The input temperature and pressure should be in celsius and bar
 ///
@@ -114,7 +114,7 @@ class ThermoBatch
     auto setTemperatureIncrement    (const double& Tmin, const double& Tmax, const double& Tstep) -> void;
     auto setPressureIncrement       (const double& Pmin, const double& Pmax, const double& Pstep) -> void;
 
-    // claculate functions substances
+    // calculate functions substances
     auto thermoPropertiesSubstance  (double T, double P, std::string symbol,  std::string property) -> Output;
     auto thermoPropertiesSubstance  (double T, double P, vstr        symbols, vstr        properties) -> Output;
     auto thermoPropertiesSubstance  (vstr symbols, vstr properties) -> Output;
@@ -123,7 +123,7 @@ class ThermoBatch
     auto thermoPropertiesSubstance  (std::vector<double> temperatures, std::vector<double> pressures, vstr symbols, vstr properties) -> Output;
     auto thermoPropertiesSubstance  (std::vector<double> temperatures, std::vector<double> pressures, vstr symbols, vstr properties, vtps vTps) -> Output;
 
-    // claculate functions reactions
+    // calculate functions reactions
     auto thermoPropertiesReaction   (double T, double P, std::string symbol,  std::string property) -> Output;
     auto thermoPropertiesReaction   (double T, double P, vstr        symbols, vstr        properties) -> Output;
     auto thermoPropertiesReaction   (vstr symbols, vstr properties) -> Output;
@@ -135,6 +135,12 @@ class ThermoBatch
     auto setBatchPreferences        (const BatchPreferences &value) -> void;
     auto setSolventSymbol           (const std::string solventSymbol) ->void;
 
+    auto temperatureIncrement  () -> const std::map<std::string, double>&;
+    auto pressureIncrement  () -> const std::map<std::string, double>&;
+
+    auto propertyUnits  () -> const std::map<std::string, std::string>&; 
+    auto propertyDigits () -> const std::map<std::string, int>&; 
+
 private:
     struct Impl;
     std::shared_ptr<Impl> pimpl;
@@ -154,7 +160,7 @@ class ThermoBatch
 
 const std::map<std::string, const std::string> defaultPropertyNames =
 {
-        // Substance propeties
+        // Substance properties
     {"gibbs_energy",                   "substance"     },
     {"enthalpy",                       "substance"     },
     {"entropy",                        "substance"     },
@@ -163,7 +169,7 @@ const std::map<std::string, const std::string> defaultPropertyNames =
     {"volume",                         "substance"     },
     {"helmholtz_energy",               "substance"     },
     {"internal_energy",                "substance"     },
-        // Reaction propeties
+        // Reaction properties
     {"reaction_gibbs_energy",          "reaction"      },
     {"reaction_helmholtz_energy",      "reaction"      },
     {"reaction_internal_energy",       "reaction"      },
@@ -174,7 +180,7 @@ const std::map<std::string, const std::string> defaultPropertyNames =
     {"reaction_heat_capacity_cv",      "reaction"      },
     {"logKr",                          "reaction"      },
     {"lnKr",                           "reaction"      },
-        // Solvent propeties
+        // Solvent properties
     {"density",                        "solvent"      },
     {"densityT",                       "solvent"      },
     {"densityP",                       "solvent"      },

diff --git a/ThermoFun/Database.h b/ThermoFun/Database.h
@@ -43,7 +43,7 @@ class Database
     explicit Database(std::string filename);
 
     /**
-     * @brief Database constructs a database instace from a vector of records in json format
+     * @brief Database constructs a database instance from a vector of records in json format
      * Records with the same symbol will be overwritten!
      * @param jsonRecords vector of records in JSON string format
      * @param _label, optional, (element, substance, reactions),
@@ -68,7 +68,7 @@ class Database
      * @brief appendData append records to the database from a vector of JSON strings
      * Records with the same symbol will be overwritten!
      * @param jsonRecords vector of records in JSON string format
-     * @param _label, oprional, (element, substance, reactions),
+     * @param _label, optional, (element, substance, reactions),
      * used when the vector of records are of one type and do not contain themselves the key "_label"
      */
     auto appendData(std::vector<std::string> jsonRecords, std::string _label) -> void;

diff --git a/ThermoFun/Substance.h b/ThermoFun/Substance.h
@@ -17,10 +17,10 @@ struct ThermoParametersSubstance;
 class Substance
 {
 public:
-    /// Constrcut a default Substance instance
+    /// Construct a default Substance instance
     Substance();
 
-    /// Constrcut a Substance instance from a JSON string
+    /// Construct a Substance instance from a JSON string
     Substance(std::string jsonSubstance);
 
     /// Construct a copy of an Substance instance

diff --git a/ThermoFun/ThermoEngine.h b/ThermoFun/ThermoEngine.h
@@ -22,7 +22,7 @@ struct ElectroPropertiesSolvent;
 struct PropertiesSolvent;
 
 /**
- * @brief The Thermo class mainly calculates the thermodynamic properties of the substances
+ * @brief The ThermoEngine class calculates the thermodynamic properties of the substances
  * from the internal database. It also calculates the electro-chemical and other physico-chemical
  * properties of the solvent
  */

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,68 @@
+<!--
+ Copyright (C) 2022 dmiron
+ 
+ This file is part of thermofun.
+ 
+ thermofun is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ 
+ thermofun is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License
+ along with thermofun.  If not, see <http://www.gnu.org/licenses/>.
+-->
+
+# [ThermoFun](https://thermohub.org/thermofun/thermofun/)
+
+#### Details on the API functionality can be found by [searching](https://docs.hdoc.io/dmiron/thermofun/search.html) the documentation. The naming is the  same in C++ and Python.
+
+Using ThermoFun is as simple as loading a [database](https://github.com/thermohub/thermofun-jupyter/blob/master/how-to-use-a-database.ipynb) initializing a [ThermoEngine](https://github.com/thermohub/thermofun-jupyter/blob/master/how-to-calculate-properties-thermoengine.ipynb)/[ThermoBatch](https://github.com/thermohub/thermofun-jupyter/blob/master/how-to-do-batch-calculations.ipynb) and calling the function to [calculate the properties](https://github.com/thermohub/thermofun-jupyter/blob/master/how-to-calculate-properties-substance-reaction.ipynb) for given substance(s)/reaction(s) at given T-P condition(s).
+
+```python
+  import thermofun as fun
+  database = fun.Database('aq17-thermofun.json')
+  engine = fun.ThermoEngine(database)
+  #                                        T(K)   P(Pa)  symbol
+  Ca_ion = engine.thermoPropertiesSubstance(473, 2000e5, 'Ca+2')
+  print(f'G0 {Ca_ion.gibbs_energy.val} J/mol')
+  #                                                     T(K)   P(Pa)  reaction equation
+  calcite_dissolution = engine.thermoPropertiesReaction(348.15, 1e5, 'Calcite = Ca+2 + CO3-2')
+  print(f'drS0 of (Cal = Ca+2 + CO3-2) is {calcite_dissolution.reaction_entropy.val}')
+  print(f'drG0 of (Cal = Ca+2 + CO3-2) is {calcite_dissolution.reaction_gibbs_energy.val}')
+  print(f'logK0 of (Cal = Ca+2 + CO3-2) is {calcite_dissolution.log_equilibrium_constant.val}')
+```
+
+In Python using the `help` function can provide hints on the usability.
+
+```python
+help(fun.ThermoEngine)
+
+Help on class ThermoEngine in module thermofun.PyThermoFun:
+
+class ThermoEngine(pybind11_builtins.pybind11_object)
+ |  Contains methods for calculating the thermodynamic properties of the substances and reactions
+ ...
+```
+
+Try the ThermoFun examples in your browser:
+
+[![Launch ThermoFun tutorials](https://img.shields.io/badge/launch-ThermoFun%20tutorials-brightgreen?style=for-the-badge&logo=jupyter)](https://mybinder.org/v2/gh/thermohub/thermofun-jupyter/master?urlpath=lab/)
+
+## The main ThermoFun classes
+
+* [Database](https://docs.hdoc.io/dmiron/thermofun/r820E4166D6856B34.html): The Database class stores maps of elements, substances and reactions. A database instance can be used to create a ThermoEngine instance which can be further used to calculate the standard thermodynamic properties of substances and reactions at T and P
+
+[![Launch example on initializing a database from file](https://img.shields.io/badge/launch-Database%20example-brightgreen?style=for-the-badge&logo=jupyter)](https://mybinder.org/v2/gh/thermohub/thermofun-jupyter/master?urlpath=lab/tree/how-to-use-a-database.ipynb)
+
+* [ThermoEngine](https://docs.hdoc.io/dmiron/thermofun/r15CBE4920E8D3EF1.html): The main ThermoFun class for doing calculations. It calculates the thermodynamic properties of the substances from the database. It also calculates the electro-chemical and other physico-chemical properties of the solvent.
+
+[![Launch example on using ThermoEngine to calculate thermodynamic properties](https://img.shields.io/badge/launch-ThermoEngine%20example-brightgreen?style=for-the-badge&logo=jupyter)](https://mybinder.org/v2/gh/thermohub/thermofun-jupyter/master?urlpath=lab/tree/how-to-calculate-properties-thermoengine.ipynb)
+
+* [ThermoBatch](https://docs.hdoc.io/dmiron/thermofun/r88DCC0D87A971DFF.html): The Batch class is useful for doing batch calculations for a given list of substances, reactions, properties, and temperature and pressure grid. Options to set the input and output properties units are available.
+
+[![Launch example on doing batch calculations, for a list of substances, T-P intervals](https://img.shields.io/badge/launch-ThermoBatch%20example-brightgreen?style=for-the-badge&logo=jupyter)](https://mybinder.org/v2/gh/thermohub/thermofun-jupyter/master?urlpath=lab/tree/how-to-do-batch-calculations.ipynb)
diff --git a/python/pyThermoFun/Batch/pyOutputBatch.cpp b/python/pyThermoFun/Batch/pyOutputBatch.cpp
@@ -35,14 +35,14 @@ namespace ThermoFun {
 
 void exportOutput(py::module& m)
 {
-    py::class_<Output>(m, "Output")
+    py::class_<Output>(m, "Output", "Type for outputting results to different formats")
         .def(py::init<const ThermoBatch&>())
-        .def("toCSV", &Output::toCSV)
-        .def("toCSVTransposed", &Output::toCSVTransposed)
-        .def("toCSVPropertyGrid", &Output::toCSVPropertyGrid)
+        .def("toCSV", &Output::toCSV, "write results to CSV file with substances/reactions on rows and properties on columns")
+        .def("toCSVTransposed", &Output::toCSVTransposed, "write results to CSV file in a special transposed format with substances/reactions on columns and properties on rows")
+        .def("toCSVPropertyGrid", &Output::toCSVPropertyGrid, "write results to CSV file in a property grid format")
         .def("toDouble", &Output::toDouble)
         .def("toThermoScalar", &Output::toThermoScalar)
-        .def("to2DVectorDouble", &Output::to2DVectorDouble)
+        .def("to2DVectorDouble", &Output::to2DVectorDouble, "returns a list of results")
         ;
 }
 }