Merge pull request #132 from newcleo-dev-team/131_minor_revs

[131_minor_revs], issue - #131, Applied some minor corrections to doc…

README.rst

@@ -112,3 +112,12 @@ How to Cite
     month = {Aug 20--25},
     editor = {ANS}
   }
+
+.. code-block:: latex
+
+  @article{lbh15JOSS2024,
+    author = {Ottino, G.M., Panico, D., Tomatis, D. and Pantel, P.A.},
+    title = {{lbh15: a Python package for standard use and implementation of physical data of heavy liquid metals used in nuclear reactors}},
+    editor = {Journal of Open-Source Scientific Software}
+    note={submitted}
+  }

docs/source/learn_more.rst

@@ -5,8 +5,8 @@ Oxygen Control
 ++++++++++++++
 
 In lead and LBE systems, Oxygen is the most important chemical element, which results
-from start-up operations, maintenance services and possibily incidental contaminations (:cite:`Agency2015`).
-For the operation of a nuclear reactor cooled by a lead alloy, it is thus important to
+from start-up operations, maintenance services and, possibily, incidental contaminations (:cite:`Agency2015`).
+To operate a nuclear reactor cooled by a lead alloy, it is thus important to
 determine the upper and the lower Oxygen concentration limits.
 
 .. _ Oxygen concentration upper limit:
@@ -74,7 +74,7 @@ assumptions, are derived.
      
      where:
 
-     - :math:`\Delta G^0_{\left(i\right)}` is the Gibbs free energy of formation related to the (i)-th reaction equation;
+     - :math:`\Delta G^0_{\left(i\right)}` is the Gibbs free energy of formation related to the (:math:`i`)-th reaction equation;
      - :math:`\Delta H^0_{\left(3\right)} = \Delta H^0_{\left(1\right)}-\Delta H^0_{\left(2\right)}` is the formation enthalpy related to equation :eq:`oxide_react_eq`;
      - :math:`\Delta S^0_{\left(3\right)} =\Delta S^0_{\left(1\right)}-\Delta S^0_{\left(2\right)}` is the formation entropy related to equation :eq:`oxide_react_eq`;
      - :math:`\Delta H^0` and :math:`\Delta S^0` values for each reaction are taken from the table 4.2.2 of :cite:`Agency2015`.
@@ -133,7 +133,7 @@ assumptions, are derived.
      thus taking the chemical activity of the dissolved Oxygen equal to the chemical activity of the dissolved :math:`\ce{PbO}`, and by
      applying some transformations, one can obtain:
 
-     .. math:: \ln{\left( C_{\ce{O}} \right)} = \frac{X}{Y} \cdot \ln{\left(\frac{C_{\ce{Me}}^{sat}}{C_{\ce{Me}}}\right)} + \frac{\Delta H^0_{\left(3\right)}}{2RT} - \frac{\Delta S^0_{\left(3\right)}}{2R} + \ln{\left(\alpha_{\ce{Pb}} \cdot C_{\ce{O}}^{sat}\right)}
+     .. math:: \ln{\left( C_{\ce{O}} \right)} = \frac{X}{Y} \cdot \ln{\left(\frac{C_{\ce{Me}}^{sat}}{C_{\ce{Me}}}\right)} + \frac{\Delta H^0_{\left(3\right)}}{2RT} - \frac{\Delta S^0_{\left(3\right)}}{2R} + \ln{\left(\alpha_{\ce{Pb}} \cdot C_{\ce{O}}^{sat}\right)}.
       :label: ox_conc_eq
 
      In the above equation, the unknows are two, that is, the Oxygen concentration :math:`C_{\ce{O}}` and the concentration
@@ -364,7 +364,7 @@ By looking into the code implementation, the following sections are identified:
     Qout: float = -1e6 # Value of dissipated heat power [W/m3]
     Ox_start = 7e-4 # Initial oxygen concentration [wt.%]
     # PID controller settings
-    P_coeff: float = 0.75 # Proportial coefficient [-]
+    P_coeff: float = 0.75 # Proportional coefficient [-]
     I_coeff: float = 0.9 # Integral coefficient [-]
     D_coeff: float = 0.0 # Derivative coefficient [-]
     max_output: float = Ox_start # Maximum value of the output [wt.%]
@@ -394,7 +394,7 @@ By looking into the code implementation, the following sections are identified:
 
   where:
 
