updated documentation and renamed compounds to composites

README.md

@@ -86,7 +86,7 @@ expr element  isotope  ionisation  mass[Da]  count  Z  N  e
    H       H        1           0  1.007825    2.0  1  0  1
    O       O       16           0 15.994915    1.0  8  8  8
 
-Compound:
+Composite:
 
 Total mass:     Quantity(1.801e+01 Da)
 Total number:   3.0

docs/source/materials/elements.rst

@@ -1,7 +1,24 @@
 Elements
 ========
 
-Properties of individual :ref:`elements <materials/elements:list of elements>` are managed by ``Element`` class.
+Properties of individual elements are managed by ``Element`` class.
+Expressions of different elements carry information about their element types, isotope numbers and ionisation states.
+A comprehensive list of all available elements and their isotopes is given at the end of this section.
+Examples of element symbols of a carbon atom are given below:
+
+.. csv-table:: Notation of element symbols
+   :widths: 20, 20, 20, 40
+   :header-rows: 1
+
+   Symbol,    Abundance,  Ionisation, Note
+   "``C``",       natural,    neutral,    "naturally occuring carbon"
+   "``C{-3}``",   natural,    cation,     "positive natural ion"
+   "``C{+3}``",   natural,    anion,      "negative natural ion"
+   "``C{13}``",   isotope,    neutral,    "carbon-13 isotope"
+   "``C{13-3}``", isotope,    cation,     "positive isotope ion"
+   "``C{13+3}``", isotope,    anion,      "negative isotope ion"
+
+The ``Element`` class can be used in the following way.
 
 .. code-block:: python
 
@@ -22,7 +39,7 @@ If set to ``False``, an isotope with the highest abundance is used.
 .. note::
 
    The number of neutrons in naturally abundant elements is not always an integer.
-   This is due to calculation of averages over all element isotopes.
+   This is due to the calculation of averages over all element isotopes.
 
 .. code-block:: python
 
@@ -42,26 +59,6 @@ If its value is higher than one, all element properties are multiplied correspon
    >>> e.proportion, e.element, e.isotope, e.ionisation
    2, 'O', 16, 0
 
-The syntax of molecular formulas used in this solver is based on standard molecular formulas known from chemistry.
-The most basic part of formulas, an element symbol, carries information about element type, isotope number and ionisation state.
-A comprehensive list of all available :ref:`elements <materials/elements:list of elements>` and their isotopes is given at the end of this section.
-Examples of element symbols of a carbon atom are given below:
-
-.. csv-table:: Notation of element symbols
-   :widths: 20, 20, 20, 40
-   :header-rows: 1
-
-   Symbol,    Abundance,  Ionisation, Note
-   "``C``",       natural,    neutral,    "naturally occuring carbon"
-   "``C{-3}``",   natural,    cation,     "positive natural ion"
-   "``C{+3}``",   natural,    anion,      "negative natural ion"
-   "``C{13}``",   isotope,    neutral,    "carbon-13 isotope"
-   "``C{13-3}``", isotope,    cation,     "positive isotope ion"
-   "``C{13+3}``", isotope,    anion,      "negative isotope ion"
-
-List of elements
-----------------
-
 Individual nucleons can be used in formulas in the same way as elements and have the following properties:
 
 .. csv-table:: Nucleon properties
@@ -75,7 +72,7 @@ Individual nucleons can be used in formulas in the same way as elements and have
 
 
 Symbols of the elements conform to a standard element notation. 
-In case of named Hydrogen isotopes, it is also possible to use the following short notation:
+In the case of named Hydrogen isotopes, it is also possible to use the following short notation:
 
 .. csv-table:: Special symbols of hydrogen isotopes
    :widths: 20, 20, 20

docs/source/materials/index.rst

@@ -7,13 +7,13 @@ This should serve as a quick tool when one needs to count the number of nucleons
 Classes in this module are grouped into the following categories. 
 
 .. csv-table:: Material cathegories
-   :widths: 20, 20, 20, 20
+   :widths: 20, 20, 20, 20, 30
    :header-rows: 1
 
