@meshioplusplus/wasm 10.0.0 → 10.9.0

package/index.d.ts

@@ -236,6 +236,13 @@ export type OpSpec =
       value?: number;
       closure?: RefineClosure;
       recordLevels?: boolean;
+      /**
+       * Attach `refine:cell_id`/`refine:parent_id` -- the persistent
+       * parent/child hierarchy a multigrid caller resolves across the
+       * sequence of meshes it keeps. Also forces `refine:entity` to be
+       * attached even when the closure leaves no hanging node.
+       */
+      recordHierarchy?: boolean;
     }
   | {
       /**
@@ -295,6 +302,34 @@ export type OpSpec =
       output?: string;
       component?: number;
     }
+  | {
+      /**
+       * The Hessian (second derivative) of a scalar `point_data` field --
+       * `gradient`'s companion one order further, for curvature-based
+       * adaptive refinement. A pure data step: geometry is untouched and
+       * one new (n,9) array is attached.
+       */
+      op: 'hessian';
+      array: string;
+      method?: GradientMethod;
+      location?: 'point' | 'cell';
+      output?: string;
+    }
+  | {
+      /**
+       * The ZZ recovery-based error indicator of a `point_data` field, plus
+       * optional marking. A pure data step: geometry is untouched and the
+       * indicator (and, when `marking` is not `"none"`, the marking) array
+       * is attached.
+       */
+      op: 'estimateError';
+      array: string;
+      method?: ErrorMethod;
+      marking?: ErrorMarking;
+      markingValue?: number;
+      output?: string;
+      marked?: string;
+    }
   | {
       /**
        * A regular grid around the mesh. One of the two steps that replace their
@@ -363,6 +398,12 @@ export type SdfWatertightCheck = 'off' | 'warn' | 'error';
 /** `gradient`'s reconstruction method. See doc/gradient.md. */
 export type GradientMethod = 'green-gauss' | 'least-squares';
 
+/** `estimateError`'s estimator family. Only `"zz"` exists today. */
+export type ErrorMethod = 'zz';
+
+/** `estimateError`'s marking policy. See doc/error.md. */
+export type ErrorMarking = 'none' | 'absolute' | 'fraction' | 'dorfler';
+
 /** One data array's location: `point_data`, `cell_data`, or `field_data`. */
 export type DataLocation = 'point' | 'cell' | 'field';
 
@@ -438,6 +479,19 @@ export interface RefineOptions {
   closure?: RefineClosure;
   /** Attach the `refine:level` `cell_data` array. */
   recordLevels?: boolean;
+  /**
+   * Attach the `refine:cell_id`/`refine:parent_id` `cell_data` arrays -- the
+   * persistent parent/child hierarchy a multigrid caller resolves across the
+   * sequence of meshes it keeps ("a link between two meshes, not a tree
+   * inside one"): an unsplit cell keeps its id and is its own parent; a
+   * split cell's children each get a fresh id and carry the parent's id. An
+   * input already carrying `refine:cell_id` is updated whatever this says.
+   * Also forces `refine:entity` to be attached even when the closure leaves
+   * no hanging node, since it already records the coarse corners each new
+   * fine node is the mean of -- the multigrid prolongation weights, which
+   * `'redgreen'`/`'propagate'` would otherwise never expose.
+   */
+  recordHierarchy?: boolean;
 }
 
 /** Where `decimate` places the surviving vertex of a collapsed edge. */
@@ -453,6 +507,10 @@ export type InterpolateMethod = 'nearest' | 'barycentric';
  *  target: throw, replace, or write to `name + '_interp'`. */
 export type InterpolateOnConflict = 'error' | 'overwrite' | 'suffix';
 
+/** What `conservativeInterpolate` does when a transferred name already
+ *  exists on the target: throw, replace, or write to `name + '_interp'`. */
+export type ConservativeInterpolateOnConflict = 'error' | 'overwrite' | 'suffix';
+
 /** Partitioning backend: SFC is always available; KaHIP is never compiled
  *  into the WASM build, so `'kahip'` always throws and `'auto'` = `'sfc'`. */
 export type PartitionMethod = 'sfc' | 'kahip' | 'auto';
@@ -486,6 +544,41 @@ export interface DataArrayInfo {
   inconsistentBlocks: boolean;
 }
 
+/** Cell-measure-weighted reduction of one array over one set of cells (the
+ *  whole mesh, or one named Cell region) -- see `dataIntegrate`. */
+export interface FieldIntegralRegion {
+  /** The region's name; absent on the whole-mesh `domain` entry. */
+  name?: string;
+  /** Cells with a computable measure. */
+  numCells: number;
+  /** Cells excluded: unmeasurable geometry (ragged, unsupported type, or
+   *  degenerate). */
+  numSkipped: number;
+  /** `sum(value * |measure|)` over cells finite in component k. */
+  totalPerComponent: number[];
+  /** `totalPerComponent[k] / domainMeasurePerComponent[k]`, or NaN when that
+   *  denominator is zero. */
+  meanPerComponent: number[];
+  /** `sum(|measure|)` over cells finite in component k. */
+  domainMeasurePerComponent: number[];
+  /** Measurable cells excluded from component k because its value was
+   *  non-finite there. */
+  numNanPerComponent: number[];
+}
+
+/** One array's field integral, returned by `dataIntegrate` --
+ *  `gradient`'s integration counterpart. See doc/field_integration.md. */
+export interface FieldIntegralArray {
+  name: string;
+  numComponents: number;
+  /** The whole-mesh reduction. */
+  domain: FieldIntegralRegion;
+  /** One independent entry per named Cell region present on the mesh -- a
+   *  cell in two regions contributes fully to both, one in none contributes
+   *  to neither. */
+  regions: FieldIntegralRegion[];
+}
+
 /** Heavy-data layout of a transient XDMF series. */
 export type XdmfDataFormat = 'HDF' | 'XML' | 'Binary';
 
@@ -973,6 +1066,48 @@ export interface MeshioPlusPlusModule {
     onConflict?: InterpolateOnConflict,
   ): Mesh;
 
+  /**
+   * Mass-preserving cross-mesh field transfer: an exact overlap-measure
+   * weighted remap, so that over the region the two meshes share,
+   * sum(target value * target measure) equals sum(source value * source
+   * measure) — the property `interpolate`'s `'barycentric'` mode does not
+   * have. Both meshes are simplexified first (accepting ragged/polyhedron
+   * blocks for free, unlike a restricted cell-type scope). Unlike
+   * `interpolate`, an empty `arrays` transfers every source point_data AND
+   * cell_data array — there is one algorithm regardless of location. Output
+   * arrays are always Float64.
+   * @throws {Error} on an unknown onConflict, an unknown array name, a name
+   *   collision under `'error'`, mismatched maximum topological dimensions
+   *   between the two meshes, or no triangle/tetrahedron cells on either
+   *   side after simplexification.
+   */
+  conservativeInterpolate(
+    source: Mesh,
+    target: Mesh,
+    arrays?: string[],
+    defaultValue?: number,
+    onConflict?: ConservativeInterpolateOnConflict,
+  ): Mesh;
+
+  /**
+   * Green-element undo: restore `fine`'s transitional (closure-only) cells
+   * back to their original parent, read verbatim from `coarse` — a lookup,
+   * not a reconstruction, since `refine` never renumbers or prunes points.
+   * `fine` must carry `refine:cell_id`/`refine:parent_id`/`refine:level`
+   * (i.e. must come from `refine(coarse, ..., {recordHierarchy: true,
+   * recordLevels: true})`); `coarse` must be the mesh that call was run on.
+   * The six reserved `refine:*` arrays are dropped from the output. Only a
+   * single-pass (`levels=1`) hierarchy is supported.
+   * @throws {Error} when `fine` lacks the required hierarchy arrays, when a
+   *   `refine:parent_id` value does not resolve against `coarse`'s id space,
+   *   or when a sibling group's level matches neither the red nor the green
+   *   relationship to its coarse parent's own level.
+   */
+  undoGreen(
+    coarse: Mesh,
+    fine: Mesh,
+  ): { mesh: Mesh; numGroupsUndone: number; numCellsRemoved: number };
+
   /** Subset a mesh to an axis-aligned bounding box. */
   cropBbox(mesh: Mesh, lo: number[], hi: number[], mode?: CropMode, recordIds?: boolean): Mesh;
 
@@ -1188,6 +1323,76 @@ export interface MeshioPlusPlusModule {
     overwrite?: boolean,
   ): { mesh: Mesh; numSkipped: number; numFallback: number };
 
+  /**
+   * The Hessian (second derivative) of a **scalar** `point_data` field --
+   * `gradient`'s companion one order further, for curvature-based adaptive
+   * refinement.
+   *
+   * A composition of TWO `gradient` calls, not a new numerical kernel: the
+   * field is differentiated once (point location), then that `(n, 3)`
+   * gradient is differentiated again with the default gradient operator,
+   * producing `(n, 9)` -- the flattened row-major 3x3 Hessian, `H[i][j]` at
+   * index `i*3+j`. `method` is forwarded to BOTH internal passes. The width
+   * travels with the array in the returned mesh's `point_data_components` /
+   * `cell_data_components` maps, exactly as `gradient`'s own output does.
+   *
+   * A field that is at most LINEAR has an exactly zero Hessian everywhere --
+   * the one mesh-shape-independent guarantee. For a genuinely quadratic
+   * field the composition is exact on a structured/symmetric mesh away from
+   * its own boundary and a good, standard, but genuinely approximate
+   * curvature estimate on an irregular mesh (see doc/hessian.md).
+   *
+   * A curvature-driven refinement indicator needs no new API: `norm(...)`
+   * in `dataCalc` on the 9-component output is exactly its Frobenius norm,
+   * ready for `refine`'s `where` selector.
+   * @throws {Error} when `array` names a `cell_data` array (piecewise
+   *   constant, so it has no derivative), an unknown array, or an array
+   *   with more than one component (hessian is scalar-only).
+   */
+  hessian(
+    mesh: Mesh,
+    array: string,
+    method?: GradientMethod,
+    location?: 'point' | 'cell',
+    output?: string,
+    overwrite?: boolean,
+  ): { mesh: Mesh; numSkipped: number; numFallback: number };
+
+  /**
+   * The Zienkiewicz-Zhu (ZZ) recovery-based error indicator of a `point_data`
+   * field, plus optional marking. A composition of `gradient` (Green-Gauss,
+   * cell location) with the measure-weighted point↔cell averaging round
+   * trip: the indicator is `sqrt(|measure| * sum((recovered - raw)^2))` per
+   * cell, attached as `output` (default `"error:zz"`, Float64).
+   *
+   * `marking` is `"none"` (default), `"absolute"`, `"fraction"`, or
+   * `"dorfler"`; when not `"none"` a second Int64 0/1 array `marked`
+   * (default `"error:marked"`) is attached too, so `refine`'s own `where`/
+   * `--where` selector needs no change at all — the intended use is
+   * `refine(mesh, {compare: '>', value: 0.5, array: 'error:marked'})`.
+   * `markingValue`'s meaning depends on `marking`: an absolute indicator
+   * threshold, a fraction in `(0, 1]` of cells, or the Doerfler bulk fraction
+   * theta in `(0, 1]`.
+   *
+   * Cells that cannot be evaluated read NaN in the indicator array and 0
+   * (never NaN) in the marking array, and are counted in `numSkipped`
+   * (excluded from `globalError` and from `numMarked`).
+   * @throws {Error} when `array` names a `cell_data` array (piecewise
+   *   constant, so it has no derivative to recover), an unknown array, an
+   *   unknown method/marking policy, or an out-of-range `markingValue` for
+   *   `"fraction"`/`"dorfler"`.
+   */
+  estimateError(
+    mesh: Mesh,
+    array: string,
+    method?: ErrorMethod,
+    marking?: ErrorMarking,
+    markingValue?: number,
+    output?: string,
+    marked?: string,
+    overwrite?: boolean,
+  ): { mesh: Mesh; globalError: number; numSkipped: number; numMarked: number };
+
   /** Partition a mesh into submeshes by type, connected component, or tag. */
   split(mesh: Mesh, by: SplitBy, tagName?: string): { key: string; mesh: Mesh }[];
 
@@ -1200,6 +1405,33 @@ export interface MeshioPlusPlusModule {
    */
   convertCells(mesh: Mesh, mode?: ConvertCellsMode, recordParentIds?: boolean): Mesh;
 
+  /**
+   * Polyhedrally refine a mesh: one polyhedral child per face of every
+   * eligible 3D cell, connected to a new interior point. Needs no per-type
+   * template table -- tabulated types (reduced to corners for a quadratic
+   * variant) and existing polyhedron blocks are handled uniformly.
+   * Automatically conforming, unlike `refine`. Non-3D blocks and the
+   * full-Lagrange family (no face table) pass through unchanged. Unlike
+   * `convertCells`, there is no point map -- subdivide never prunes or
+   * renumbers an original point.
+   * @throws {Error} when a cell's faces are not a closed orientable surface.
+   */
+  subdivide(mesh: Mesh, recordParentIds?: boolean): Mesh;
+
+  /**
+   * Polyhedrally coarsen a mesh: merge groups of cells into single larger
+   * polyhedral cells via greedy seed-and-grow over the mesh's shared-face
+   * dual, absorbing face-adjacent neighbours into a group until it reaches
+   * `targetGroupSize` (default 8; a short group at a mesh boundary or
+   * pocket is expected, not an error). `targetGroupSize=1` groups every
+   * cell by itself. Non-volume blocks pass through unchanged; points are
+   * never pruned or renumbered (`clean(mesh, ..., true)` is the follow-up
+   * for a minimal point set).
+   * @throws {Error} when targetGroupSize is 0, or the mesh contains a face
+   *   shared by three or more cells (non-manifold).
+   */
+  agglomerate(mesh: Mesh, targetGroupSize?: number): Mesh;
+
   /**
    * Refine a mesh, subdividing cells into same-type children (`line` → 2,
    * `triangle` → 4, `quad` → 4, `tetra` → 8, `wedge` → 8, `hexahedron` → 8).
@@ -1350,6 +1582,14 @@ export interface MeshioPlusPlusModule {
   /** Read-only per-array summary of every data array the mesh carries. */
   dataInfo(mesh: Mesh): DataArrayInfo[];
 
+  /**
+   * Cell-measure-weighted total/mean of one or more cell_data arrays --
+   * gradient's integration counterpart. `arrays` empty/undefined means
+   * every cell_data array. A point_data-only name throws naming
+   * dataPointToCell as the fix. See doc/field_integration.md.
+   */
+  dataIntegrate(mesh: Mesh, arrays?: string[]): FieldIntegralArray[];
+
   /**
    * Open a transient (time-series) XDMF writer on the virtual filesystem --
    * the one stateful object in this API. See {@link XdmfTimeSeriesWriter} for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshioplusplus/wasm",
-  "version": "10.0.0",
+  "version": "10.9.0",
   "description": "meshio++ mesh I/O compiled to WebAssembly: read/write 41 mesh formats (incl. MED, CGNS, Exodus) in the browser or Node.js",
   "type": "module",
   "main": "./src/index.mjs",

package/src/index.mjs

@@ -160,8 +160,12 @@ function resolveVariant(variant) {
  *   distanceToSurface: (query: Mesh, surface: Mesh, sign?: string, location?: string, band?: number, recordInside?: boolean, watertightCheck?: string) => {mesh: Mesh, numBanded: number, quality: object},
  *   computeSdf: (surface: Mesh, structure?: string, resolution?: number[], cellSize?: number, bounds?: number[], padding?: number, paddingRelative?: number, rootResolution?: number, maxDepth?: number, bandCells?: number, recordLevels?: boolean, maxCells?: number, sign?: string, location?: string, band?: number, watertightCheck?: string) => {mesh: Mesh, dims: number[], origin: number[], spacing: number[], maxDepth: number, numBanded: number, quality: object},
  *   gradient: (mesh: Mesh, array: string, operator?: string, method?: string, location?: string, output?: string, component?: number, overwrite?: boolean) => {mesh: Mesh, numSkipped: number, numFallback: number},
+ *   hessian: (mesh: Mesh, array: string, method?: string, location?: string, output?: string, overwrite?: boolean) => {mesh: Mesh, numSkipped: number, numFallback: number},
+ *   estimateError: (mesh: Mesh, array: string, method?: string, marking?: string, markingValue?: number, output?: string, marked?: string, overwrite?: boolean) => {mesh: Mesh, globalError: number, numSkipped: number, numMarked: number},
  *   split: (mesh: Mesh, by: string, tagName?: string) => {key: string, mesh: Mesh}[],
  *   convertCells: (mesh: Mesh, mode?: string, recordParentIds?: boolean) => Mesh,
+ *   subdivide: (mesh: Mesh, recordParentIds?: boolean) => Mesh,
+ *   agglomerate: (mesh: Mesh, targetGroupSize?: number) => Mesh,
  *   refine: (mesh: Mesh, levels?: number, recordParentIds?: boolean,
  *            options?: object) => Mesh,
  *   decimate: (mesh: Mesh, ratio?: number, targetFaces?: number, maxError?: number, placement?: string, preserveBoundary?: boolean, preserveFeatures?: boolean, featureAngle?: number) => {mesh: Mesh, facesRemoved: number, pointsRemoved: number, collapsesRejected: number, maxErrorApplied: number},
@@ -174,6 +178,7 @@ function resolveVariant(variant) {
  *   dataCalc: (mesh: Mesh, expression: string, location: string, outputName: string, overwrite?: boolean) => Mesh,
  *   dataCondition: (mesh: Mesh, location: string, names?: string[], mode?: string, lo?: number, hi?: number, scope?: string, nanPolicy?: string, nanReplacement?: number, suffix?: string) => Mesh,
  *   dataInfo: (mesh: Mesh) => object[],
+ *   dataIntegrate: (mesh: Mesh, arrays?: string[]) => object[],
  *   createXdmfTimeSeriesWriter: (path: string, options?: {dataFormat?: string, gzipLevel?: number, mode?: 'truncate'|'append', autoFlush?: boolean}) => XdmfTimeSeriesWriter,
  * }>}
  */
@@ -352,6 +357,26 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
                 defaultValue,
                 onConflict,
             ),
+        // Mass-preserving cross-mesh field transfer: an exact overlap-measure
+        // weighted remap (unlike interpolate's pointwise sampling). An empty
+        // `arrays` = every source point_data AND cell_data array.
+        conservativeInterpolate: (
+            source,
+            target,
+            arrays = [],
+            defaultValue = 0,
+            onConflict = 'error',
+        ) =>
+            Module.conservativeInterpolate(
+                source,
+                target,
+                arrays,
+                defaultValue,
+                onConflict,
+            ),
+        // Restore `fine`'s transitional (green) cells to their coarse parent,
+        // read verbatim from `coarse` (a lookup, not a reconstruction).
+        undoGreen: (coarse, fine) => Module.undoGreen(coarse, fine),
         cropBbox: (mesh, lo, hi, mode = 'all', recordIds = false) =>
             Module.cropBbox(mesh, lo, hi, mode, recordIds),
         cropPlane: (mesh, point, normal, mode = 'all', recordIds = false) =>
@@ -431,9 +456,39 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
             overwrite = false,
         ) =>
             Module.gradient(mesh, array, operator, method, location, output, component, overwrite),
