Enhance documentation and code clarity across multiple scripts by updating function descriptions, organizing imports, and improving formatting for better readability

Author: nikoscham

CONTRIBUTING.md

@@ -20,7 +20,62 @@ Thank you for your interest in contributing! FEAScript is in early development,
    ```
 
    FEAScript can be run on a local server. To start a local server, you can use [Python HTTP Server](https://docs.python.org/3/library/http.server.html):
-      ```bash
-      python -m http.server
-      ```
+
+   ```bash
+   python -m http.server
+   ```
+
    where the server will be available at `http://127.0.0.1:8000/`. Static file server npm packages like [serve](https://github.com/vercel/serve#readme) and [Vite](https://vite.dev/) can also be used.
+
+## File Structure Guidelines
+
+All files in the FEAScript-core codebase should follow this structure:
+
+1. **Banner**: All files start with the FEAScript ASCII art banner
+2. **Imports**:
+   - External imports (from npm packages) first, alphabetically ordered
+   - Internal imports next, grouped by module/folder
+3. **Classes/Functions**: Implementation with proper JSDoc comments
+
+Example:
+
+```javascript
+//   ______ ______           _____           _       _     //
+//  |  ____|  ____|   /\    / ____|         (_)     | |    //
+//  | |__  | |__     /  \  | (___   ___ ____ _ ____ | |_   //
+//  |  __| |  __|   / /\ \  \___ \ / __|  __| |  _ \| __|  //
+//  | |    | |____ / ____ \ ____) | (__| |  | | |_) | |    //
+//  |_|    |______/_/    \_\_____/ \___|_|  |_|  __/| |    //
+//                                            | |   | |    //
+//                                            |_|   | |_   //
+//       Website: https://feascript.com/             \__|  //
+
+// External imports
+import { mathLibrary } from "math-package";
+
+// Internal imports
+import { relatedFunction } from "../utilities/helperScript.js";
+
+/**
+ * Class to handle specific functionality
+ */
+export class MyClass {
+  /**
+   * Constructor to initialize the class
+   * @param {object} options - Configuration options
+   */
+  constructor(options) {
+    // Implementation
+  }
+
+  /**
+   * Function to perform a specific action
+   * @param {number} input - Input value
+   * @returns {number} Processed result
+   */
+  doSomething(input) {
+    // Implementation
+    return input * DEFAULT_VALUE;
+  }
+}
+```

src/FEAScript.js

@@ -8,12 +8,13 @@
 //                                            |_|   | |_   //
 //       Website: https://feascript.com/             \__|  //
 
-import { assembleSolidHeatTransferMat } from "./solvers/solidHeatTransferScript.js";
+// Internal imports
 import { jacobiMethod } from "./methods/jacobiMethodScript.js";