-   "Class",       Matter,  Compound, Component
-   "Element",     "✔",     "",       "✔"
-   "Substance",   "✔",     "✔",      "✔"
-   "Material",    "✔",     "✔",      ""
+   "Class",       Matter,  Composite, Component, Note
+   "Element",     "✔",     "",        "✔",       "atoms and homoatomic molecules"
+   "Substance",   "✔",     "✔",       "✔",       "compounds"
+   "Material",    "✔",     "✔",       "",        "mixtures"
 
 Exact terminology for categories used in this code is given below.
 
@@ -27,18 +27,18 @@ Substance
    The smallest form of matter with constant chemical composition made of single atoms (e.g. O), or multiple atoms connected by covalent (molecules e.g. H2, H2O), ionic (crystals e.g. NaCl), or metallic (metals e.g. CaCl2) bonds.
 
 Material
-   It is a substance, or a mixture of substances, that constitute an object (e.g. Air, Seawater). Substances in a material are not bound chemically, but rather blended mechanically and retain their chemical properties.
+   It is a substance, or a mixture of substances, that constitutes an object (e.g. Air, Seawater). Substances in a material are not bound chemically, but rather blended mechanically and retain their chemical properties.
 
 Matter
    A physical material that occupies space (volume) and possesses some rest mass.
 
 Component
-   An elementary part of a compound that has a specific proportion (number, or a fraction).
+   An elementary part of a composite that has a specific proportion (number, or a fraction).
+   In substances, proportions are numbers (count) of individual atoms.
+   In materials, proportions are number, or mass fractions of individual substances.
 
-Compound
+Composite
    A chemical structure composed of several components. 
-   In the case of substances, component proportions are given by integer numbers (count) of individual atoms.
-   In the case of materials, component proportions are defined by number, or mass fractions of individual substances.
 
 Further description of the Element, Substance and Material classes is given in the following sections.
 

docs/source/materials/materials.rst

@@ -3,7 +3,7 @@ Materials
 
 Materials can be formed from one or more substances and their corresponding number (``x``, ``Norm.NUMBER_FRACTION``), or mass (``X``, ``Norm.MASS_FRACTION``) fractions.
 If number fractions are given, mass fractions are calculated using substance masses, and vice versa.
-Number and mass fraction values are always normalized to unity.
+Number and mass fraction values of components within a composite are automatically normalized.
 
 Individual material components can be given in a form of a string (format ``fraction <substance> fraction <substance> ...``)
 
@@ -18,7 +18,7 @@ Individual material components can be given in a form of a string (format ``frac
     H2O       0.2 18.015286 10.0  8.00471 10.0
    NaCl       0.3 58.442707 28.0 30.48480 28.0
    
-   Compound:
+   Composit:
    
    expr  x[%]       X[%]
     H2O  40.0  17.047121
@@ -55,7 +55,7 @@ or as a dictionary
      O2    20.946 31.998810 16.0 16.008960 16.0
      Ar     0.934 39.947799 18.0 21.985398 18.0
     CO2     0.036 44.009546 22.0 22.019660 22.0
-   >>> m.print_compound()
+   >>> m.print_composite()
    expr    x[%]       X[%]
      N2  78.084  75.517607
      O2  20.946  23.139564

docs/source/materials/substances.rst

@@ -3,6 +3,7 @@ Substances
 
 Several element expressions can be combined into a more complex molecular formula.
 In this context, we consider as substances pure elements, chemical compounds and molecules.
+The syntax of molecular formulas used in this solver is based on standard molecular formulas known from chemistry.
 The substance expression solver currently supports the following 3 basic operations:
 
 .. csv-table:: Operations in molecular formulas
@@ -30,7 +31,7 @@ In this case, the option applies to all elements in a substance.
    >>> Substance('H2O', natural=False)
    Substance(mass=18.011 Z=10 N=8.000 e=10)
 
-A substance can also be initialised from an explicit dictionary of element expressions and corresponding proportions.
+A substance can also be initialized from an explicit dictionary of element expressions and corresponding proportions.
 
 .. code-block:: python
 
@@ -41,8 +42,8 @@ A substance can also be initialised from an explicit dictionary of element expre
    >>> })
    Substance(mass=31.059 Z=18 N=13.000 e=18)
 