-  - ``time`` contains all the time instants hich the solution is computed at;
+  - ``time`` contains all the time instants which the solution is computed at;
   - ``delta_t`` is the integration time step;
   - ``Qin`` is a dictionary containing for each time instant (key) the corresponding heat load value; values coincide with the Heaviside function values stored in ``Qin_signal``;
   - ``T_sol`` is the array where the lead temperature time history will be stored;
@@ -448,7 +448,7 @@ By looking into the code implementation, the following sections are identified:
         Ox_sol[i] = pid(Ox_sol[i])
         i += 1
 
-  where there is a loop over all the required time instants; for each *i*-th instant:
+  where there is a loop over all the required time instants; for each :code:`i`-th instant:
 
   - an explicit call is made to the time integration function;
   - the Oxygen concentration setpoint is updated correspondingly;
@@ -479,7 +479,7 @@ By looking into the code implementation, the following sections are identified:
   
   where:
 
-  - the first call to ``plotTimeHistory()`` returns the 2D plot shown above, where the heat load time history is depicted;
+  - the first call to ``plotTimeHistory()`` returns the 2D plot shown in :numref:`timevsqin`, where the heat load time history is depicted;
   - the second call to ``plotTimeHistory()`` returns the 2D plot where the temperature time history is depicted of the lead volume (see :numref:`timet`);
 
     .. _timet:
@@ -498,9 +498,9 @@ By looking into the code implementation, the following sections are identified:
       :width: 500
       :align: Center
 
-      Time evolution of the Oxygen concentrations within the lead volume: the Oxygen concentration setpoint (yellow) and the actual controlled Oxygen concentration (blue).
+      Time evolution of the Oxygen concentrations within the lead volume: the Oxygen concentration setpoint (orange) and the actual controlled Oxygen concentration (blue).
 
-    After an initial transient, the blue curve, representing the controlled Oxygen concentration within lead, overlaps almost exactly with the setpoint values (yellow curve).
+    After an initial transient, the blue curve, representing the controlled Oxygen concentration within lead, overlaps almost exactly with the setpoint values (orange curve).
     The overlapping of the two Oxygen concentration curves can be improved or worsened by varying the PID coefficients.
 
 .. note:: This tutorial works even with the :class:`.Bismuth` and the :class:`.LBE` classes instances.

docs/source/readme_full.rst

@@ -1,6 +1,6 @@
 .. raw:: latex
 
-   \setcounter{secnumdepth}{1}
+   \setcounter{secnumdepth}{3}
 
 ============
 Introduction
@@ -432,7 +432,7 @@ Basic Usage
 This section shows a few examples of basic usage of *lbh15*.
 
 - Create a :class:`.Lead` instance using Celsius degrees as temperature unit
-  and print the corresponding dynamic viscosity:
+  and print the corresponding dynamic viscosity :code:`mu`:
 
   >>> from scipy.constants import convert_temperature
   >>> from lbh15 import Lead
@@ -443,7 +443,7 @@ This section shows a few examples of basic usage of *lbh15*.
   0.0022534948395446985
 
 - Create two instances of :class:`.Lead` class, one at atmospheric pressure and one at twenty times the 
-  atmospheric pressure. Then compare their density values:
+  atmospheric pressure. Then compare their density values :code:`rho`:
 
   >>> from lbh15 import Lead
   >>> from scipy.constants import atm
@@ -455,8 +455,8 @@ This section shows a few examples of basic usage of *lbh15*.
   >>> liquid_lead.rho, liquid_lead_2.rho
   (10417.4, 10418.185181757714)
 
-- Create an instance of :class:`.Lead` class at a given temperature, then change the temperature value. Compare the conductivity
-  values at the two temperatures:
+- Create an instance of :class:`.Lead` class at a given temperature :code:`T`, then change the temperature value. Compare the conductivity
+  values :code:`k` at the two temperatures:
 
   >>> from lbh15 import Lead
   >>> liquid_lead = Lead(T=750)
@@ -466,8 +466,8 @@ This section shows a few examples of basic usage of *lbh15*.
   >>> liquid_lead.k
   22.4
 
-- Create an instance of :class:`.Lead` class at a given temperature, then change the temperature value. Compare the Oxygen
-  diffusivity values at the two temperatures:
+- Create an instance of :class:`.Lead` class at a given temperature :code:`T`, then change the temperature value. Compare the Oxygen
+  diffusivity values :code:`o_dif` at the two temperatures:
 
   >>> from lbh15 import Lead
   >>> liquid_lead = Lead(T=700)
