Skip to content

Commit 22b4620

Browse files
nikoschamnikoscham
committed
Write the documentation for FEAScript 0.3.0
Add Fundamentals (finite element method, mesh, boundary conditions, solvers), all five model pages, the API reference (FEAScriptModel, importGmshMesh, visualization, FEAScriptWorker, utilities) and a complete first simulation. Add SVG figures in static/assets, inverted in dark mode.
1 parent 344c949 commit 22b4620

24 files changed

Lines changed: 2222 additions & 39 deletions

‎docs/api/feascript-model.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# FEAScriptModel
6+
7+
`FEAScriptModel` is the main class of FEAScript. It holds the configuration of a simulation (model, mesh,
8+
boundary conditions and solver) and solves it.
9+
10+
```javascript
11+
import { FEAScriptModel } from "feascript";
12+
13+
const model = new FEAScriptModel();
14+
model.setModelConfig("heatConductionScript");
15+
model.setMeshConfig({ meshDimension: "1D", elementOrder: "linear", numElementsX: 10, maxX: 0.15 });
16+
model.addBoundaryCondition("0", ["convection", 1, 25]);
17+
model.addBoundaryCondition("1", ["constantTemperature", 5]);
18+
model.setSolverMethod("lusolve");
19+
const { solutionVector, nodesCoordinates } = model.solve();
20+
```
21+
22+
## Constructor
23+
24+
### `new FEAScriptModel()`
25+
26+
Creates an empty model. The solver method defaults to `"lusolve"`.
27+
28+
## Methods
29+
30+
### `setModelConfig(modelConfig, options)`
31+
32+
Selects the physical model and sets its options.
33+
34+
| Parameter | Type | Description |
35+
| ------------- | -------- | ---------------------------------- |
36+
| `modelConfig` | `string` | Name of the model (see below) |
37+
| `options` | `object` | Optional model options (see below) |
38+
39+
| `modelConfig` | Model | Dimensions |
40+
| ---------------------------- | --------------------------------------------------------- | ---------- |
41+
| `"heatConductionScript"` | [Heat conduction](../models/heat-conduction.md) | 1D, 2D |
42+
| `"generalFormPDEScript"` | [General form PDE](../models/general-form-pde.md) | 1D |
43+
| `"frontPropagationScript"` | [Front propagation](../models/front-propagation.md) | 1D, 2D |
44+
| `"creepingFlowScript"` | [Creeping flow](../models/creeping-flow.md) | 2D |
45+
| `"eulerBernoulliBeamScript"` | [Euler–Bernoulli beam](../models/euler-bernoulli-beam.md) | 1D |
46+
47+
| Option | Type | Used by | Description |
48+
| ---------------------- | --------- | ------------------------------------------------------- | ------------------------------------------------------ |
49+
| `coefficientFunctions` | `object` | Heat conduction, general form PDE, Euler–Bernoulli beam | Coefficients of the equation; see each model page |
50+
| `nonlinear` | `boolean` | General form PDE | Solve with the Newton–Raphson method (default `false`) |
51+
| `maxIterations` | `number` | All | Maximum iterations of the iterative method in use |
52+
| `tolerance` | `number` | All | Convergence tolerance of the iterative method in use |
53+
54+
`maxIterations` and `tolerance` apply to the Jacobi solvers in linear models and to the Newton–Raphson method in
55+
nonlinear models; see [Solvers](../fundamentals/solvers.md) for their defaults.
56+
57+
```javascript
58+
model.setModelConfig("heatConductionScript", {
59+
coefficientFunctions: {
60+
thermalConductivity: (x, y) => (x < 2 ? 10 : 1),
61+
heatSource: 0,
62+
},
63+
});
64+
```
65+
66+
### `setMeshConfig(meshConfig)`
67+
68+
Sets the mesh: either the parameters of a structured mesh or a mesh imported from Gmsh.
69+
70+
| Property | Type | Description |
71+
| --------------- | -------- | ------------------------------------------------------------------------------- |
72+
| `meshDimension` | `string` | `"1D"` or `"2D"` (detected automatically for `parsedMesh`) |
73+
| `elementOrder` | `string` | `"linear"` (default) or `"quadratic"` (detected automatically for `parsedMesh`) |
74+
| `numElementsX` | `number` | Number of elements along $x$ (structured mesh) |
75+
| `numElementsY` | `number` | Number of elements along $y$ (structured 2D mesh) |
76+
| `maxX` | `number` | Length of the domain along $x$ (structured mesh) |
77+
| `maxY` | `number` | Height of the domain along $y$ (structured 2D mesh) |
78+
| `angleLeft` | `number` | Interior angle of the left side in degrees, default `90` (structured 2D mesh) |
79+
| `angleRight` | `number` | Interior angle of the right side in degrees, default `90` (structured 2D mesh) |
80+
| `parsedMesh` | `object` | Mesh returned by [`importGmshMesh`](./gmsh-import.md) |
81+
82+
See [Mesh](../fundamentals/mesh.md) for the geometry, the boundary keys and the node numbering.
83+
84+
### `addBoundaryCondition(boundaryKey, condition)`
85+
86+
Adds a boundary condition, or replaces the condition of a boundary that already has one.
87+
88+
| Parameter | Type | Description |
89+
| ------------- | -------- | ----------------------------------------------------------------------------- |
90+
| `boundaryKey` | `string` | Boundary key (`"0"`, `"1"`, ...), or node number for the Euler–Bernoulli beam |
91+
| `condition` | `array` | Condition type followed by its parameters, e.g. `["convection", 1, 20]` |
92+
93+
See [Boundary conditions](../fundamentals/boundary-conditions.md) for the condition types of each model.
94+
Condition types that the selected model does not recognize are reported as errors when `solve()` runs (see
95+
[Checks](../fundamentals/boundary-conditions.md#checks)).
96+
97+
### `setSolverMethod(solverMethod)`
98+
99+
Selects the linear system solver: `"lusolve"` (default), `"jacobi"`, `"frontal"` or `"jacobi-gpu"`. See
100+
[Solvers](../fundamentals/solvers.md) for the methods supported by each model.
101+
102+
### `solve(options)`
103+
104+
Prepares the mesh, assembles the system, applies the boundary conditions and solves it. This method is
105+
synchronous.
106+
107+
| Parameter | Type | Description |
108+
| --------- | -------- | ------------------------------------------------------------------------------------------- |
109+
| `options` | `object` | Optional `{ maxIterations, tolerance }`; they take precedence over `setModelConfig` options |
110+
111+
Returns an object with:
112+
113+
| Property | Type | Description |
114+
| ------------------------------------ | -------------- | --------------------------------------------- |
115+
| `solutionVector` | `Float64Array` | The computed unknowns (see the model pages) |
116+
| `nodesCoordinates.nodesXCoordinates` | `number[]` | $x$ coordinates of the mesh nodes |
117+
| `nodesCoordinates.nodesYCoordinates` | `number[]` | $y$ coordinates of the mesh nodes (2D meshes) |
118+
119+
For scalar models (heat conduction, general form PDE, front propagation), `solutionVector` has one value per
120+
node, in the order of `nodesCoordinates`. The [creeping flow](../models/creeping-flow.md#results) and
121+
[Euler–Bernoulli beam](../models/euler-bernoulli-beam.md#results) models return more unknowns per node; see
122+
their pages for the layout.
123+
124+
### `solveAsync(computeEngine, options)`
125+
126+
Asynchronous version of `solve`, used with the `"jacobi-gpu"` solver method. It returns a `Promise` that resolves
127+
to the same object as `solve()`.
128+
129+
```javascript
130+
model.setSolverMethod("jacobi-gpu");
131+
const { solutionVector, nodesCoordinates } = await model.solveAsync();
132+
```
133+
134+
| Parameter | Type | Description |
135+
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
136+
| `computeEngine` | `object` | Optional. An initialized WebGPU compute engine to reuse across solves. When omitted or `null`, FEAScript creates one for the solve and terminates it afterwards; a provided engine is left running |
137+
| `options` | `object` | Optional `{ maxIterations, tolerance }` |
138+
139+
:::caution
140+
`solveAsync` currently supports only `heatConductionScript` with the `"jacobi-gpu"` solver method, in browsers
141+
with WebGPU support. For other models or solver methods, it returns an empty solution vector.
142+
:::
143+
144+
## Error handling
145+
146+
FEAScript reports configuration problems (for example an unsupported mesh for a model, or a solver that did not
147+
converge) as `[ERROR]` messages in the console, and in most cases continues instead of throwing an exception.
148+
Check the console output when a result looks wrong. See [Logging](./utilities.md#logsystem) to control the
149+
amount of output.

‎docs/api/gmsh-import.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# importGmshMesh
6+
7+
```javascript
8+
const parsedMesh = await importGmshMesh(file);
9+
```
10+
11+
Reads a 2D mesh generated by [Gmsh](https://gmsh.info/) (`.msh` format version 4.1, ASCII) and returns it in the
12+
form that `setMeshConfig` expects through its `parsedMesh` property. See
13+
[Mesh](../fundamentals/mesh.md#gmsh-meshes) for the supported element types and for how boundaries are defined.
14+
15+
| Parameter | Type | Description |
16+
| --------- | -------- | --------------------------------------------------------------------------------------------------------------- |
17+
| `file` | `object` | A `File` object, or any object with an asynchronous `text()` method that returns the content of the `.msh` file |
18+
19+
Returns a `Promise` that resolves to the parsed mesh. Its `meshDimension` (`"2D"`) and `elementOrder`
20+
(`"linear"` or `"quadratic"`) are detected from the file and used by `setMeshConfig`.
21+
22+
## In the browser
23+
24+
From a file input:
25+
26+
```html
27+
<input type="file" id="meshFile" accept=".msh" />
28+
29+
<script type="module">
30+
import { FEAScriptModel, importGmshMesh } from "https://core.feascript.com/dist/feascript.esm.js";
31+
32+
document.getElementById("meshFile").addEventListener("change", async (event) => {
33+
const parsedMesh = await importGmshMesh(event.target.files[0]);
34+
35+
const model = new FEAScriptModel();
36+
model.setModelConfig("heatConductionScript");
37+
model.setMeshConfig({ parsedMesh });
38+
// ...boundary conditions and solve
39+
});
40+
</script>
41+
```
42+
43+
From a file on the server:
44+
45+
```javascript
46+
const response = await fetch("./rhom_quad.msh");
47+
const meshFile = new File([await response.text()], "rhom_quad.msh");
48+
const parsedMesh = await importGmshMesh(meshFile);
49+
```
50+
51+
## In Node.js
52+
53+
Node.js has no `File` object for files on disk, so pass an object with a `text()` method:
54+
55+
```javascript
56+
import fs from "fs";
57+
import { FEAScriptModel, importGmshMesh } from "feascript";
58+
59+
const meshContent = fs.readFileSync("rect_quad.msh", "utf8");
60+
const parsedMesh = await importGmshMesh({ text: async () => meshContent });
61+
62+
const model = new FEAScriptModel();
63+
model.setModelConfig("heatConductionScript");
64+
model.setMeshConfig({ parsedMesh });
65+
66+
model.addBoundaryCondition("0", ["constantTemperature", 200]); // Physical curve with tag 1
67+
model.addBoundaryCondition("1", ["constantTemperature", 200]); // Physical curve with tag 2
68+
model.addBoundaryCondition("2", ["convection", 1, 20]); // Physical curve with tag 3
69+
model.addBoundaryCondition("3", ["symmetry"]); // Physical curve with tag 4
70+
71+
const { solutionVector, nodesCoordinates } = model.solve();
72+
```
73+
74+
## Limitations
75+
76+
- Only 2D meshes are supported; a 1D or 3D mesh is reported as an error.
77+
- All elements must be of the same shape (quadrilaterals or triangles) and order (linear or quadratic).
78+
- Only the ASCII variant of the version 4.1 format is read. Export with
79+
`gmsh model.geo -2 -format msh41 -o model.msh`, or with **File → Export** and the "Version 4 ASCII" format in
80+
the Gmsh interface.

‎docs/api/utilities.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
sidebar_position: 5
3+
---
4+
5+
# Utilities
6+
7+
## `logSystem`
8+
9+
```javascript
10+
import { logSystem } from "feascript";
11+
12+
logSystem("debug");
13+
```
14+
15+
Sets how much FEAScript prints to the console.
16+
17+
| Level | Output |
18+
| --------- | --------------------------------------------------------------------------------------------------------------------- |
19+
| `"none"` | Errors and warnings only |
20+
| `"basic"` | Default. Adds progress messages (`[INFO]`), including the error norm of every Newton–Raphson iteration |
21+
| `"debug"` | Adds detailed messages (`[DEBUG]`), such as the nodes of every boundary condition and the number of Jacobi iterations |
22+
23+
Errors (`[ERROR]`) and warnings (`[WARN]`) are always printed. Any other value falls back to `"basic"` with a
24+
warning. The timings of the solution steps (`totalSolvingTime`, `systemSolving`) are printed with `console.time`
25+
at every level.
26+
27+
## `printVersion`
28+
29+
```javascript
30+
import { printVersion } from "feascript";
31+
32+
console.log("FEAScript version:", printVersion); // "0.3.0 (RC)"
33+
```
34+
35+
A string constant with the version of the library.

0 commit comments

Comments
 (0)