Implement WebGPU Conjugate Gradient Solver with Enhanced Precision and Robust Fallback

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: FEAScript
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.gitignore

@@ -0,0 +1,9 @@
+# Dependencies
+/node_modules
+node_modules
+node_modules/
+
+# Example dependencies
+examples/**/package.json
+examples/**/package-lock.json
+examples/**/node_modules/

.npmignore

@@ -0,0 +1,4 @@
+examples/
+test/
+.gitignore
+package-lock.json

CONTRIBUTING.md

@@ -40,11 +40,11 @@ To contribute a new feature or fix:
 
 All files in the FEAScript-core codebase should follow this structure:
 
-1. **Banner**: All files start with the FEAScript ASCII art banner
+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
+   - External imports (from npm packages) first, alphabetically ordered.
+   - Internal imports next, grouped by module/folder.
+3. **Classes/Functions**: Implementation with proper JSDoc comments.
 
 Example:
 
@@ -88,3 +88,14 @@ export class MyClass {
   }
 }
 ```
+
+## File Naming Convention
+
+All JavaScript source files in FEAScript end with the suffix `Script` before the `.js` extension (e.g., `loggingScript.js`, `meshGenerationScript.js`, `newtonRaphsonScript.js`). This is an explicit, project‑level stylistic choice to:
+
+- Visually distinguish internal FEAScript modules from third‑party or external library files.
+- Keep historical and stylistic consistency across the codebase.
+
+Exceptions:
+- Public entry file: `index.js` (standard entry point convention).
+- Core model file: `FEAScript.js` (matches the library name; appending "Script" would be redundant).

NOTICE.md

@@ -1,16 +1,14 @@
 FEAScript makes use of the following third-party software:
 
 1. **math.js**
-   - License: Apache 2.0 License
+   - License: Apache 2.0 (https://github.com/josdejong/mathjs/blob/develop/LICENSE)
    - Source: https://github.com/josdejong/mathjs
-   - License: https://github.com/josdejong/mathjs/blob/develop/LICENSE
+
 
 2. **plotly.js**
-   - License: MIT License
+   - License: MIT (https://github.com/plotly/plotly.js/blob/master/LICENSE)
    - Source: https://github.com/plotly/plotly.js/tree/master
-   - License: https://github.com/plotly/plotly.js/blob/master/LICENSE
 
 3. **Comlink**
-   - License: Apache 2.0 License
-   - Source: https://github.com/GoogleChromeLabs/comlink
-   - License: https://github.com/GoogleChromeLabs/comlink/blob/main/LICENSE
+   - License: Apache 2.0 (https://github.com/GoogleChromeLabs/comlink/blob/main/LICENSE)
+   - Source: https://github.com/GoogleChromeLabs/comlink

README.md

@@ -2,50 +2,116 @@
 
 # FEAScript-core
 
-[FEAScript](https://feascript.com/) is a lightweight finite element simulation library built in JavaScript. It empowers users to create and execute browser-based simulations for physics and engineering applications. This is the core library of FEAScript.
+[![npm version](https://img.shields.io/npm/v/feascript)](https://www.npmjs.com/package/feascript) <img src="https://img.shields.io/liberapay/receives/FEAScript.svg?logo=liberapay">
+
+[FEAScript](https://feascript.com/) is a lightweight finite element simulation library built in JavaScript. It empowers users to create and execute simulations for physics and engineering applications in both browser-based and server-side environments. This is the core library of FEAScript.
 
 > 🚧 **FEAScript is currently under heavy development.** Functionality and interfaces may change rapidly as new features and enhancements are introduced. 🚧
 
-## Getting Started
+## Contents
+
+- [Installation](#installation)
+- [Example Usage](#example-usage)
+- [FEAScript Platform](#feascript-platform)
+- [Contribute](#contribute)
+- [License](#license)
+
+## Installation
+
+FEAScript is entirely implemented in pure JavaScript and can run in two environments:
+
+1. **In the browser** with a simple HTML page, where all simulations are executed locally without any installations or using any cloud services.
+2. **Via Node.js** with plain JavaScript files, for server-side simulations.
+
+### Option 1: In the Browser
+
+You can use FEAScript in browser environments in two ways:
+
+**Direct Import from the Web (ES Module):**
+
+```html
+<script type="module">
+  import { FEAScriptModel } from "https://core.feascript.com/dist/feascript.esm.js";
+</script>
+```
+
+**Download and Use Locally:**
+
+```html
+<script type="module">
+  import { FEAScriptModel } from "./path/to/dist/feascript.esm.js";
+</script>
+```
 
-FEAScript is entirely implemented in pure JavaScript and requires only a simple HTML page to operate. All simulations are executed locally in your browser, without the need for any cloud services.
+You can download the latest stable release from [GitHub Releases](https://github.com/FEAScript/FEAScript-core/releases). Explore various browser-based examples and use cases in our [website](https://feascript.com/#tutorials).
 
-### Example Usage
+### Option 2: Via Node.js
+
+Install FEAScript and its peer dependencies from npm:
+
+```bash
+npm install feascript mathjs plotly.js
+```
+
+Then, import it in your JavaScript file:
 
 ```javascript