-Besides information about elements and nucleon, every substance calculate also other parameters.
-In the example below, we show an example for the substance of water ``H2O``.
+Besides information about elements and nucleons, every substance calculates also other parameters.
+In the example below, we show an example of the substance of water ``H2O``.
 A concise overview of all its properties can be printed using its ``print()`` method.
 Here the ``mass`` is an atomic mass, ``Z`` proton number, ``N`` number of neutrons, ``e`` number of electrons, ``x`` number fraction and ``X`` is a mass fraction.
 
@@ -56,7 +57,7 @@ Here the ``mass`` is an atomic mass, ``Z`` proton number, ``N`` number of neutro
       H       H        1           0  1.007825    2.0  1  0  1
       O       O       16           0 15.994915    1.0  8  8  8
    
-   Compound:
+   Composite:
    
    Total mass:     Quantity(1.801e+01 Da)
    Total number:   3.0
@@ -82,11 +83,11 @@ Here the ``mass`` is an atomic mass, ``Z`` proton number, ``N`` number of neutro
 
 In the example above, we additionally set substance density ``rho`` and its volume ``V``.
 Density is used for calculation of number ``n`` and mass ``rho`` densities.
-If volume is also set, total number of species ``N`` and total mass ``M`` are added.
+If volume is also set, the total number of species ``N`` and total mass ``M`` are added.
 
-Individual substance parameters can be accessed directly using ``data_components()``, ``data_compound()`` and ``data_matter()``.
+Individual substance parameters can be accessed directly using ``data_components()``, ``data_composite()`` and ``data_matter()``.
 Both methods return a :ref:`ParameterTable <misc/parameter_table:parametertable>` object with corresponding values.
-Corresponding tabular values can be printed using method ``print_components()``, ``print_compound()`` and ``print_matter()``.
+Corresponding tabular values can be printed using method ``print_components()``, ``print_composite()`` and ``print_matter()``.
 
 .. code-block:: python
 
@@ -96,7 +97,7 @@ Corresponding tabular values can be printed using method ``print_components()``,
    8
    >>>     data.H.count
    2
-   >>>     data = c.data_compound()
+   >>>     data = c.data_composite()
    >>>     data['sum'].e
    10
    >>>     data.H.mass

src/scinumtools/materials/compound.py → src/scinumtools/materials/composite.py

@@ -14,17 +14,17 @@ class Component:
     def __init__(self, proportion:int=1):
         self.proportion = proportion
 
-class Compound:
-    components: Dict[str,Component] # list of compound components
-    component_class: callable       # name of the class that inherits Compound
+class Composite:
+    components: Dict[str,Component] # list of composite components
+    component_class: callable       # name of the class that inherits Composite
 
     cols_components: dict           # settings of component columns
-    cols_compound: dict             # settings of compound columns
+    cols_composit: dict             # settings of composite columns
 
     natural: bool                   # natural ements
-    norm_type: Norm                 # type of compound norm
+    norm_type: Norm                 # type of composite norm
     proportion_norm: Union[float,int] # sum of all comonent proportions
-    compound_mass: Quantity         # sum of all component masses
+    composite_mass: Quantity         # sum of all component masses
 
     def __enter__(self):
         return self
@@ -34,14 +34,14 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 
     def __init__(self, 
         solver:callable, component_class:callable, expr:Union[str,dict], 
-        cols_components: dict, cols_compound: dict,
+        cols_components: dict, cols_composite: dict,
         natural:bool, norm_type:Norm,
     ):
         self.expr = ''
         self.norm_type = norm_type
         self.natural = natural
         self.cols_components = cols_components
