From 32f149a46eda80193e8dfa1d48b12d8ca95bd551 Mon Sep 17 00:00:00 2001
From: VsevolodX <79542055+VsevolodX@users.noreply.github.com>
Date: Mon, 16 Sep 2024 13:53:14 -0700
Subject: [PATCH] chore: add docstrings

---
 .../made/tools/calculate/calculators.py       | 69 +++++++++++++++++--
 1 file changed, 64 insertions(+), 5 deletions(-)

diff --git a/src/py/mat3ra/made/tools/calculate/calculators.py b/src/py/mat3ra/made/tools/calculate/calculators.py
index bbd9b4fc..963096e3 100644
--- a/src/py/mat3ra/made/tools/calculate/calculators.py
+++ b/src/py/mat3ra/made/tools/calculate/calculators.py
@@ -12,21 +12,73 @@
 
 
 class MaterialCalculatorParameters(BaseModel):
+    """
+    Defines the parameters for a material calculator.
+
+    Args:
+        interaction_function (Callable): A function used to calculate the interaction metric between
+        sets of coordinates. The default function is sum_of_inverse_distances_squared.
+    """
+
     interaction_function: Callable = sum_of_inverse_distances_squared
 
 
 class InterfaceMaterialCalculatorParameters(MaterialCalculatorParameters):
+    """
+    Parameters specific to the calculation of interaction energies between
+    an interface material's film and substrate.
+
+    Args:
+        shadowing_radius (float): Radius used to determine the surface atoms of the film or substrate
+                                  for interaction calculations. Default is 2.5 Å.
+    """
+
     shadowing_radius: float = 2.5
 
 
 class MaterialCalculator(BaseModel):
+    """
+    A base class for performing calculations on materials.
+
+    This class uses the parameters defined in MaterialCalculatorParameters to calculate
+    interaction metrics between atoms or sets of coordinates within the material.
+
+    Args:
+        calculator_parameters (MaterialCalculatorParameters): Parameters controlling the calculator,
+        including the interaction function.
+    """
+
     calculator_parameters: MaterialCalculatorParameters = MaterialCalculatorParameters()
 
     def get_energy(self, material: Material):
+        """
+        Calculate the energy (or other metric) for a material.
+
+        Args:
+            material (Material): The material to calculate the interaction energy for.
+
+        Returns:
+            float: The interaction energy between the coordinates of the material,
+            calculated using the specified interaction function.
+        """
         return self.calculator_parameters.interaction_function(material.coordinates, material.coordinates)
 
 
 class InterfaceMaterialCalculator(MaterialCalculator):
+    """
+    A specialized calculator for computing the interaction energy between a film and a substrate
+    in an interface material.
+
+    This class extends MaterialCalculator and uses additional parameters specific to interface materials,
+    such as the shadowing radius to detect surface atoms.
+
+    Args:
+        calculator_parameters (InterfaceMaterialCalculatorParameters): Parameters that include the
+        shadowing radius and interaction function.
+    """
+
+    calculator_parameters: InterfaceMaterialCalculatorParameters = InterfaceMaterialCalculatorParameters()
+
     def get_energy(
         self,
         material: Material,
@@ -34,17 +86,24 @@ def get_energy(
         interaction_function: Callable = sum_of_inverse_distances_squared,
     ) -> float:
         """
-        Calculate the interaction metric between the film and substrate.
+        Calculate the interaction energy between the film and substrate in an interface material.
+
+        This method uses the shadowing radius to detect surface atoms and applies the given
+        interaction function to calculate the interaction between the film and substrate.
+
         Args:
-            material (Material): The interface Material object.
-            shadowing_radius (float): The shadowing radius to detect the surface atoms, in Angstroms.
-            interaction_function (Callable): The metric function to use for the calculation of the interaction.
+            material (Material): The interface Material object consisting of both the film and substrate.
+            shadowing_radius (float): The radius used to detect surface atoms for the interaction
+                                      calculation. Defaults to 2.5 Å.
+            interaction_function (Callable): A function to compute the interaction between the film and
+                                             substrate. Defaults to sum_of_inverse_distances_squared.
 
         Returns:
-            float: The calculated norm.
+            float: The calculated interaction energy between the film and substrate.
         """
         film_material = get_interface_part(material, part=InterfacePartsEnum.FILM)
         substrate_material = get_interface_part(material, part=InterfacePartsEnum.SUBSTRATE)
+
         film_surface_atom_indices = get_surface_atom_indices(
             film_material, SurfaceTypes.BOTTOM, shadowing_radius=shadowing_radius
         )