v0.1.0

Author: mpetrasinovic

.gitignore

@@ -0,0 +1,17 @@
+# Keep only final wasm artifacts in dist
+dist/*
+!dist/mystran.js
+!dist/mystran.wasm
+
+# Docker/host build working directory
+build/
+
+# Native reference used by smoke script
+sources/MYSTRAN_native_ref/
+
+# Fetched third-party sources (recreated by scripts/fetch_deps.ps1)
+sources/MYSTRAN/
+sources/MYSTRAN_Benchmark/
+
+# Generated from embedded assets in tools/build.js
+tools/build_assets/

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 PR-DC contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

PATCHING.md

@@ -0,0 +1,177 @@
+# WebMYSTRAN (WebAssembly)
+
+Builds [MYSTRAN](https://github.com/MYSTRANsolver/MYSTRAN) into WebAssembly and provides:
+
+- reproducible fetch/build scripts
+- quick smoke and full benchmark-deck smoke validation
+- an ESM JavaScript library (`src/web_mystran.js`, `src/mystran_input.js`, `src/output_parser.js`)
+
+## Requirements
+
+- Docker (or compatible daemon)
+- Node.js 18+
+- PowerShell (Windows helper scripts)
+
+## Quick Start (Windows)
+
+1. `powershell -File scripts/fetch_deps.ps1`
+2. `powershell -File scripts/build.ps1`
+3. `node tools/smoke_test.js`
+
+For full benchmark-deck smoke checks:
+
+- `powershell -File scripts/smoke_test.ps1`
+
+## npm Scripts
+
+- `npm run fetch-deps`
+- `npm run build`
+- `npm run smoke` (library-level smoke)
+- `npm run smoke:full` (full deck smoke)
+
+If PowerShell blocks `npm.ps1` by execution policy, run `npm.cmd` instead (for example: `npm.cmd run smoke`).
+
+## Build Outputs
+
+- `dist/mystran.js` (ES module, `MODULARIZE=1`, `EXPORT_ES6=1`)
+- `dist/mystran.wasm`
+- `sources/MYSTRAN_native_ref/Binaries/mystran` (native Linux reference binary for smoke compare)
+
+## Module Exports
+
+- `./index.js` -> `WebMYSTRAN`, `MystranInput`, `parseMystranOutput`
+- `./src/web_mystran.js` -> `WebMYSTRAN`
+- `./src/mystran_input.js` -> `MystranInput`
+- `./src/output_parser.js` -> `parseMystranOutput`
+
+## JavaScript API (`index.js` exports)
+
+### `WebMYSTRAN`
+
+- `static async load(options?) -> Promise<WebMYSTRAN>`
+- `static input(lines?) -> MystranInput`
+- `static Input` (alias for `MystranInput`)
+- `input(lines?) -> MystranInput`
+- `run(deckText, options?) -> result`
+- `readOutput(result, extension, encoding?)`
+- `writeFile(path, data)`, `readFile(path, encoding?)`, `FS`, `reset()`, `destroy()`
+
+`WebMYSTRAN.load(options?)` accepts:
+
+- `moduleUrl`: URL/path override for `dist/mystran.js`
+- `wasmUrl`: URL/path override for `dist/mystran.wasm`
+- `moduleFactory`: custom emscripten module factory function
+- `exportName`: export name when loading from `moduleUrl` (default `WebmystranModule`)
+- `wasmBinary`: `Uint8Array`/`ArrayBuffer`/`Buffer` override for wasm bytes
+- `workDir`: virtual FS working directory (default `/work`)
+- `onStdout`/`onStderr`: per-line callbacks
+- `moduleOptions`/`locateFile`: forwarded to emscripten module options
+
+`run(deckText, options?)`:
+
+- writes `deckText` to `deckFileName` (default `WEBMYSTRAN.DAT`)
+- executes wasm in-process via ESM module factory
+- returns:
+  - `raw`: `{ stdout, stderr, exitCode, signal, timedOut }`
+  - `output`: parsed status object from `parseMystranOutput(raw)`
+  - `outputs`: discovered result files by extension (`F06`, `OP2`, ...)
+  - `files`: artifact metadata `{ extension, name, path, size }`
+  - `workDir`, `deckFileName`, `deckPath`
+
+`run(..., options?)` options:
+
+- `deckFileName`, `workDir`, `stdinText`, `args`
+- `files`: array of `{ path, data }` staged before execution
+- `parseOptions`: forwarded to parser
+- `outputExtensions`: custom extension scan list
+
+### `MystranInput`
+
+Builder for deck text.
+
+- `add(line | lines[])`, `addLines(lines)`
+- `blank(count?)`, `comment(text?)`
+- `sol(value)`, `cend()`, `subcase(id)`
+- `set(key, value)`, `setTitle(value)`, `setSubtitle(value)`, `setLabel(value)`
+- `beginBulk()`, `endData()`
+- `param(name, value)`, `include(path)`
+- `toArray()`, `toString()`
+
+### `parseMystranOutput(raw)`
+
+Parses stdout/stderr into a structured status object:
+
+- `hasNormalTermination`
+- `hasRuntimeAbort`
+- `hasSolverError`
+- `warningCount`
+- `errorCodes`, `firstErrorCode`
+
+## Example
+
+```js
+import fs from "node:fs";
+import { WebMYSTRAN } from "./index.js";
+
+const deck = fs.readFileSync(
+  "sources/MYSTRAN_Benchmark/Benchmark_Decks/Bush_Bar/bar_01.DAT",
+  "utf8"
+);
+
+const solver = await WebMYSTRAN.load();
+const result = solver.run(deck, { deckFileName: "WEBMYSTRAN.DAT" });
+
+if (!result.output.hasNormalTermination) {
+  throw new Error("MYSTRAN did not terminate normally.");
+}
+
+const f06Text = solver.readOutput(result, "F06", "utf8");
+console.log(f06Text.slice(0, 400));
+solver.destroy();
+```
+
+## Smoke Testing
+
+### Library smoke
+
+- `node tools/smoke_test.js`
+- Uses benchmark deck `Bush_Bar/bar_01.DAT`
+- Uses the same per-deck PASS/FAIL line format and final summary format as full smoke
+- Runs both wasm and native reference, then checks wasm/native parity for the deck
+- Validates:
+  - process exit code
+  - `MYSTRAN terminated normally`
+  - no parsed `*ERROR` codes
+  - required output artifacts (`F06`, `OP2`)
+
+### Full deck smoke
+
+- `scripts/smoke_test.ps1` (or `node tools/smoke_test.js full`) runs wasm and native reference over selected benchmark decks
+- Checks:
+  - per-deck wasm and native run outcomes (timeouts/runtime aborts/process errors)
+  - required output generation (`F06` plus non-empty result artifacts)
+  - wasm/native parity checks (outcome class, termination marker, error code, OP2 presence)
+- Reports one terminal line per deck and a final summary line
+- Writes no smoke artifacts to host disk (no `smoke_run` folder or host-side deck outputs)
+
+## Technical References
+
+- Source/dependency provenance: [SOURCES.md](./SOURCES.md)
+- Patch inventory: [PATCHING.md](./PATCHING.md)
+- Third-party notices: [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+
+## Environment Variables
+
+`scripts/build.ps1` forwards:
+
+- `WEBMYSTRAN_DEBUG_STACKS`
+- `WEBMYSTRAN_TRACE_MALLOC`
+- `WEBMYSTRAN_PROFILE_CHECKPOINTS`
+
+`scripts/smoke_test.ps1` accepts smoke arguments directly.
+
+## License
+
+- Project/package: MIT ([LICENSE](./LICENSE))
+- Upstream MYSTRAN source is MIT (see `sources/MYSTRAN/LICENSE.txt`)
+- Additional notices: [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)

README.md

@@ -0,0 +1,48 @@
+# Source Provenance (WebMYSTRAN)
+
+This package builds MYSTRAN into WebAssembly and includes helper scripts for
+fetch, patch, build, and parity validation.
+
+If you redistribute the wasm output, keep this repository (scripts + patches)
+and make the exact upstream sources available.
+
+## Upstream Repositories
+
+### MYSTRAN
+
+- Name: MYSTRAN
+- URL: https://github.com/MYSTRANsolver/MYSTRAN.git
+- Local path: `sources/MYSTRAN`
+- Resolved branch at fetch/build time: `main`
+- Resolved commit: `ae40b554c76c3d27b9b0fdaf697346f8e05251ac`
+- License: MIT (`sources/MYSTRAN/LICENSE.txt`)
+
+### MYSTRAN_Benchmark
+
+- Name: MYSTRAN_Benchmark
+- URL: https://github.com/MYSTRANsolver/MYSTRAN_Benchmark.git
+- Local path: `sources/MYSTRAN_Benchmark`
+- Resolved branch at fetch/build time: `main`
+- Resolved commit: `ad765adfcd2e2fd148743f0846d6ce6e71d33c99`
+- License: see upstream repository
+
+## Fetch and Build Chain
+
+- Fetch script: `scripts/fetch_deps.ps1`
+- Patch generator/applier: `tools/build.js`
+- Containerized build driver: embedded in `tools/build.js` (`tools/build_assets/build_in_docker.sh` at runtime)
+- CMake entrypoint/toolchain: embedded in `tools/build.js` (`tools/build_assets/*` at runtime)
+
+## Patch Policy
+
+- Patches are applied in-place to fetched sources in `sources/MYSTRAN`.
+- Detailed patch inventory is maintained in `PATCHING.md`.
+
+## Repro Note
+
+To reproduce the same source state:
+
+1. Clone this repository.
+2. Run `scripts/fetch_deps.ps1` with matching refs (`-MystranRef`, `-BenchmarkRef`) if needed.
+3. Confirm `git -C sources/MYSTRAN rev-parse HEAD` and
+   `git -C sources/MYSTRAN_Benchmark rev-parse HEAD` match the commit IDs above.

SOURCES.md

@@ -0,0 +1,22 @@
+# Third-Party Notices
+
+The generated artifacts in `dist/` and build/runtime flow may involve these
+third-party components:
+
+- Emscripten SDK (MIT License)
+  - https://emscripten.org/docs/introducing_emscripten/emscripten_license.html
+- LLVM Project (Apache 2.0 with LLVM Exceptions)
+  - https://llvm.org/LICENSE.txt
+- flang-wasm container image
+  - `ghcr.io/r-wasm/flang-wasm:v20.1.4`
+- MYSTRAN upstream source (MIT License)
+  - https://github.com/MYSTRANsolver/MYSTRAN
+- SuperLU / SuperLU_MT (via MYSTRAN submodules)
+  - https://github.com/xiaoyeli/superlu
+  - https://github.com/xiaoyeli/superlu_mt
+- netlib f2c source (used in build toolchain)
+  - https://www.netlib.org/f2c/
+
+This repository does not redistribute the full toolchains. Use the links above
+for their license texts and notices.
+

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,3 @@
+export { WebMYSTRAN } from "./src/web_mystran.js";
+export { MystranInput } from "./src/mystran_input.js";
+export { parseMystranOutput } from "./src/output_parser.js";

dist/mystran.js

@@ -0,0 +1,49 @@
+{
+  "name": "webmystran-wasm",
+  "version": "0.1.0",
+  "description": "WebMYSTRAN WebAssembly build, smoke validation, and Node.js wrapper API.",
+  "author": "Milos Petrasinovic <mpetrasinovic@pr-dc.com>",
+  "keywords": [
+    "mystran",
+    "fea",
+    "fem",
+    "fortran",
+    "wasm",
+    "webassembly"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./mystran": "./src/web_mystran.js",
+    "./web_mystran": "./src/web_mystran.js",
+    "./mystran_input": "./src/mystran_input.js",
+    "./output_parser": "./src/output_parser.js",
+    "./wasm_runner": "./tools/wasm_runner.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "tools/build.js",
+    "tools/smoke_test.js",
+    "tools/wasm_runner.js",
+    "scripts/",
+    "index.js",
+    "README.md",
+    "SOURCES.md",
+    "THIRD_PARTY_NOTICES.md",
+    "PATCHING.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "fetch-deps": "powershell -ExecutionPolicy Bypass -NoProfile -File scripts/fetch_deps.ps1",
+    "build": "node tools/build.js",
+    "smoke": "node tools/smoke_test.js",
+    "smoke-full": "node tools/smoke_test.js full"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}