-// Import FEAScript library
-import { FEAScriptModel, plotSolution } from "https://core.feascript.com/src/index.js";
-
-// Create and configure model
-const model = new FEAScriptModel();
-model.setSolverConfig("solverType"); // e.g., "solidHeatTransfer" for a stationary solid heat transfer case
-model.setMeshConfig({ // Define mesh configuration (assuming a rectangular domain for 2D)
-  meshDimension: "1D" | "2D", // Mesh dimension
-  elementOrder: "linear" | "quadratic", // Element order
-  numElementsX: number, // Number of elements in x-direction
-  numElementsY: number, // Number of elements in y-direction (for 2D)
-  maxX: number, // Domain length in x-direction
-  maxY: number, // Domain length in y-direction (for 2D)
-});
-
-// Apply boundary conditions
-model.addBoundaryCondition("boundaryIndex", ["conditionType", /* parameters */]);
-
-// Solve
-const { solutionVector, nodesCoordinates } = model.solve();
-
-// Plot results
-plotSolution(
-  solutionVector,
-  nodesCoordinates,
-  model.solverConfig,
-  model.meshConfig.meshDimension,
-  "plotType", // e.g., "contour"
-  "targetDivId" // HTML div ID for plot
-);
+import { FEAScriptModel } from "feascript";
+```
+
+**Important:** FEAScript is built as an ES module. If you're starting a completely new project (outside this repository), make sure to configure it to use ES modules by:
+
+```bash
+# Create package.json with type=module for ES modules support
+echo '{"type":"module"}' > package.json
+```
+
+When running examples from within this repository, this step is not needed as the root package.json already has the proper configuration. Explore various Node.js examples and use cases [here](https://github.com/FEAScript/FEAScript-core/tree/main/examples).
+
+## Example Usage
+
+This is an indicative example of FEAScript, shown for execution in the browser. Adapt paths, solver types, and boundary conditions as needed for your specific problem:
+
+```html
+<body>
+  <!-- ...body region... -->
+  <script type="module">
+    // Import FEAScript library
+    import { FEAScriptModel } from "https://core.feascript.com/dist/feascript.esm.js";
+
+    window.addEventListener("DOMContentLoaded", async () => {
+      // Create and configure model
+      const model = new FEAScriptModel();
+      model.setSolverConfig("solverType"); // e.g., "solidHeatTransfer" for a stationary solid heat transfer case
+      model.setMeshConfig({
+        meshDimension: "1D" | "2D", // Mesh dimension
+        elementOrder: "linear" | "quadratic", // Element order
+        numElementsX: number, // Number of elements in x-direction
+        numElementsY: number, // Number of elements in y-direction (for 2D)
+        maxX: number, // Domain length in x-direction
+        maxY: number, // Domain length in y-direction (for 2D)
+      });
+
+      // Apply boundary conditions
+      model.addBoundaryCondition("boundaryIndex", ["conditionType" /* parameters */]);
+
+      // Solve
+      const { solutionVector, nodesCoordinates } = model.solve();
+    });
+  </script>
+  <!-- ...continue of body region... -->
+</body>
 ```
 
-Explore various examples and use cases of FEAScript [here](https://github.com/FEAScript/FEAScript-core/tree/main/examples).
+## FEAScript Platform
+
+For users who prefer a visual approach to creating simulations, we offer the [FEAScript platform](https://platform.feascript.com/) - a browser-based visual editor built on the [Blockly](https://developers.google.com/blockly) library. This no-code interface allows you to:
+
+- Build and run finite element simulations directly in your browser by connecting visual blocks
+- Create complex simulations without writing any JavaScript code
+- Save and load projects in XML format for easy sharing and reuse
+
+While FEAScript's JavaScript API offers full programmatic control for advanced customization, the FEAScript platform provides an accessible entry point for users without coding experience.
 
 ## Contribute
 

examples/WebGPU_ConjugateGradient_README.md

@@ -0,0 +1,44 @@
+# WebGPU Conjugate Gradient Solver Example
+
+This example demonstrates the use of the new WebGPU-accelerated Conjugate Gradient solver in FEAScript for improved precision in linear system solving.
+
+## Key Features
+
+- **WebGPU Acceleration**: Uses WebGPU compute shaders when available for faster vector operations
+- **CPU Fallback**: Automatically falls back to optimized CPU implementation when WebGPU is unavailable
+- **Improved Precision**: Higher precision arithmetic and tighter convergence tolerances (1e-9 vs 1e-6)
+- **Robust Error Handling**: Automatically detects matrix properties and falls back to stable iterative methods
+- **Smart Matrix Detection**: Checks for matrix symmetry and positive definiteness required by CG
+
+## Usage
+
+```javascript
+// Set the solver method to use WebGPU Conjugate Gradient
+model.setSolverMethod("conjugate-gradient-webgpu");
+```
+
+## Fallback Behavior
+
+The solver intelligently handles different matrix types:
+
+1. **Symmetric Positive Definite**: Uses optimized Conjugate Gradient algorithm
+2. **Non-symmetric or Indefinite**: Falls back to robust Gauss-Seidel-based iterative solver
+3. **WebGPU Unavailable**: Uses CPU implementation with same algorithms
+
+## Precision Improvements
+
+- Default tolerance: 1e-9 (vs 1e-6 for other solvers)
+- Explicit numerical casting for precision preservation
+- Better convergence criteria and residual monitoring
+- Numerical stability checks throughout the algorithm
+
+## Performance
+
+- WebGPU acceleration when available (browser environment)
+- Optimized CPU fallback for Node.js and non-WebGPU environments
+- Competitive performance with traditional direct solvers
+- Better convergence for well-conditioned systems
+
+## Compatibility
+
+The WebGPU solver is fully compatible with existing FEAScript workflows and can be used as a drop-in replacement for other solver methods.

examples/frontPropagationScript/SolidificationFront2D/README.md

@@ -0,0 +1,29 @@
+<img src="https://feascript.github.io/FEAScript-website/assets/FEAScriptFrontPropagation.png" width="80" alt="FEAScript Logo">
+
+## Solidification Front Propagation in a Two-Dimensional Domain
+
+This example demonstrates solving an eikonal equation in a two-dimensional domain using the FEAScript library. The problem represents a typical solidification front propagation scenario, where the objective is to track the movement of an interface, such as in metal cooling or crystal growth processes.
+
+### Instructions
+
+This example requires the `feascript` npm package and its peer dependencies (`mathjs`). It imports FEAScript directly from the npm package and runs the simulation in a Node.js environment. To run the example, follow these instructions:
+
+1. **Create package.json with ES module support:**
+
+   ```bash
+   echo '{"type":"module"}' > package.json
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   npm install feascript mathjs
+   ```
+
+3. **Run the example:**
+
+   ```bash
+   node SolidificationFront2D.js
+   ```
+
+**Note:** For detailed information on the model setup, boundary conditions, and simulation results, refer to the comments in the JavaScript files and the corresponding standard [tutorial](https://feascript.com/tutorials/SolidificationFront2D.html).

examples/frontPropagationScript/SolidificationFront2D/SolidificationFront2D.js

@@ -0,0 +1,51 @@
+//   ______ ______           _____           _       _     //
+//  |  ____|  ____|   /\    / ____|         (_)     | |    //
+//  | |__  | |__     /  \  | (___   ___ ____ _ ____ | |_   //
+//  |  __| |  __|   / /\ \  \___ \ / __|  __| |  _ \| __|  //
+//  | |    | |____ / ____ \ ____) | (__| |  | | |_) | |    //
+//  |_|    |______/_/    \_\_____/ \___|_|  |_|  __/| |    //
+//                                            | |   | |    //
+//                                            |_|   | |_   //
+//       Website: https://feascript.com/             \__|  //
+
+// Import Math.js
+import * as math from "mathjs";
+global.math = math;
+
+// Import FEAScript library
+import { FEAScriptModel, logSystem, VERSION } from "feascript";
+
+console.log("FEAScript Version:", VERSION);
+
+// Create a new FEAScript model
+const model = new FEAScriptModel();
+
+// Set solver configuration for front propagation
+model.setSolverConfig("frontPropagationScript");
+
+// Define mesh configuration
+model.setMeshConfig({
+  meshDimension: "2D",
+  elementOrder: "quadratic",
+  numElementsX: 12,
+  numElementsY: 8,
+  maxX: 4,
+  maxY: 2,
+});
+
+// Define boundary conditions
+model.addBoundaryCondition("0", ["constantValue", 0]); // Bottom
+model.addBoundaryCondition("1", ["constantValue", 0]); // Left
+model.addBoundaryCondition("2", ["zeroGradient"]); // Top
+model.addBoundaryCondition("3", ["constantValue", 0]); // Right
+
+// Set solver method (optional)
+model.setSolverMethod("lusolve");
+
+// Solve the problem and get the solution
+const { solutionVector, nodesCoordinates } = model.solve();
+
+// Print results to console
+console.log("Solution vector:", solutionVector);
+console.log("Node coordinates:", nodesCoordinates);
+console.log(`Number of nodes in mesh: ${nodesCoordinates.nodesXCoordinates.length}`);