@@ -478,8 +478,7 @@ This section shows a few examples of basic usage of *lbh15*.
   6.708316471487037e-06
 
 - Request a property outside the range of validity of the corresponding correlation. In this example, a :class:`.Lead` object is initialized
-  using a temperature value that is outside the range of physical validity of the surface tension
-  correlation:
+  using a temperature value :code:`T` that is outside the range of physical validity of the surface tension :code:`sigma` correlation:
 
   >>> from lbh15 import Lead
   >>> liquid_lead = Lead(T=1400.0)
@@ -521,8 +520,8 @@ the user is invited to double-check the result (see :any:`advanced-usage` sectio
 
 In the following, some examples are provided:
 
-- Initialize an :class:`.LBE` instance, i.e., lead-bismuth-eutectic object, by setting its density
-  and retrieve the corresponding temperature in Kelvin degrees:
+- Initialize an :class:`.LBE` instance, i.e., lead-bismuth-eutectic object, by setting its density :code:`rho`
+  and retrieve the corresponding temperature :code:`T` in Kelvin degrees:
 
   >>> from lbh15 import LBE
   >>> # Initialize LBE with rho=9800 [kg/m^3]
@@ -533,8 +532,8 @@ In the following, some examples are provided:
 
 - Compare properties of different liquid metal objects at a given temperature. In this 
   example, a :class:`.Lead` object is initialized by specifying a value of the thermal
-  conductivity :math:`k`; then, a :class:`.Bismuth` object is initialized using the :class:`.Lead`
-  instance temperature in Kelvin degrees. Finally, the conductivity of the :class:`.Bismuth` object
+  conductivity :code:`k`; then, a :class:`.Bismuth` object is initialized using the :class:`.Lead`
+  instance temperature :code:`T` in Kelvin degrees. Finally, the thermal conductivity :code:`k` of the :class:`.Bismuth` object
   is printed for comparison purposes:
 
   >>> from lbh15 import Lead
@@ -605,34 +604,34 @@ Advanced usage includes the possibility of adding new properties and new physica
     from lbh15.properties.interface import range_warning
 
     class rho_custom_corr(PropertyInterface):
-      @range_warning
-      def correlation(self, T, p=atm, verbose=False):
-          "Implement here the user-defined correlation."
-          return 11400 - 1.2*T
+        @range_warning
+        def correlation(self, T, p=atm, verbose=False):
+            "Implement here the user-defined correlation."
+            return 11400 - 1.2*T
 
-      @property
-      def range(self):
-          return [700.0, 1900.0]
+        @property
+        def range(self):
+            return [700.0, 1900.0]
 
-      @property
-      def units(self):
-          return "[kg/m^3]"
+        @property
+        def units(self):
+            return "[kg/m^3]"
 
-      @property
-      def name(self):
-          return "rho"
+        @property
+        def name(self):
+            return "rho"
 
-      @property
-      def long_name(self):
-          return "custom density"
+        @property
+        def long_name(self):
+            return "custom density"
 
-      @property
-      def description(self):
-          return "Liquid lead " + self.long_name
+        @property
+        def description(self):
+            return "Liquid lead " + self.long_name
 
-      @property
-      def correlation_name(self):
-          return "custom2022"
+        @property
+        def correlation_name(self):
+            return "custom2022"
 
   .. note:: It is mandatory to override the ``correlation`` method and the ``range``, ``units``, ``long_name`` and ``description`` properties.
 
@@ -697,34 +696,34 @@ Advanced usage includes the possibility of adding new properties and new physica
     from lbh15.properties.interface import range_warning
 
     class T_double(PropertyInterface):
-      @range_warning
-      def correlation(self, T, p=atm, verbose=False):
-          "Return the temperature value multiplied by 2."
-          return 2*T
-
-      @property
-      def range(self):
-          return [700.0, 1900.0]
-
-      @property
-      def units(self):
-          return "[K]"
-
-      @property
-      def name(self):
-          return "T_double"
-
-      @property
-      def long_name(self):
-          return "double of the temperature"
-
-      @property
-      def description(self):
-          return "Liquid lead " + self.long_name
-
-      @property
-      def correlation_name(self):
-          return "double2022"
+        @range_warning
+        def correlation(self, T, p=atm, verbose=False):
+            "Return the temperature value multiplied by 2."
+            return 2*T
+
+        @property
+        def range(self):
+            return [700.0, 1900.0]
+
+        @property
+        def units(self):
+            return "[K]"
+
+        @property
+        def name(self):
+            return "T_double"
+
+        @property
+        def long_name(self):
+            return "double of the temperature"
+
+        @property
+        def description(self):
+            return "Liquid lead " + self.long_name
+
+        @property
+        def correlation_name(self):
+            return "double2022"
 
   The new custom property can be set as :class:`.Lead` attribute by specifying the path to the module
   where it is defined:

docs/source/release_notes.rst

@@ -13,6 +13,8 @@ related to each one, please look at https://github.com/newcleo-dev-team/lbh15.
 
 1. **Enhancements**
 
+   - Minor revisions to doc and comments - **#131**
+
    - Remove typecheck for performance reasons - **#129**
 
    - Review for v2.0.0 release - **#120**
@@ -29,7 +31,7 @@ related to each one, please look at https://github.com/newcleo-dev-team/lbh15.
 
    - Horner's Scheme - **#100**
 
-   - Update :code:`test_custom_properties`` to test correct assignment of custom properties to different liquid metal classes - **#86**
+   - Update :code:`test_custom_properties` to test correct assignment of custom properties to different liquid metal classes - **#86**
 
    - Thermochemical Modules Corrections and Improvements - **#76**
 
@@ -101,7 +103,7 @@ related to each one, please look at https://github.com/newcleo-dev-team/lbh15.
 
    - Modifiy liquid metal classes to read thermochemical properties - **#30**
 
-   - Properties module attribute of :code:`LiquidMetalInterface`` must be a dictionary to handle multiple modules - **#29**
+   - Properties module attribute of :code:`LiquidMetalInterface` must be a dictionary to handle multiple modules - **#29**
 
    - Modify the properties sub-package for the implementation of thermochemical properties - **#28**
 
@@ -145,7 +147,7 @@ related to each one, please look at https://github.com/newcleo-dev-team/lbh15.
 
    - Warnings management - **#107**
 
-   - Add the pressure info inside the :code:`__repr__`` method - **#106**
+   - Add the pressure info inside the :code:`__repr__` method - **#106**
 
    - Fix initialization of liquid metal object from thermochemical properties - **#83**
 
@@ -157,7 +159,7 @@ related to each one, please look at https://github.com/newcleo-dev-team/lbh15.
 
    - Attribute Change within :file:`_lbh15.py` - **#55**
 
-   - Bug into "range_warning" Method ("interface.py") - **#51**
+   - Bug into :code:`range_warning` Method (:file:`interface.py`) - **#51**
 
    - Fix loading of duplicate properties - **#45**
 

lbh15/properties/bismuth_thermochemical_properties/bismuth_thermochemical.py

@@ -439,7 +439,7 @@ def correlation(self, T: float, p: float = atm,
         Returns
         -------
         float:
-            Gibbs free energy in :math:`[J/mol)]`
+            Gibbs free energy in :math:`[J/mol]`
         """
         return MolarEnthalpy().correlation(T, p)\
             - T * MolarEntropy().correlation(T, p)

lbh15/properties/lbe_thermochemical_properties/lbe_thermochemical.py

@@ -417,7 +417,7 @@ def correlation(self, T: float, p: float = atm,
         Returns
         -------
         float:
-            Gibbs free energy in :math:`[J/mol)]`
+            Gibbs free energy in :math:`[J/mol]`
         """
         return MolarEnthalpy().correlation(T, p)\
             - T * MolarEntropy().correlation(T, p)

lbh15/properties/lead_thermochemical_properties/lead_thermochemical.py

@@ -694,7 +694,7 @@ def correlation(self, T: float, p: float = atm,
         Returns
         -------
         float:
-            Gibbs free energy in :math:`[J/mol)]`
+            Gibbs free energy in :math:`[J/mol]`
         """
         return MolarEnthalpy().correlation(T, p)\
             - T * MolarEntropy().correlation(T, p)

tutorials/oxygen_control/control_on_oxygen_by_metal.py

@@ -22,7 +22,7 @@
 Qout: float = -1e6 # Value of dissipated heat power [W/m3]
 Ox_start = 7e-4 # Initial oxygen concentration [wt.%]
 # PID controller settings
-P_coeff: float = 0.75 # Proportial coefficient [-]
+P_coeff: float = 0.75 # Proportional coefficient [-]
 I_coeff: float = 0.9 # Integral coefficient [-]
 D_coeff: float = 0.0 # Derivative coefficient [-]
 max_output: float = Ox_start # Maximum value of the output [wt.%]