[Units] Improve docstrings

Cantera · Sep 10, 2021 · d45482b · d45482b
1 parent 24fcfeb
commit d45482b
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 18 deletions.
diff --git a/interfaces/cython/cantera/_cantera.pxd b/interfaces/cython/cantera/_cantera.pxd
@@ -647,7 +647,7 @@ cdef extern from "cantera/base/YamlWriter.h" namespace "Cantera":
         void toYamlFile(string&) except +translate_exception
         void setPrecision(int)
         void skipUserDefined(cbool)
-        void setUnitSystem(CxxUnitSystem) except +translate_exception
+        void setUnitSystem(CxxUnitSystem&) except +translate_exception
 
 cdef extern from "cantera/equil/MultiPhase.h" namespace "Cantera":
     cdef cppclass CxxMultiPhase "Cantera::MultiPhase":

diff --git a/interfaces/cython/cantera/test/test_utils.py b/interfaces/cython/cantera/test/test_utils.py
@@ -11,7 +11,7 @@ class TestUnitSystem(utilities.CanteraTest):
     def test_default(self):
         units = ct.UnitSystem().units
         checks = {
-            "activation-energy": "J/kmol",
+            "activation-energy": "J / kmol",
             "current": "A",
             "energy": "J",
             "length": "m",
@@ -28,16 +28,16 @@ def test_default(self):
     def test_cgs(self):
         system = ct.UnitSystem({
             "length": "cm", "mass": "g", "time": "s",
-            "quantity": "mol", "pressure": "dyn/cm^2", "energy": "erg",
-            "activation-energy": "cal/mol"})
+            "quantity": "mol", "pressure": "dyn / cm^2", "energy": "erg",
+            "activation-energy": "cal / mol"})
         units = system.units
         checks = {
-            "activation-energy": "cal/mol",
+            "activation-energy": "cal / mol",
             "current": "A",
             "energy": "erg",
             "length": "cm",
             "mass": "g",
-            "pressure": "dyn/cm^2",
+            "pressure": "dyn / cm^2",
             "quantity": "mol",
             "temperature": "K",
             "time": "s",

diff --git a/interfaces/cython/cantera/units.pyx b/interfaces/cython/cantera/units.pyx
@@ -31,30 +31,26 @@ cdef class Units:
 
 cdef class UnitSystem:
     """
-    Unit conversion utility
+    Unit system used for YAML input and output.
 
-    Provides functions for converting dimensional values from a given unit system.
-    The main use is for converting values specified in input files to Cantera's
+    The `UnitSystem` class is used to specify dimensional values for a given unit
+    system. The main use is for converting values specified in input files to Cantera's
     native unit system, which is SI units except for the use of kmol as the base
     unit of quantity, i.e. kilogram, meter, second, kelvin, ampere, and kmol.
 
-    Special functions for converting activation energies allow these values to be
-    expressed as either energy per quantity, energy (e.g. eV), or temperature by
-    applying a factor of the Avogadro number or the gas constant where needed.
-
     The default unit system used by Cantera is SI+kmol::
 
         ct.UnitSystem({
             "length": "m", "mass": "kg", "time": "s",
             "quantity": "kmol", "pressure": "Pa", "energy": "J",
-            "temperature": "K", "current": "A", "activation-energy": "J/kmol"})
+            "temperature": "K", "current": "A", "activation-energy": "J / kmol"})
 
     A CGS+mol unit system with activation energy units of cal/mol is created as::
 
         ct.UnitSystem({
             "length": "cm", "mass": "g", "time": "s",
-            "quantity": "mol", "pressure": "dyn/cm^2", "energy": "erg",
-            "temperature": "K", "current": "A", "activation-energy": "cal/mol"})
+            "quantity": "mol", "pressure": "dyn / cm^2", "energy": "erg",
+            "temperature": "K", "current": "A", "activation-energy": "cal / mol"})
 
     Defaults for dimensions not specified will be left unchanged. Accordingly,
     the default unit system is retrieved as::

diff --git a/src/base/Units.cpp b/src/base/Units.cpp
@@ -339,7 +339,9 @@ std::map<std::string, std::string> UnitSystem::defaults() const
         {"activation-energy", Units(m_activation_energy_factor, 1, 2, -2, 0, 0, -1)},
     };
 
-    // Retrieve known units (if applicable)
+    // Retrieve known units
+    // (replace combinations of base units used by the default system by known
+    // secondary units, e.g. 'kg / m / s^2' is replaced by 'Pa')
     std::map<std::string, std::string> out;
     for (const auto& unit : units) {
         out[unit.first] = unit.second.str();
@@ -351,12 +353,14 @@ std::map<std::string, std::string> UnitSystem::defaults() const
         }
     }
 
-    // Overwrite entries that have buffered defaults
+    // Overwrite entries that have non-unity conversion factors
+    // (replace units deviating from default unit system with buffered values)
     for (const auto& defaults : m_defaults) {
         out[defaults.first] = defaults.second;
     }
 
     // Ensure compact output for activation energy
+    // (use appropriate abbreviations for activation energy)
     if (m_defaults.find("activation-energy") == m_defaults.end()) {
         out["activation-energy"] = fmt::format(
             "{} / {}", out["energy"], out["quantity"]);