@woosh/meep-engine 2.43.0 → 2.43.3

package/core/geom/3d/tetrahedra/{tetrahedra_collection.js → TetrahedralMesh.js}

@@ -1,17 +1,15 @@
 import { tetrahedron_contains_point } from "./tetrahedron_contains_point.js";
-import { assert } from "../../../assert.js";
 import { BitSet } from "../../../binary/BitSet.js";
 import { typed_array_copy } from "../../../collection/array/typed/typed_array_copy.js";
 import { max3 } from "../../../math/max3.js";
-import { Cavity } from "./delaunay/Cavity.js";
-import { tetrahedral_mesh_compute_cavity } from "./delaunay/tetrahedral_mesh_compute_cavity.js";
+import { assert } from "../../../assert.js";
 
 /**
  * Size in bytes of a single tetrahedron record
  * @readonly
  * @type {number}
  */
-export const LAYOUT_TETRA_BYTE_SIZE = 9 * 4;
+export const LAYOUT_TETRA_BYTE_SIZE = 8 * 4;
 
 /**
  * @readonly
@@ -19,11 +17,35 @@ export const LAYOUT_TETRA_BYTE_SIZE = 9 * 4;
  */
 export const INVALID_NEIGHBOUR = 0xFFFFFFFF;
 
-const SCRATCH_CAVITY = new Cavity();
+/**
+ * @readonly
+ * @type {number}
+ */
+export const MAX_TET_INDEX = 0xFFFFFFFC;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const DEFAULT_INITIAL_SIZE = 128;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const CAPACITY_GROW_MULTIPLIER = 1.2;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const CAPACITY_GROW_MIN_STEP = 32;
 
 /**
- * Only keeps track of tetrahedra, actual point coordinates are stored outside. For most useful operations point coordinates are passed in
- * Layout:
+ * Only keeps track of tetrahedra, actual point coordinates are stored outside.
+ * For most useful operations point coordinates are passed in as an extra argument.
+ *
+ * Binary Layout:
  *      vertex_id_a :: uint32
  *      vertex_id_b :: uint32
  *      vertex_id_c :: uint32
@@ -32,19 +54,51 @@ const SCRATCH_CAVITY = new Cavity();
  *      neighbour_b :: uint32         - neighbour tetrahedron, opposite to vertex B
  *      neighbour_c :: uint32         - neighbour tetrahedron, opposite to vertex C
  *      neighbour_d :: uint32         - neighbour tetrahedron, opposite to vertex D
- *      sub_determinant :: float    - ?
- * Layout is similar to [1], but is interleaved for better cache locality
+ * Layout is similar to [1], but is interleaved for better cache locality.
+ * Also note that sub-determinants are not included, these are only needed for building the mesh, we excluded them to keep structure clean and more compact.
+ *
+ * Neighbours are encoded in the following manner:
+ *      MSB -> [tet_id:30bit][opposite_corner_index:2bit] <- LSB
+ *      Code to get tet index: encoded >> 2
+ *      Code to get corner index: encoded & 3
  *
  * @see [1] 2018 "One machine, one minute, three billion tetrahedra" by Célestin Marot,  Jeanne Pellerin and Jean-François Remacle
  * @see https://git.immc.ucl.ac.be/hextreme/hxt_seqdel (C source code for [1])
  */
 export class TetrahedralMesh {
-    constructor(initial_size) {
+    /**
+     *
+     * @param {number} [initial_size]
+     */
+    constructor(initial_size = DEFAULT_INITIAL_SIZE) {
+        assert.isNonNegativeInteger(initial_size, 'initial_size');
+
+        /**
+         *
+         * @type {ArrayBuffer}
+         * @private
+         */
         this.__buffer = new ArrayBuffer(initial_size * LAYOUT_TETRA_BYTE_SIZE);
 
+        /**
+         *
+         * @type {DataView}
+         * @private
+         */
         this.__view = new DataView(this.__buffer);
 
+        /**
+         *
+         * @type {number}
+         * @private
+         */
         this.__capacity = initial_size;
+
+        /**
+         *
+         * @type {number}
+         * @private
+         */
         this.__length = 0;
 
 
@@ -56,22 +110,36 @@ export class TetrahedralMesh {
         this.__occupancy = new BitSet();
     }
 
+    /**
+     * Traverse tetrahedrons
+     * @param {(tet:number,mesh:TetrahedralMesh)=>*} visitor
+     * @param {*} [thisArg]
+     */
+    forEach(visitor, thisArg) {
+        const occupancy = this.__occupancy;
+        for (let i = occupancy.nextSetBit(0); i !== -1; i = occupancy.nextSetBit(i + 1)) {
+            visitor.call(thisArg, i, this);
+        }
+    }
+
     /**
      *
-     * @param {number} n
+     * @param {number} capacity
      */
-    setCapacity(n) {
-        if (n === this.__capacity) {
+    setCapacity(capacity) {
+        assert.isNonNegativeInteger(capacity, 'capacity');
+
+        if (capacity === this.__capacity) {
             // do nothing
             return;
         }
 
-        if (n < this.__length) {
-            throw new Error('Dropping information, not supported');
+        if (capacity < this.__capacity && capacity < this.__occupancy.size()) {
+            throw new Error('Reducing capacity would result in dropping information. This is an illegal operation. If you need to reduce capacity - either drop data or compact the layout first.');
         }
 
         // allocate new buffer
-        const new_buffer = new ArrayBuffer(n * LAYOUT_TETRA_BYTE_SIZE);
+        const new_buffer = new ArrayBuffer(capacity * LAYOUT_TETRA_BYTE_SIZE);
 
         // move data across from old buffer to the new one
         const destination_uint8 = new Uint8Array(new_buffer);
@@ -82,18 +150,39 @@ export class TetrahedralMesh {
         // set new buffer
         this.__buffer = new_buffer;
         this.__view = new DataView(new_buffer);
+
+        // write new capacity
+        this.__capacity = capacity;
+    }
+
+    /**
+     *
+     * @return {number}
+     */
+    getCapacity() {
+        return this.__capacity;
+    }
+
+    /**
+     * How many tetrahedrons are contained in the mesh
+     * @return {number}
+     */
+    size() {
+        return this.__length;
     }
 
     /**
      *
-     * @param {number} n
+     * @param {number} capacity
      */
-    ensureCapacity(n) {
+    ensureCapacity(capacity) {
+
+        const existing_capacity = this.__capacity;
 
         const new_capacity = max3(
-            n,
-            this.__capacity * 1.2,
-            this.__capacity + 32
+            capacity,
+            existing_capacity * CAPACITY_GROW_MULTIPLIER,
+            existing_capacity + CAPACITY_GROW_MIN_STEP
         );
 
         this.setCapacity(new_capacity);
@@ -101,31 +190,115 @@ export class TetrahedralMesh {
 
     /**
      *
+     * @param {number} tet
+     * @return {boolean}
+     */
+    exists(tet) {
+        return this.__occupancy.get(tet);
+    }
+
+    /**
+     * NOTE: the neighbour value must be encoded, see format specification for details
      * @param {number} tetra_index
      * @param {number} neighbour_index
      * @returns {number}
      */
     getNeighbour(tetra_index, neighbour_index) {
+        assert.isNonNegativeInteger(tetra_index, 'tetra_index');
+        assert.ok(this.__occupancy.get(tetra_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(neighbour_index, 'neighbour_index');
+
+        assert.lessThan(neighbour_index, 4, 'neighbour_index');
+
         const tetra_address = LAYOUT_TETRA_BYTE_SIZE * tetra_index;
         return this.__view.getUint32(tetra_address + (4 + neighbour_index) * 4);
     }
 
     /**
-     *
+     * NOTE: the neighbour value must be encoded, see format specification for details
      * @param {number} tetra_index
      * @param {number} neighbour_index which neighbour to set (0..11)
      * @param {number} neighbour index of the neighbour
      */
     setNeighbour(tetra_index, neighbour_index, neighbour) {
+
+        assert.isNonNegativeInteger(tetra_index, 'tetra_index');
+        assert.ok(this.__occupancy.get(tetra_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(neighbour_index, 'neighbour_index');
+        assert.isNonNegativeInteger(neighbour, 'neighbour');
+
+        assert.lessThan(neighbour_index, 4, 'neighbour_index');
+
         const tetra_address = LAYOUT_TETRA_BYTE_SIZE * tetra_index;
         return this.__view.setUint32(tetra_address + (4 + neighbour_index) * 4, neighbour);
     }
 
+
+    /**
+     *
+     * @param {number} tet_index
+     * @param {number} point_index should be an integer between 0 and 3
+     * @returns {number}
+     */
+    getVertexIndex(tet_index, point_index) {
+        assert.isNonNegativeInteger(tet_index, 'tet_index');
+        assert.lessThanOrEqual(tet_index, MAX_TET_INDEX, 'max index exceeded');
+        assert.ok(this.__occupancy.get(tet_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(point_index, 'point_index');
+        assert.lessThan(point_index, 4, 'point_index must be less than 4');
+
+
+        return this.__view.getUint32(tet_index * LAYOUT_TETRA_BYTE_SIZE + point_index * 4);
+    }
+
+    /**
+     *
+     * @param {number} tet_index
+     * @param {number} point_index
+     * @param {number} vertex
+     */
+    setVertexIndex(tet_index, point_index, vertex) {
+        assert.isNonNegativeInteger(tet_index, 'tet_index');
+        assert.lessThanOrEqual(tet_index, MAX_TET_INDEX, 'max index exceeded');
+        assert.ok(this.__occupancy.get(tet_index), 'tetrahedron does not exist');
+
+        assert.isNonNegativeInteger(point_index, 'point_index');
+        assert.lessThan(point_index, 4, 'point_index must be less than 4');
+
+        assert.isNonNegativeInteger(vertex, 'vertex');
+
+
+        return this.__view.setUint32(
+            tet_index * LAYOUT_TETRA_BYTE_SIZE + point_index * 4,
+            vertex
+        );
+    }
+
+    /**
+     * Whether a given tetrahedron contains vertex with a given index
+     * @param {number} tet
+     * @param {number} vertex
+     * @return {boolean}
+     */
+    tetContainsVertex(tet, vertex) {
+        for (let i = 0; i < 4; i++) {
+            if (this.getVertexIndex(tet, i) === vertex) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     validateLength() {
         return this.countOccupancy() === this.__length;
     }
 
     /**
+     * DEBUG method
      * Counts number of occupied(used) elements in the pool
      * Should be the same as __length
      * @return {number}
@@ -139,6 +312,37 @@ export class TetrahedralMesh {
         return r;
     }
 
+    /**
+     * Allocate empty tet
+     * NOTE: the tet memory might be dirty, please make sure you set/clear it as necessary
+     * @return {number} index of allocated tetrahedron
+     */
+    allocate() {
+        const tetra_index = this.__occupancy.nextClearBit(0);
+
+        const required_capacity = tetra_index + 1;
+
+        if (required_capacity > this.__capacity) {
+            // needs to be increased in size
+            this.ensureCapacity(required_capacity);
+        }
+
+        this.__occupancy.set(tetra_index, true);
+
+        // initialize neighbours
+        for (let i = 0; i < 4; i++) {
+            this.setNeighbour(tetra_index, i, INVALID_NEIGHBOUR);
+        }
+
+        //assert(this.validateLength());
+
+        this.__length++;
+
+        // assert(this.validateLength());
+
+        return tetra_index;
+    }
+
     /**
      *
      * @param {number[]|Float32Array} points
@@ -146,16 +350,12 @@ export class TetrahedralMesh {
      * @param {number} b
      * @param {number} c
      * @param {number} d
-     * @returns {number} index of the new tetra
+     * @returns {number} index of the new tetrahedron
      */
     append(points, a, b, c, d) {
-        const tetra_index = this.__occupancy.nextClearBit(0);
-        const address = tetra_index * LAYOUT_TETRA_BYTE_SIZE;
+        const tetra_index = this.allocate();
 
-        if (tetra_index >= this.__capacity) {
-            // needs to be increased in size
-            this.ensureCapacity(tetra_index);
-        }
+        const address = tetra_index * LAYOUT_TETRA_BYTE_SIZE;
 
         const view = this.__view;
 
@@ -170,26 +370,20 @@ export class TetrahedralMesh {
         view.setUint32(address + 24, INVALID_NEIGHBOUR);
         view.setUint32(address + 28, INVALID_NEIGHBOUR);
 
-        //assert(this.validateLength());
-
-        this.__occupancy.set(tetra_index, true);
-
-        this.__length++;
-
-        // assert(this.validateLength());
-
         return tetra_index;
     }
 
     /**
      * Remove tetrahedron
-     * @param {number} tera_index
+     * @param {number} tetra_index
      */
-    remove(tera_index) {
+    remove(tetra_index) {
+        assert.isNonNegativeInteger(tetra_index, 'tera_index');
+        assert.equal(this.__occupancy.get(tetra_index), true, 'tetrahedron does not exist');
 
         // find neighbours and remove reference to self
         for (let i = 0; i < 4; i++) {
-            const neighbour_encoded = this.getNeighbour(tera_index, i);
+            const neighbour_encoded = this.getNeighbour(tetra_index, i);
 
             if (neighbour_encoded === INVALID_NEIGHBOUR) {
                 // no neighbour
@@ -198,7 +392,7 @@ export class TetrahedralMesh {
 
             // get tetrahedra index and point index
             const neighbour_index = neighbour_encoded >> 2;
-            const neighbour_point = neighbour_encoded & 4;
+            const neighbour_point = neighbour_encoded & 3;
 
             // clear reference to self
             this.setNeighbour(neighbour_index, neighbour_point, INVALID_NEIGHBOUR);
@@ -207,7 +401,7 @@ export class TetrahedralMesh {
         //assert(this.validateLength());
 
         // mark as dead
-        this.__occupancy.clear(tera_index);
+        this.__occupancy.clear(tetra_index);
         this.__length--;
 
         //assert(this.validateLength());
@@ -270,114 +464,4 @@ export class TetrahedralMesh {
         return -1;
     }
 
-    /**
-     *
-     * @param {number} tet_index
-     * @param {number} point_index should be an integer between 0 and 3
-     * @returns {number}
-     */
-    getCornerIndex(tet_index, point_index) {
-        return this.__view.getUint32(tet_index * LAYOUT_TETRA_BYTE_SIZE + point_index * 4);
-    }
-
-
-    /**
-     *
-     * @param {number[]|Float32Array} points
-     * @param {number} index
-     */
-    insertPoint(points, index) {
-        const debug_length_initial = this.__length;
-
-        // Compute the cavity, that is the set of tetrahedra that need to be removed and rebuilt
-        tetrahedral_mesh_compute_cavity(this, SCRATCH_CAVITY, points, index);
-
-
-        // identify cavity "edge" - the set of tetras that are neighbours of the tetras that form the cavity
-        const cavity_size = SCRATCH_CAVITY.size;
-        const cavity_indices = SCRATCH_CAVITY.indices;
-
-        for (let i = 0; i < cavity_size; i++) {
-            const data = this.__view;
-
-            const cavity_index = cavity_indices[i];
-
-            // take each side of the tetra
-            const tetra_address = cavity_index * LAYOUT_TETRA_BYTE_SIZE;
-
-            const a = data.getUint32(tetra_address);
-            const b = data.getUint32(tetra_address + 4);
-            const c = data.getUint32(tetra_address + 8);
-            const d = data.getUint32(tetra_address + 12);
-
-            // attempt to form 4 tetras using the sides of the cavity
-            const a_neighbour = data.getUint32(tetra_address + 16);
-            const a_neighbour_index = a_neighbour >> 2;
-
-            const b_neighbour = data.getUint32(tetra_address + 20);
-            const b_neighbour_index = b_neighbour >> 2;
-
-            const c_neighbour = data.getUint32(tetra_address + 24);
-            const c_neighbour_index = c_neighbour >> 2;
-
-            const d_neighbour = data.getUint32(tetra_address + 28);
-            const d_neighbour_index = d_neighbour >> 2;
-
-
-            if (a_neighbour === INVALID_NEIGHBOUR || cavity_indices.indexOf(a_neighbour_index) === 0) {
-                // ABC is a valid side
-                const tet = this.append(points, b, d, c, index);
-                // patch in neighbours
-                if (a_neighbour !== INVALID_NEIGHBOUR) {
-                    this.setNeighbour(tet, 3, a_neighbour);
-                    this.setNeighbour(a_neighbour_index, a_neighbour & 3, tet);
-                }
-            }
-            if (b_neighbour === INVALID_NEIGHBOUR || cavity_indices.indexOf(b_neighbour_index) === 0) {
-                // ABC is a valid side
-                const tet = this.append(points, c, d, a, index);
-                if (b_neighbour !== INVALID_NEIGHBOUR) {
-                    this.setNeighbour(tet, 3, b_neighbour);
-                    this.setNeighbour(b_neighbour_index, b_neighbour & 3, tet);
-                }
-            }
-            if (c_neighbour === INVALID_NEIGHBOUR || cavity_indices.indexOf(c_neighbour_index) === 0) {
-                // ABC is a valid side
-                const tet = this.append(points, d, b, a, index);
-                if (c_neighbour !== INVALID_NEIGHBOUR) {
-                    this.setNeighbour(tet, 3, c_neighbour);
-                    this.setNeighbour(c_neighbour_index, c_neighbour & 3, tet);
-                }
-            }
-            if (d_neighbour === INVALID_NEIGHBOUR || cavity_indices.indexOf(d_neighbour_index) === 0) {
-                // ABC is a valid side
-                const tet = this.append(points, a, b, c, index);
-                if (d_neighbour !== INVALID_NEIGHBOUR) {
-                    this.setNeighbour(tet, 3, d_neighbour);
-                    this.setNeighbour(d_neighbour_index, d_neighbour & 3, tet);
-                }
-            }
-        }
-
-
-        // 3. remove the cavity tetrahedrons
-        for (let i = 0; i < cavity_size; i++) {
-            const cavity_index = cavity_indices[i];
-
-            // clear out cavity, connectivity was already patched in the previous step
-            this.__occupancy.set(cavity_index, false);
-            this.__length--;
-        }
-
-        assert.greaterThan(this.__length, debug_length_initial, 'after insertion number of tetrahedra must grow, not shrink')
-    }
-
-    /**
-     * optimize tetrahedrons to reduce number of thin and long tetras
-     * @see https://gitlab.onelab.info/gmsh/gmsh/-/blob/master/contrib/hxt/tetMesh/src/HXTSPR.c
-     */
-    optimize() {
-
-        throw new Error('Not Implemented');
-    }
 }

package/core/geom/3d/tetrahedra/TetrahedralMesh.spec.js

@@ -0,0 +1,156 @@
+import { TetrahedralMesh } from "./TetrahedralMesh.js";
+import { jest } from "@jest/globals";
+
+test("constructor does not throw", () => {
+    expect(() => new TetrahedralMesh(1)).not.toThrow();
+});
+
+test("capacity set in constructor is respected", () => {
+    const mesh = new TetrahedralMesh(7);
+
+    expect(mesh.getCapacity()).toBe(7);
+});
+
+test("attempting to set capacity below what's used will throw", () => {
+    const mesh = new TetrahedralMesh(1);
+
+    mesh.allocate();
+    mesh.allocate();
+
+    expect(() => mesh.setCapacity(1)).toThrow();
+});
+
+test("set/get capacity consistence", () => {
+    const mesh = new TetrahedralMesh(2);
+
+    mesh.setCapacity(1);
+
+    expect(mesh.getCapacity()).toBe(1);
+
+    mesh.setCapacity(1); // idempotency check
+
+    expect(mesh.getCapacity()).toBe(1);
+
+    mesh.setCapacity(2);
+
+    expect(mesh.getCapacity()).toBe(2);
+});
+
+
+test("set/get neighbour consistency", () => {
+    const mesh = new TetrahedralMesh(7);
+
+    const tet = mesh.allocate();
+
+    mesh.setNeighbour(tet, 0, 7);
+    mesh.setNeighbour(tet, 1, 3);
+    mesh.setNeighbour(tet, 2, 11);
+    mesh.setNeighbour(tet, 3, 13);
+
+    //
+    expect(mesh.getNeighbour(tet, 0)).toBe(7);
+    expect(mesh.getNeighbour(tet, 1)).toBe(3);
+    expect(mesh.getNeighbour(tet, 2)).toBe(11);
+    expect(mesh.getNeighbour(tet, 3)).toBe(13);
+});
+
+test("set/get vertex index consistency", () => {
+    const mesh = new TetrahedralMesh(7);
+    const tet = mesh.allocate();
+
+    mesh.setVertexIndex(tet, 0, 3);
+    mesh.setVertexIndex(tet, 1, 7);
+    mesh.setVertexIndex(tet, 2, 11);
+    mesh.setVertexIndex(tet, 3, 13);
+
+    //
+    expect(mesh.getVertexIndex(tet, 0)).toBe(3);
+    expect(mesh.getVertexIndex(tet, 1)).toBe(7);
+    expect(mesh.getVertexIndex(tet, 2)).toBe(11);
+    expect(mesh.getVertexIndex(tet, 3)).toBe(13);
+});
+
+test("allocation within capacity doesn't resize capacity", () => {
+    const mesh = new TetrahedralMesh(1);
+
+    expect(mesh.getCapacity()).toBe(1);
+
+    mesh.allocate();
+
+    expect(mesh.getCapacity()).toBe(1); // allocation fits in the capacity, so no growth is expected
+});
+
+test("allocation beyond capacity does not destroy existing data", () => {
+    const mesh = new TetrahedralMesh(1);
+
+    const t0 = mesh.allocate();
+
+    expect(mesh.getCapacity()).toBe(1);
+
+    for (let i = 0; i < 4; i++) {
+        mesh.setNeighbour(t0, i, 1);
+        mesh.setVertexIndex(t0, i, 3);
+    }
+
+    mesh.allocate(); // allocation over capacity
+
+    expect(mesh.getCapacity()).toBeGreaterThan(1);
+
+    for (let i = 0; i < 4; i++) {
+        expect(mesh.getNeighbour(t0, i)).toBe(1);
+        expect(mesh.getVertexIndex(t0, i)).toBe(3);
+    }
+
+});
+
+test("allocation increases size", () => {
+    const mesh = new TetrahedralMesh(1);
+
+    expect(mesh.size()).toBe(0);
+
+    mesh.allocate();
+
+    expect(mesh.size()).toBe(1);
+});
+
+test("remove method reduces size", () => {
+    const mesh = new TetrahedralMesh(1);
+
+    const tet = mesh.allocate();
+
+    expect(mesh.size()).toBe(1);
+
+    mesh.remove(tet);
+
+    expect(mesh.size()).toBe(0);
+});
+
+
+test("forEach visits all allocated tets", () => {
+    const mesh = new TetrahedralMesh();
+
+    const t0 = mesh.allocate();
+    const t1 = mesh.allocate();
+
+    const mock = jest.fn();
+
+    mesh.forEach(mock);
+
+    expect(mock).toHaveBeenCalledTimes(2);
+    expect(mock).toHaveBeenCalledWith(t0, mesh);
+    expect(mock).toHaveBeenCalledWith(t1, mesh);
+});
+
+test("exists method", () => {
+    const mesh = new TetrahedralMesh();
+
+    expect(mesh.exists(0)).toBe(false);
+
+    const tet = mesh.allocate();
+
+    expect(mesh.exists(tet)).toBe(true);
+
+    mesh.remove(tet);
+
+    expect(mesh.exists(tet)).toBe(false);
+});