+import { assembleSolidHeatTransferMat } from "./solvers/solidHeatTransferScript.js";
 import { basicLog, debugLog } from "./utilities/loggingScript.js";
 
 /**
- * FEAScript: An open-source finite element simulation library developed in JavaScript
+ * Class to implement finite element analysis in JavaScript
  * @param {string} solverConfig - Parameter specifying the type of solver
  * @param {object} meshConfig - Object containing computational mesh details
  * @param {object} boundaryConditions - Object containing boundary conditions for the finite element analysis
@@ -35,7 +36,11 @@ export class FEAScriptModel {
 
   setMeshConfig(meshConfig) {
     this.meshConfig = meshConfig;
-    debugLog(`Mesh config set with dimensions: ${meshConfig.meshDimension}, elements: ${meshConfig.numElementsX}x${meshConfig.numElementsY || 1}`);
+    debugLog(
+      `Mesh config set with dimensions: ${meshConfig.meshDimension}, elements: ${meshConfig.numElementsX}x${
+        meshConfig.numElementsY || 1
+      }`
+    );
   }
 
   addBoundaryCondition(boundaryKey, condition) {
@@ -83,14 +88,14 @@ export class FEAScriptModel {
       const initialGuess = new Array(residualVector.length).fill(0);
       // Call Jacobi method with desired max iterations and tolerance
       const jacobiResult = jacobiMethod(jacobianMatrix, residualVector, initialGuess, 1000, 1e-6);
-      
+
       // Log convergence information
       if (jacobiResult.converged) {
         debugLog(`Jacobi method converged in ${jacobiResult.iterations} iterations`);
       } else {
         debugLog(`Jacobi method did not converge after ${jacobiResult.iterations} iterations`);
       }
-      
+
       solutionVector = jacobiResult.solution;
     }
     console.timeEnd("systemSolving");

src/mesh/basisFunctionsScript.js

@@ -23,7 +23,7 @@ export class basisFunctions {
   }
 
   /**
-   * Return the basis functions and their derivatives based on the dimension and order
+   * Function to calculate basis functions and their derivatives based on the dimension and order
    * @param {number} ksi - Natural coordinate (for both 1D and 2D)
    * @param {number} [eta] - Second natural coordinate (only for 2D elements)
    * @returns {object} An object containing:

src/mesh/meshGenerationScript.js

@@ -8,13 +8,13 @@
 //                                            |_|   | |_   //
 //       Website: https://feascript.com/             \__|  //
 
-/**
- * Class to handle the generation of structured finite element meshes
- */
-
+// Internal imports
 import { importGmshQuadTri } from "../readers/gmshReaderScript.js";
 import { errorLog } from "../utilities/loggingScript.js";
 