-        self.cols_compound = cols_compound | {
+        self.cols_composite = cols_composite | {
             "x":     Units.FRACTION, 
             "X":     Units.FRACTION,
         }
@@ -62,12 +62,12 @@ def _norm(self):
         components = self.components.values()
         if self.norm_type==Norm.MASS_FRACTION:
             self.proportion_norm = np.sum([i.proportion/i.component_mass for i in components])
-            self.compound_mass  = np.sum([i.proportion for i in components])
+            self.composite_mass  = np.sum([i.proportion for i in components])
         else:
             self.proportion_norm = np.sum([i.proportion for i in components])
-            self.compound_mass  = np.sum([i.proportion*i.component_mass for i in components])
+            self.composite_mass  = np.sum([i.proportion*i.component_mass for i in components])
         if type(self) in Component.__subclasses__():
-            self.component_mass = self.compound_mass
+            self.component_mass = self.composite_mass
         Matter._norm(self)
 
     def _data(self, columns:dict, fn_row:callable, stats:bool=False, weight:bool=False, components:list=None, quantity:bool=True):
@@ -87,11 +87,11 @@ def _data(self, columns:dict, fn_row:callable, stats:bool=False, weight:bool=Fal
             row, values = [], fn_row(s,m)
             if self.norm_type in [Norm.NUMBER_FRACTION, Norm.NUMBER]:
                 values['x'] = Quantity(m.proportion/self.proportion_norm)
-                values['X'] = m.proportion*m.component_mass/self.compound_mass
+                values['X'] = m.proportion*m.component_mass/self.composite_mass
                 weights.append(m.proportion)
             elif self.norm_type==Norm.MASS_FRACTION:
                 values['x'] = m.proportion/m.component_mass/self.proportion_norm
-                values['X'] = Quantity(m.proportion/self.compound_mass)
+                values['X'] = Quantity(m.proportion/self.composite_mass)
                 weights.append(m.proportion/m.component_mass)
             # convert to proper units
             for col in column_names:
@@ -122,20 +122,20 @@ def _data(self, columns:dict, fn_row:callable, stats:bool=False, weight:bool=Fal
 
         return pt
 
-    def _multiply(self, compound, other):
+    def _multiply(self, composite, other):
         for expr, component in self.components.items():
-            compound.add(expr, component.proportion*other)
-        return compound
+            composite.add(expr, component.proportion*other)
+        return composite
 
-    def _add(self, compound, other):
+    def _add(self, composite, other):
         for expr, component in self.components.items():
-            compound.add(expr, component.proportion)
+            composite.add(expr, component.proportion)
         if isinstance(other, self.component_class):
-            compound.add(other.expr, other.proportion)
+            composite.add(other.expr, other.proportion)
         else:
             for expr, component in other.components.items():
-                compound.add(expr, component.proportion)
-        return compound
+                composite.add(expr, component.proportion)
+        return composite
 
     def _add_expr(self, expr:str, proportion:int):
         pass
@@ -156,21 +156,21 @@ def _print_table(self, columns:dict, fn_data:callable, **kwargs):
     def print_components(self):
         self._print_table(self.cols_components, self.data_components)
 
-    def print_compound(self, components:list=None):
-        self._print_table(self.cols_compound, self.data_compound, components=components)
+    def print_composite(self, components:list=None):
+        self._print_table(self.cols_composite, self.data_composite, components=components)
 
     def print(self):
         print("Components:")
         print("")
         self._print_table(self.cols_components, self.data_components)
         print("")
-        print("Compound:")
+        print("Composite:")
         if self.norm_type == Norm.NUMBER:
             print("")
-            print(f"Total mass:     {self.compound_mass}")
+            print(f"Total mass:     {self.composite_mass}")
             print(f"Total number:   {self.proportion_norm}")
         print("")
-        self._print_table(self.cols_compound, self.data_compound)
+        self._print_table(self.cols_composite, self.data_composite)
         if self.mass_density:
             print("")
             Matter.print(self)

src/scinumtools/materials/element.py

@@ -3,7 +3,7 @@
 
 from . import Units
 from .matter import Matter
-from .compound import Component
+from .composite import Component
 from .periodic_table import *
 from ..units import Quantity, Unit
 from .. import RowCollector, ParameterTable
@@ -101,7 +101,7 @@ def __init__(self, expr:str, proportion:int=1, natural:bool=True, **kwargs):
         else:
             raise Exception('Unrecognized expr', expr)
         self.component_mass = self.mass
-        self.compound_mass = self.mass
+        self.composite_mass = self.mass
         Matter._norm(self)
 
     def __mul__(self, other:float):