+        hessian: (
+            mesh,
+            array,
+            method = 'green-gauss',
+            location = 'cell',
+            output = '',
+            overwrite = false,
+        ) => Module.hessian(mesh, array, method, location, output, overwrite),
+        estimateError: (
+            mesh,
+            array,
+            method = 'zz',
+            marking = 'none',
+            markingValue = 0.0,
+            output = '',
+            marked = '',
+            overwrite = false,
+        ) =>
+            Module.estimateError(
+                mesh,
+                array,
+                method,
+                marking,
+                markingValue,
+                output,
+                marked,
+                overwrite,
+            ),
         split: (mesh, by, tagName = '') => Module.split(mesh, by, tagName),
         convertCells: (mesh, mode = 'linearize', recordParentIds = false) =>
             Module.convertCells(mesh, mode, recordParentIds),
+        subdivide: (mesh, recordParentIds = false) => Module.subdivide(mesh, recordParentIds),
+        agglomerate: (mesh, targetGroupSize = 8) => Module.agglomerate(mesh, targetGroupSize),
         refine: (mesh, levels = 1, recordParentIds = false, options = undefined) =>
             Module.refine(mesh, levels, recordParentIds, options),
         // Exactly one of ratio / targetFaces / maxError must be non-negative;
@@ -519,6 +574,7 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
                 mesh, location, names, mode, lo, hi, scope, nanPolicy, nanReplacement, suffix,
             ),
         dataInfo: (mesh) => Module.dataInfo(mesh),
+        dataIntegrate: (mesh, arrays = []) => Module.dataIntegrate(mesh, arrays),
         // Transient (time-series) XDMF -- the one *stateful* thing in this API.
         // The raw binding is an opaque integer handle plus seven free
         // functions (see bindings/wasm/js_bindings.cpp for why it is not an