+/**
+ * Class to handle the generation of structured finite element meshes
+ */
 export class meshGeneration {
   /**
    * Constructor to initialize the meshGeneration class
@@ -46,7 +46,7 @@ export class meshGeneration {
   }
 
   /**
-   * Generate the mesh based on the dimension or custom mesh file
+   * Function to generate the mesh based on the dimension or custom mesh file
    * @returns {object} The generated mesh containing node coordinates and total nodes
    */
   generateMesh() {
@@ -64,7 +64,12 @@ export class meshGeneration {
           throw new Error(errorMessage);
         }
       } else if (this.meshDimension === "2D") {
-        if (this.numElementsX === null || this.maxX === null || this.numElementsY === null || this.maxY === null) {
+        if (
+          this.numElementsX === null ||
+          this.maxX === null ||
+          this.numElementsY === null ||
+          this.maxY === null
+        ) {
           const errorMessage =
             "numElementsX, maxX, numElementsY, and maxY are required parameters when generating a 2D mesh from geometry";
           errorLog(errorMessage);
@@ -78,7 +83,7 @@ export class meshGeneration {
   }
 
   /**
-   * Parse a custom mesh JSON file and generate the mesh
+   * Function to parse a custom mesh JSON file and generate the mesh
    * @param {string} meshFilePath - Path to the custom mesh file (JSON format)
    * @returns {object} Mesh data containing coordinates and connectivity
    */
@@ -106,7 +111,7 @@ export class meshGeneration {
   }
 
   /**
-   * Generate a structured mesh based on the msh file
+   * Function to generate a structured mesh based on the msh file
    * @returns {object} An object containing the coordinates of nodes,
    * total number of nodes, nodal numbering (NOP) array, and boundary elements
    */
@@ -118,7 +123,7 @@ export class meshGeneration {
   }
 
   /**
-   * Generate a structured mesh based on the geometry configuration
+   * Function to generate a structured mesh based on the geometry configuration
    * @returns {object} An object containing the coordinates of nodes,
    * total number of nodes, nodal numbering (NOP) array, and boundary elements
    */
@@ -233,21 +238,13 @@ export class meshGeneration {
   }
 
   /**
-   * Find the elements that belong to each boundary for a simple rectangular domain
+   * Function to find the elements that belong to each boundary for a simple rectangular domain
    * @returns {array} An array containing arrays of elements and their adjacent boundary side for each boundary
    * Each element in the array is of the form [elementIndex, side], where side for a rectangular element is:
    * 0 - Bottom side
    * 1 - Left side
    * 2 - Top side
    * 3 - Right side
-   *
-   * Example representation of boundaryElements array in case of a rectangular element:
-   * boundaryElements = [
-   *   [[element1, 0], [element2, 0], [element3, 0], ...], // Bottom boundary
-   *   [[element*, 1], [element*, 1], [element*, 1], ...], // Left boundary
-   *   [[element*, 2], [element*, 2], [element*, 2], ...], // Top boundary
-   *   [[element*, 3], [element*, 3], [element*, 3], ...]  // Right boundary
-   * ];
    */
   findBoundaryElements() {
     const boundaryElements = [];
@@ -294,7 +291,7 @@ export class meshGeneration {
   }
 
   /**
-   * Generate the nodal numbering (NOP) array for a structured mesh
+   * Function to generate the nodal numbering (NOP) array for a structured mesh
    * This array represents the connectivity between elements and their corresponding nodes
    * @param {number} numElementsX - Number of elements along the x-axis
    * @param {number} [numElementsY] - Number of elements along the y-axis (optional for 1D)

src/methods/jacobiMethodScript.js

@@ -9,7 +9,7 @@
 //       Website: https://feascript.com/             \__|  //
 
 /**
- * Solves a system of linear equations using the Jacobi iterative method
+ * Function to solve a system of linear equations using the Jacobi iterative method
  * @param {array} A - The coefficient matrix (must be square)
  * @param {array} b - The right-hand side vector
  * @param {array} x0 - Initial guess for solution vector
@@ -22,9 +22,9 @@
  */
 export function jacobiMethod(A, b, x0, maxIterations = 100, tolerance = 1e-7) {
   const n = A.length; // Size of the square matrix
-  let x = [...x0];    // Current solution (starts with initial guess)
+  let x = [...x0]; // Current solution (starts with initial guess)
   let xNew = new Array(n); // Next iteration's solution
-  
+
   for (let iteration = 0; iteration < maxIterations; iteration++) {
     // Perform one iteration
     for (let i = 0; i < n; i++) {
@@ -38,30 +38,30 @@ export function jacobiMethod(A, b, x0, maxIterations = 100, tolerance = 1e-7) {
       // Update xNew[i] using the Jacobi formula
       xNew[i] = (b[i] - sum) / A[i][i];
     }
-    
+
     // Check convergence
     let maxDiff = 0;
     for (let i = 0; i < n; i++) {
       maxDiff = Math.max(maxDiff, Math.abs(xNew[i] - x[i]));
     }
-    
+
     // Update x for next iteration
     x = [...xNew];
-    
+
     // Successfully converged if maxDiff is less than tolerance
     if (maxDiff < tolerance) {
       return {
         solution: x,
         iterations: iteration + 1,
-        converged: true
+        converged: true,
       };
     }
   }
-  
+
   // maxIterations were reached without convergence
   return {
     solution: x,
     iterations: maxIterations,
-    converged: false
+    converged: false,
   };
-}
+}

src/methods/numericalIntegrationScript.js

@@ -13,17 +13,17 @@
  */
 export class numericalIntegration {
   /**
-   * Constructor to initialize the numIntegration class
+   * Constructor to initialize the numericalIntegration class
    * @param {string} meshDimension - The dimension of the mesh
-   * @param {number} elementOrder - The order of elements
+   * @param {string} elementOrder - The order of elements
    */
   constructor({ meshDimension, elementOrder }) {
     this.meshDimension = meshDimension;
     this.elementOrder = elementOrder;
   }
 
   /**
-   * Return Gauss points and weights based on element configuration
+   * Function to return Gauss points and weights based on element configuration
    * @returns {object} An object containing:
    *  - gaussPoints: Array of Gauss points
    *  - gaussWeights: Array of Gauss weights