refactor documentation

Author: otvam

pypeec/lib_matrix/green_function.py

@@ -3,14 +3,14 @@
 Analytical solutions and numerical approximations are used.
 
 The two following integrals are available:
-    - Integrate all the dimensions (6D integrals).
-    - Integrate the dimensions except the last one (5D integrals).
+    - Integrate all the dimensions (for the inductance and potential matrices).
+    - Integrate the dimensions except the last one (for the coupling matrices).
 
 Exact Inductance Equations for Rectangular Conductors With Applications to More Complicated Geometries
-C. Hoer and C. Love, 1965
+C. Hoer and C. Love, Journal of Research of the National Bureau of Standards, 1965
 
 Exact Closed Form Formula for Self Inductance of Conductor of Rectangular Cross Section
-Z. Piatek and B. Baron, 2021
+Z. Piatek and B. Baron, Progress In Electromagnetics Research, 2012
 """
 
 __author__ = "Thomas Guillod"
@@ -207,7 +207,7 @@ def _get_green_preproc(int_type):
 def get_green_ana(d, idx, int_type):
     """
     Compute a Green function between two voxels.
-    An analytical solution is used.
+    A stable analytical solution is used.
     The 5D or 6D integrals can be computed.
     """
 
@@ -255,7 +255,7 @@ def get_green_num(d, idx, int_type):
     """
     Compute a Green function between two voxels.
     The 5D or 6D integrals can be computed.
-    A numerical approximation is used.
+    A fast numerical approximation is used.
     Only valid if the distance between the two voxels is large.
     """
 

pypeec/lib_matrix/matrix_factorization.py

@@ -5,6 +5,7 @@
     - SuperLU is typically slower but is always available (integrated with SciPy).
     - PARDISO is typically faster than SuperLU (available through Pydiso).
     - PyAMG is typically slow but uses less memory (risk of convergence issues).
+    - Diagonal is a dummy factorization (only for debugging).
 
 This module is only importing the required matrix solver.
 This means that the unused matrix solvers are not required.

pypeec/lib_matrix/matrix_multiply.py

@@ -5,19 +5,21 @@
 
 Three different types of matrices are supported:
     - Tensor representing a simple potential matrix.
-        - Size of the last dimension of the input tensor => 1.
-        - Number of dimensions of the input vector => 1.
-        - Number of dimensions of the output vector => 1.
+        - Size of the last dimension of the input tensor: 1.
+        - Number of dimensions of the input vector: 1.
+        - Number of dimensions of the output vector: 1.
     - Tensor representing a block diagonal inductance matrix.
-        - Size of the last dimension of the input tensor => 1.
-        - Number of dimensions of the input vector => 3.
-        - Number of dimensions of the output vector => 3.
+        - Size of the last dimension of the input tensor: 1.
+        - Number of dimensions of the input vector: 3.
+        - Number of dimensions of the output vector: 3.
     - Tensor representing a block off-diagonal coupling matrix.
-        - Size of the last dimension of the input tensor => 3.
-        - Number of dimensions of the input vector => 3.
-        - Number of dimensions of the output vector => 3.
+        - Size of the last dimension of the input tensor: 3.
+        - Number of dimensions of the input vector: 3.
+        - Number of dimensions of the output vector: 3.
 
-A matrix-vector operator is returned for performing the matrix-vector multiplication.
+A matrix-vector operator is returned for performing the matrix-vector multiplication:
+    - For standard multiplication, the full matrix is constructed and stored.
+    - For FFT multiplication, the full matrix is never constructed nor stored.
 """
 
 __author__ = "Thomas Guillod"

pypeec/lib_matrix/multiply_fft.py

@@ -358,18 +358,6 @@ def _get_prepare_sub(name, idx_out, idx_in, mat):
     return name, n_in, n_out, idx_in_mat, idx_out_mat, mat_fft
 
 
-def get_prepare(name, idx_out, idx_in, mat):
-    """
-    Construct a circulant tensor from a 4D tensor (log wrapper).
-    """
-
-    LOGGER.debug("multiplication: %s" % name)
-    with LOGGER.BlockIndent():
-        data = _get_prepare_sub(name, idx_out, idx_in, mat)
-
-    return data
-
-
 def set_options(fft_options):
     """
     Assign the options and load the right libray.
@@ -399,6 +387,18 @@ def set_options(fft_options):
     NPCP = lib_tmp
 
 
+def get_prepare(name, idx_out, idx_in, mat):
+    """
+    Construct a circulant tensor from a 4D tensor (log wrapper).
+    """
+
+    LOGGER.debug("multiplication: %s" % name)
+    with LOGGER.BlockIndent():
+        data = _get_prepare_sub(name, idx_out, idx_in, mat)
+
+    return data
+
+
 def get_multiply(data, vec_in, flip):
     """
     Matrix-vector multiplication with FFT.

pypeec/lib_mesher/mesher_voxel.py

@@ -1,5 +1,5 @@
 """
-Module for parsing voxel indices.
+Module for creating a voxel structure from given indices.
 Transform the voxel indices into NumPy arrays.
 Check the validity of the indices.
 """

pypeec/lib_mesher/voxel_conflict.py

@@ -1,6 +1,6 @@
 """
 Different functions for resolving conflict between domains.
-Detect and remove shared indices (conflict) between domains.
+Check the integrity of the voxel structure after the resolution.
 """
 
 __author__ = "Thomas Guillod"
@@ -14,9 +14,8 @@
 def _get_solve_overlap(domain_def, conflict_rules):
     """
     Detect and remove shared indices (conflict) between two domains.
-    The conflict is solved in the following way:
-        - The reference domain indices remain unchanged.
-        - The shared indices are removed from the domain to be fixed.
+    The duplicated indices are removed from the domains to be resolved.
+    The reference domains indices remain unchanged.
     """
 
     # extract the data

