[ci skip] 📝 update docstrings

rayflare/rigorous_coupled_wave_analysis/rcwa.py

@@ -1123,13 +1123,28 @@ def vs_pol(s, p):
         return xs, ys, E, H, E_mag, H_mag
 
     def set_widths(self, new_widths):
+        """Allows the user to set new widths for the layers in the structure.
+
+        :param new_widths: new layer widths, in nm.
+        """
+
         new_widths = np.append(np.insert(np.array(new_widths, dtype='f'), 0, np.inf), np.inf).tolist()
         self.widths = new_widths
 
     def set_size(self, new_size):
+        """Allows the user to set new basis vectors for the structure.
+
+        :param new_size: new basis vectors in the format ((x1, y1), (x2, y2))
+        """
         self.size = new_size
 
     def edit_geom_list(self, layer_index, geom_index, geom_entry):
+        """Allows the user to edit the geom_list of a specific layer in the structure.
+
+        :param layer_index: for which layer to edit the geom_list; 0 is the incidence medium
+        :param geom_index: which entry in that layer's geom_list to change
+        :param geom_entry: new entry for the geom_list.
+        """
 
         self.geom_list[layer_index][geom_index].update(geom_entry)
 

rayflare/textures/define_textures.py

@@ -10,12 +10,12 @@
 
 
 def xyz_texture(x, y, z):
-    """
+    """Defines RTSurface textures for ray-tracing based on lists of x, y and z coordinates provided by the user.
 
     :param x: list of x (in-plane) coordinates of points on the surface texture (1D numpy array)
     :param y: list of y (in-plane) coordinates of points on the surface texture (1D numpy array)
     :param z: list of z (height) coordinates of points on the surface texture (1D numpy array)
-    :return:
+    :return: a list of two RTSurface objects: [front_incidence, rear_incidence]
 
     """
     Points = np.vstack([x, y, z]).T
@@ -28,13 +28,15 @@ def xyz_texture(x, y, z):
 
 
 def heights_texture(z_points, x_width, y_width):
-    """
+    """Defines RTSurface textures for ray-tracing based on a 2D array of z coordinates and the width along the x and
+    y directions.
 
-    :param z_points: list of z (height) coordinates of points on the surface texture (2D numpy array)
+    :param z_points: array of z (height) coordinates of points on the surface texture (2D numpy array)
     :param x_width: width along the x direction
     :param y_width: width along the y direction
-    :return:
+    :return: a list of two RTSurface objects: [front_incidence, rear_incidence]
     """
+
     x = np.linspace(0, x_width, z_points.shape[0])
     y = np.linspace(0, y_width, z_points.shape[1])
 

rayflare/textures/standard_rt_textures.py

@@ -11,12 +11,13 @@
 import os
 
 def regular_pyramids(elevation_angle=55, upright=True, size=1):
-    """
+    """Defines RTSurface textures for ray-tracing of regular upright or inverted pyramids.
 
-    :param elevation_angle:
-    :param upright:
-    :param size:
-    :return:
+    :param elevation_angle: angle between the horizontal and a face of the pyramid, in degrees
+    :param upright: if True, upright pyramids. If False, inverted pyramids
+    :param size: size of the pyramids; the units are arbitrary, but should be kept consistent across
+            different interfaces if you are not randomizing the ray positions.
+    :return: a list of two RTSurface objects: [front_incidence, rear_incidence]
     """
 
     char_angle = math.radians(elevation_angle)
@@ -41,10 +42,10 @@ def regular_pyramids(elevation_angle=55, upright=True, size=1):
     return [surf_fi, surf_ri]
 
 def planar_surface(size=1):
-    """
+    """Defines RTSurface textures for ray-tracing for a planar surface for ray-tracing.
 
-    :param size:
-    :return:
+    :param size: size of the unit cell (this should not affect the results, as the surface is planar).
+    :return: a list of two RTSurface objects: [front_incidence, rear_incidence]
     """
     Lx = 1*size
     Ly = 1*size
@@ -60,9 +61,10 @@ def planar_surface(size=1):
 
 
 def random_pyramids():
-    """
+    """Defines RTSurface textures for ray-tracing for a surface of random pyramids (based on
+    real surface scan data).
 
-    :return:
+    :return: a list of two RTSurface objects: [front_incidence, rear_incidence]
     """
     cur_path = os.path.dirname(os.path.abspath(__file__))
     z_map = np.loadtxt(os.path.join(cur_path, 'pyramids.csv'), delimiter=',')
@@ -83,12 +85,13 @@ def random_pyramids():
 
 
 def V_grooves(elevation_angle=55, width=1, direction='y'):
-    """
+    """Defines RTSurface textures for ray-tracing for a surface of V-grooves.
 
-    :param elevation_angle:
-    :param width:
-    :param direction:
-    :return:
+    :param elevation_angle: angle between the horizontal and a face of the V-grooves, in degrres
+    :param width: width of the V-grooves (units are arbitrary but should be kept consistent between surfaces
+            if you are not randomizing the ray positions).
+    :param direction: Whether the V-grooves lie along the 'x' or 'y' direction (string)
+    :return: a list of two RTSurface objects: [front_incidence, rear_incidence]
     """
     char_angle = math.radians(elevation_angle)
     h = width*math.tan(char_angle)/2