10000 Enhance documentation and code clarity across multiple scripts by upd… · FEAScript/FEAScript-core@d2f75f8 · GitHub
[go: up one dir, main page]
Skip to content

Commit d2f75f8

Browse files
nikoschamnikoscham
committed
Enhance documentation and code clarity across multiple scripts by updating function descriptions, organizing imports, and improving formatting for better readability
1 parent b679f4d commit d2f75f8

13 files changed

+184
-151
lines changed

‎CONTRIBUTING.md

Lines changed: 58 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,62 @@ Thank you for your interest in contributing! FEAScript is in early development,
2020
```
2121

2222
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):
23-
```bash
24-
python -m http.server
25-
```
23+
24+
```bash
25+
python -m http.server
26+
```
27+
2628
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.
29+
30+
## File Structure Guidelines
31+
32+
All files in the FEAScript-core codebase should follow this structure:
33+
34+
1. **Banner**: All files start with the FEAScript ASCII art banner
35+
2. **Imports**:
36+
- External imports (from npm packages) first, alphabetically ordered
37+
- Internal imports next, grouped by module/folder
38+
3. **Classes/Functions**: Implementation with proper JSDoc comments
39+
40+
Example:
41+
42+
```javascript
43+
// ______ ______ _____ _ _ //
44+
// | ____| ____| /\ / ____| (_) | | //
45+
// | |__ | |__ / \ | (___ ___ ____ _ ____ | |_ //
46+
// | __| | __| / /\ \ \___ \ / __| __| | _ \| __| //
47+
// | | | |____ / ____ \ ____) | (__| | | | |_) | | //
48+
// |_| |______/_/ \_\_____/ \___|_| |_| __/| | //
49+
// | | | | //
50+
// |_| | |_ //
51+
// Website: https://feascript.com/ \__| //
52+
53+
// External imports
54+
import { mathLibrary } from "math-package";
55+
56+
// Internal imports
57+
import { relatedFunction } from "../utilities/helperScript.js";
58+
59+
/**
60+
* Class to handle specific functionality
61+
*/
62+
export class MyClass {
63+
/**
64+
* Constructor to initialize the class
65+
* @param {object} options - Configuration options
66+
*/
67+
constructor(options) {
68+
// Implementation
69+
}
70+
71+
/**
72+
* Function to perform a specific action
73+
* @param {number} input - Input value
74+
* @returns {number} Processed result
75+
*/
76+
doSomething(input) {
77+
// Implementation
78+
return input * DEFAULT_VALUE;
79+
}
80+
}
81+
```

‎src/FEAScript.js

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,13 @@
88
// |_| | |_ //
99
// Website: https://feascript.com/ \__| //
1010

11-
import { assembleSolidHeatTransferMat } from "./solvers/solidHeatTransferScript.js";
11+
// Internal imports
1212
import { jacobiMethod } from "./methods/jacobiMethodScript.js";
13+
import { assembleSolidHeatTransferMat } from "./solvers/solidHeatTransferScript.js";
1314
import { basicLog, debugLog } from "./utilities/loggingScript.js";
1415

1516
/**
16-
* FEAScript: An open-source finite element simulation library developed in JavaScript
17+
* Class to implement finite element analysis in JavaScript
1718
* @param {string} solverConfig - Parameter specifying the type of solver
1819
* @param {object} meshConfig - Object containing computational mesh details
1920
* @param {object} boundaryConditions - Object containing boundary conditions for the finite element analysis
@@ -35,7 +36,11 @@ export class FEAScriptModel {
3536

3637
setMeshConfig(meshConfig) {
3738
this.meshConfig = meshConfig;
38-
debugLog(`Mesh config set with dimensions: ${meshConfig.meshDimension}, elements: ${meshConfig.numElementsX}x${meshConfig.numElementsY || 1}`);
39+
debugLog(
40+
`Mesh config set with dimensions: ${meshConfig.meshDimension}, elements: ${meshConfig.numElementsX}x${
41+
meshConfig.numElementsY || 1
42+
}`
43+
);
3944
}
4045

4146
addBoundaryCondition(boundaryKey, condition) {
@@ -83,14 +88,14 @@ export class FEAScriptModel {
8388
const initialGuess = new Array(residualVector.length).fill(0);
8489
// Call Jacobi method with desired max iterations and tolerance
8590
const jacobiResult = jacobiMethod(jacobianMatrix, residualVector, initialGuess, 1000, 1e-6);
86-
91+
8792
// Log convergence information
8893
if (jacobiResult.converged) {
8994
debugLog(`Jacobi method converged in ${jacobiResult.iterations} iterations`);
9095
} else {
9196
debugLog(`Jacobi method did not converge after ${jacobiResult.iterations} iterations`);
9297
}
93-
98+
9499
solutionVector = jacobiResult.solution;
95100
}
96101
console.timeEnd("systemSolving");

‎src/mesh/basisFunctionsScript.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ export class basisFunctions {
2323
}
2424

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

‎src/mesh/meshGenerationScript.js

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@
88
// |_| | |_ //
99
// Website: https://feascript.com/ \__| //
1010

11-
/**
12-
* Class to handle the generation of structured finite element meshes
13-
*/
14-
11+
// Internal imports
1512
import { importGmshQuadTri } from "../readers/gmshReaderScript.js";
1613
import { errorLog } from "../utilities/loggingScript.js";
1714

15+
/**
16+
* Class to handle the generation of structured finite element meshes
17+
*/
1818
export class meshGeneration {
1919
/**
2020
* Constructor to initialize the meshGeneration class
@@ -46,7 +46,7 @@ export class meshGeneration {
4646
}
4747

4848
/**
49-
* Generate the mesh based on the dimension or custom mesh file
49+
* Function to generate the mesh based on the dimension or custom mesh file
5050
* @returns {object} The generated mesh containing node coordinates and total nodes
5151
*/
5252
generateMesh() {
@@ -64,7 +64,12 @@ export class meshGeneration {
6464
throw new Error(errorMessage);
6565
}
6666
} else if (this.meshDimension === "2D") {
67-
if (this.numElementsX === null || this.maxX === null || this.numElementsY === null || this.maxY === null) {
67+
if (
68+
this.numElementsX === null ||
69+
this.maxX === null ||
70+
this.numElementsY === null ||
71+
this.maxY === null
72+
) {
6873
const errorMessage =
6974
"numElementsX, maxX, numElementsY, and maxY are required parameters when generating a 2D mesh from geometry";
7075
errorLog(errorMessage);
@@ -78,7 +83,7 @@ export class meshGeneration {
7883
}
7984

8085
/**
81-
* Parse a custom mesh JSON file and generate the mesh
86+
* Function to parse a custom mesh JSON file and generate the mesh
8287
* @param {string} meshFilePath - Path to the custom mesh file (JSON format)
8388
* @returns {object} Mesh data containing coordinates and connectivity
8489
*/
@@ -106,7 +111,7 @@ export class meshGeneration {
106111
}
107112

108113
/**
109-
* Generate a structured mesh based on the msh file
114+
* Function to generate a structured mesh based on the msh file
110115
* @returns {object} An object containing the coordinates of nodes,
111116
* total number of nodes, nodal numbering (NOP) array, and boundary elements
112117
*/
@@ -118,7 +123,7 @@ export class meshGeneration {
118123
}
119124

120125
/**
121-
* Generate a structured mesh based on the geometry configuration
126+
* Function to generate a structured mesh based on the geometry configuration
122127
* @returns {object} An object containing the coordinates of nodes,
123128
* total number of nodes, nodal numbering (NOP) array, and boundary elements
124129
*/
@@ -233,21 +238,13 @@ export class meshGeneration {
233238
}
234239

235240
/**
236-
* Find the elements that belong to each boundary for a simple rectangular domain
241+
* Function to find the elements that belong to each boundary for a simple rectangular domain
237242
* @returns {array} An array containing arrays of elements and their adjacent boundary side for each boundary
238243
* Each element in the array is of the form [elementIndex, side], where side for a rectangular element is:
239244
* 0 - Bottom side
240245
* 1 - Left side
241246
* 2 - Top side< 2851 /span>
242247
* 3 - Right side
243-
*
244-
* Example representation of boundaryElements array in case of a rectangular element:
245-
* boundaryElements = [
246-
* [[element1, 0], [element2, 0], [element3, 0], ...], // Bottom boundary
247-
* [[element*, 1], [element*, 1], [element*, 1], ...], // Left boundary
248-
* [[element*, 2], [element*, 2], [element*, 2], ...], // Top boundary
249-
* [[element*, 3], [element*, 3], [element*, 3], ...] // Right boundary
250-
* ];
251248
*/
252249
findBoundaryElements() {
253250
const boundaryElements = [];
@@ -294,7 +291,7 @@ export class meshGeneration {
294291
}
295292

296293
/**
297-
* Generate the nodal numbering (NOP) array for a structured mesh
294+
* Function to generate the nodal numbering (NOP) array for a structured mesh
298295
* This array represents the connectivity between elements and their corresponding nodes
299296
* @param {number} numElementsX - Number of elements along the x-axis
300297
* @param {number} [numElementsY] - Number of elements along the y-axis (optional for 1D)

‎src/methods/jacobiMethodScript.js

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
// Website: https://feascript.com/ \__| //
1010

1111
/**
12-
* Solves a system of linear equations using the Jacobi iterative method
12+
* Function to solve a system of linear equations using the Jacobi iterative method
1313
* @param {array} A - The coefficient matrix (must be square)
1414
* @param {array} b - The right-hand side vector
1515
* @param {array} x0 - Initial guess for solution vector
@@ -22,9 +22,9 @@
2222
*/
2323
export function jacobiMethod(A, b, x0, maxIterations = 100, tolerance = 1e-7) {
2424
const n = A.length; // Size of the square matrix
25-
let x = [...x0]; // Current solution (starts with initial guess)
25+
let x = [...x0]; // Current solution (starts with initial guess)
2626
let xNew = new Array(n); // Next iteration's solution
27-
27+
2828
for (let iteration = 0; iteration < maxIterations; iteration++) {
2929
// Perform one iteration
3030
for (let i = 0; i < n; i++) {
@@ -38,30 +38,30 @@ export function jacobiMethod(A, b, x0, maxIterations = 100, tolerance = 1e-7) {
3838
// Update xNew[i] using the Jacobi formula
3939
xNew[i] = (b[i] - sum) / A[i][i];
4040
}
41-
41+
4242
// Check convergence
4343
let maxDiff = 0;
4444
for (let i = 0; i < n; i++) {
4545
maxDiff = Math.max(maxDiff, Math.abs(xNew[i] - x[i]));
4646
}
47-
47+
4848
// Update x for next iteration
4949
x = [...xNew];
50-
50+
5151
// Successfully converged if maxDiff is less than tolerance
5252
if (maxDiff < tolerance) {
5353
return {
5454
solution: x,
5555
iterations: iteration + 1,
56-
converged: true
56+
converged: true,
5757
};
5858
}
5959
}
60-
60+
6161
// maxIterations were reached without convergence
6262
return {
6363
solution: x,
6464
iterations: maxIterations,
65-
converged: false
65+
converged: false,
6666
};
67-
}
67+
}

‎src/methods/numericalIntegrationScript.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,17 @@
1313
*/
1414
export class numericalIntegration {
1515
/**
16-
* Constructor to initialize the numIntegration class
16+
* Constructor to initialize the numericalIntegration class
1717
* @param {string} meshDimension - The dimension of the mesh
18-
* @param {number} elementOrder - The order of elements
18+
* @param {string} elementOrder - The order of elements
1919
*/
2020
constructor({ meshDimension, elementOrder }) {
2121
this.meshDimension = meshDimension;
2222
this.elementOrder = elementOrder;
2323
}
2424

2525
/**
26-
* Return Gauss points and weights based on element configuration
26+
* Function to return Gauss points and weights based on element configuration
2727
* @returns {object} An object containing:
2828
* - gaussPoints: Array of Gauss points
2929
* - gaussWeights: Array of Gauss weights

0 commit comments

Comments
 (0)
0