pypeec/lib_plot/manage_pyvista.py

@@ -340,9 +340,6 @@ def _get_arrow(obj, data_plot):
 def _plot_scalar(pl, obj, data_plot, plot_clip, plot_theme):
     """
     Plot a scalar variable.
-    The plot is either made on:
-        - the unstructured grid describing the non-empty voxels
-        - the polydata (point cloud) used to evaluate the field
     """
 
     # extract
@@ -387,10 +384,6 @@ def _plot_scalar(pl, obj, data_plot, plot_clip, plot_theme):
 def _plot_arrow(pl, grid, obj, data_plot, plot_clip, plot_theme):
     """
     Plot a vector variable with an arrow plot (quiver plot).
-    The plot is either made on:
-        - the unstructured grid describing the non-empty voxels
-        - the polydata (point cloud) used to evaluate the field
-
     A scalar variable is used to determine the color of the arrows.
     The length of the arrows is constant (and scaled with respect to the voxel size).
     """

pypeec/lib_solver/equation_system.py

@@ -2,8 +2,8 @@
 Different functions for building the equation system.
 
 Two different equation systems are built:
-     - A sparse system for the preconditioner.
-     - A dense system for the iterative solver.
+    - A sparse system for the preconditioner.
+    - A dense system for the iterative solver.
 
 The voxel structure has the following size: (nx, ny, nz).
 The problem contains n_vc non-empty electric voxels and n_vm non-empty magnetic voxels.
@@ -85,9 +85,9 @@
 Only volume charges are used, which is an approximation.
 
 For the preconditioner, the following simplifications are made:
-     - The dense inductance matrix is diagonalized.
-     - The dense potential matrix is diagonalized.
-     - The electric-magnetic coupling matrices are neglected.
+    - The dense inductance matrix is diagonalized.
+    - The dense potential matrix is diagonalized.
+    - The electric-magnetic coupling matrices are neglected.
 
 With these assumptions, a sparse (electric and magnetic) equation system is obtained.
 The preconditioner is solved separately for the electric and magnetic equations.
@@ -127,9 +127,8 @@ def _get_system_size(A_net_c, A_net_m, A_src):
     """
     Get the size of the equation system.
 
-    The equation system has the following size:
-        - n_fc+n_vc+n_src_c+n_src_v: electric system
-        - n_fm+n_vm: magnetic system
+    The electric system has the following size: n_fc+n_vc+n_src_c+n_src_v.
+    The magnetic system has the following size: n_fm+n_vm.
     """
 
     # get the matrices
@@ -200,9 +199,7 @@ def _get_cond_fact_electric(freq, A_net_c, R_c, L_c, A_src):
     Compute the sparse matrices using for the electric preconditioner.
 
     The equation system has the following size: n_fc+n_vc+n_src_c+n_src_v.
-    The equation system is split in two subsystems:
-        - n_fc (diagonal block size)
-        - n_vc+n_src_c+n_src_v (sparse block size)
+    The first (n_fc, n_fc) block is a diagonal matrix:
     """
 
     # get the matrices
@@ -242,9 +239,7 @@ def _get_cond_fact_magnetic(A_net_m, R_m, P_m):
     Compute the sparse matrices using for the magnetic preconditioner.
 
     The equation system has the following size: n_fm+n_vm.
-    The equation system is split in two subsystems:
-        - n_fm (diagonal block size)
-        - n_vm (sparse block size)
+    The first (n_fm, n_fm) block is a diagonal matrix:
     """
 
     # get the system size
@@ -407,9 +402,9 @@ def get_source_matrix(idx_vc, idx_src_c, idx_src_v, Y_src_c, Z_src_v):
     The source matrices connect the sources to the rest of the system.
 
     The source matrices have the following sizes:
-        - A_vc_src: (n_vc, n_src_c+n_src_v)
-        - A_src_vc: (n_src_c+n_src_v, n_vc)
-        - A_src_src: (n_src_c+n_src_v, n_src_c+n_src_v)
+        - A_vc_src which contains A_vc_src_c and A_vc_src_v: (n_vc, n_src_c+n_src_v).
+        - A_src_vc which contains A_src_c_vc and A_src_v_vc: (n_src_c+n_src_v, n_vc).
+        - A_src_src which contains A_src_c_src_c and A_src_v_src_v: (n_src_c+n_src_v, n_src_c+n_src_v).
 
     It should be noted that the matrices connecting the magnetic voxels are all-zeros.
     This is explained by the fact that the sources are only connected to electric voxels.

pypeec/lib_solver/extract_convergence.py

@@ -1,9 +1,8 @@
 """
-Provide a function to extract convergence metrics from the solution vector.
-
-The complex power is extracted at the different terminals.
-The total complex power is computed for all the terminals.
-The active and reactive power are returned as metrics.
+Provide functions to extract convergence metrics from the solution vector:
+    - The complex power is extracted at the different terminals.
+    - The total complex power is combined for all the terminals.
+    - The active and reactive power are returned as metrics.
 """
 
 __author__ = "Thomas Guillod"

pypeec/lib_solver/extract_solution.py

@@ -1,11 +1,10 @@
 """
-Different functions for extracting the fields and terminal currents and voltages from the solution vector.
-
-Extract the different fields.
-Extract the losses and energy.
-Extract the integral quantities.
-Extract the source terminal currents and voltages.
-Compute the magnetic field for the point cloud.
+Different functions for extracting the fields and terminal currents and voltages from the solution vector:
+    - Extract the different fields.
+    - Extract the losses and energy.
+    - Extract the integral quantities.
+    - Extract the source terminal currents and voltages.
+    - Compute the magnetic field for the point cloud.
 
 Warning
 -------