Update project structure and configurations

2026-05-23 10:19:55 +02:00
parent ab5dc7e568
commit 62efea0646
1832 changed files with 83568 additions and 51829 deletions
--- a/bindings/wasm/README.md
+++ b/bindings/wasm/README.md
@@ -7,7 +7,6 @@ WebAssembly bindings for the [Entropyk](https://github.com/entropyk/entropyk) th
 - **Browser-native execution**: Run thermodynamic simulations directly in the browser
 - **TabularBackend**: Pre-computed fluid tables for fast property lookups (100x faster than direct EOS calls)
 - **Zero server dependency**: No backend required - runs entirely client-side
- **Type-safe**: Full TypeScript definitions included
 - **JSON serialization**: All results are JSON-serializable for easy integration

 ## Installation
@@ -19,30 +18,56 @@ npm install @entropyk/wasm
 ## Quick Start

 ```javascript
-import init, { 
-    WasmSystem, 
+import init, {
+    WasmSystem,
    WasmCompressor,
    WasmCondenser,
    WasmEvaporator,
    WasmExpansionValve,
-    WasmFallbackConfig 
+    WasmFallbackConfig
 } from '@entropyk/wasm';

 // Initialize the WASM module
 await init();

 // Create components
-const compressor = new WasmCompressor("R134a");
-const condenser = new WasmCondenser("R134a", 1000.0);
-const evaporator = new WasmEvaporator("R134a", 800.0);
-const valve = new WasmExpansionValve("R134a");
+// WasmCompressor(fluid, speed_rpm, displacement_m3_per_rev, efficiency, m1..m10)
+const compressor = new WasmCompressor(
+    "R134a",    // fluid
+    2900.0,     // speed_rpm
+    0.0001,     // displacement_m3_per_rev
+    0.85,       // mechanical_efficiency
+    1.0, 0.0, 0.0, 0.0, 0.0,  // AHRI 540 coefficients m1-m5
+    0.0, 0.0, 0.0, 0.0, 0.0   // AHRI 540 coefficients m6-m10
+);

-// Create system
+// WasmCondenser(ua) — thermal conductance in W/K
+const condenser = new WasmCondenser(1000.0);
+
+// WasmEvaporator(ua) — thermal conductance in W/K
+const evaporator = new WasmEvaporator(800.0);
+
+// WasmExpansionValve(fluid, capacity_kW) — pass 0 for no capacity limit
+const valve = new WasmExpansionValve("R134a", 0.0);
+
+// Create system and add components
 const system = new WasmSystem();
+const n0 = system.add_component(compressor.into_component());
+const n1 = system.add_component(condenser.into_component());
+const n2 = system.add_component(valve.into_component());
+const n3 = system.add_component(evaporator.into_component());
+
+// Connect components in a cycle
+system.add_edge(n0, n1)?; // compressor → condenser
+system.add_edge(n1, n2)?; // condenser → valve
+system.add_edge(n2, n3)?; // valve → evaporator
+system.add_edge(n3, n0)?; // evaporator → compressor
+
+// Finalize topology
+system.finalize()?;

 // Configure solver
 const config = new WasmFallbackConfig();
-config.timeout_ms(1000);

 // Solve
 const result = system.solve(config);
@@ -52,7 +77,17 @@ console.log(result.toJson());
 //   "converged": true,
 //   "iterations": 12,
 //   "final_residual": 1e-8,
-//   "solve_time_ms": 45
+//   "status": "Converged"
+// }
+
+// Get thermodynamic state at a node
+const state = system.get_node_result(0);
+console.log(state.toJson());
+// {
+//   "pressure": { "pascals": 1000000.0 },
+//   "temperature": { "kelvin": 310.5 },
+//   "enthalpy": { "joules_per_kg": 420000.0 },
+//   "mass_flow": { "kg_per_s": 0.0 }
 // }
 ```

@@ -60,26 +95,56 @@ console.log(result.toJson());

 ### Core Types

- `WasmPressure` - Pressure in Pascals or bar
- `WasmTemperature` - Temperature in Kelvin or Celsius
- `WasmEnthalpy` - Enthalpy in J/kg or kJ/kg
- `WasmMassFlow` - Mass flow rate in kg/s
+- `WasmPressure` — Pressure in Pascals (constructor validates non-negative)
+  - `new(pascals)` — from Pascals
+  - `from_bar(bar)` — from bar
+- `WasmTemperature` — Temperature in Kelvin (constructor validates non-negative)
+  - `new(kelvin)` — from Kelvin
+  - `from_celsius(celsius)` — from Celsius
+- `WasmEnthalpy` — Enthalpy in J/kg (constructor rejects NaN)
+  - `new(joules_per_kg)` — from J/kg
+  - `from_kj_per_kg(kj_per_kg)` — from kJ/kg
+- `WasmMassFlow` — Mass flow in kg/s (constructor rejects NaN)
+  - `new(kg_per_s)` — from kg/s
+
+All types have a `toJson()` method returning a JSON string.

 ### Components

- `WasmCompressor` - AHRI 540 compressor model
- `WasmCondenser` - Heat rejection heat exchanger
- `WasmEvaporator` - Heat absorption heat exchanger
- `WasmExpansionValve` - Isenthalpic expansion device
- `WasmEconomizer` - Internal heat exchanger
+- `WasmCompressor` — AHRI 540 compressor model
+  - `new(fluid, speed_rpm, displacement, efficiency, m1..m10)` — all 10 AHRI coefficients required
+- `WasmCondenser` — Heat rejection heat exchanger
+  - `new(ua)` — thermal conductance in W/K (must be positive)
+- `WasmEvaporator` — Heat absorption heat exchanger
+  - `new(ua)` — thermal conductance in W/K (must be positive)
+- `WasmExpansionValve` — Isenthalpic expansion device
+  - `new(fluid, capacity_kW)` — pass 0 for no capacity limit
+- `WasmPipe` — Transport pipe
+  - `new(fluid, length, diameter, density, viscosity)` — all parameters required
+
+Each component has an `into_component()` method that converts it to a generic `WasmComponent` for adding to the system.

 ### Solver

- `WasmSystem` - Thermodynamic system container
- `WasmNewtonConfig` - Newton-Raphson solver configuration
- `WasmPicardConfig` - Sequential substitution solver configuration
- `WasmFallbackConfig` - Intelligent fallback solver configuration
- `WasmConvergedState` - Solver result
+- `WasmSystem` — Thermodynamic system container
+  - `add_component(component)` → node index
+  - `add_edge(from_idx, to_idx)` — connect two component nodes
+  - `finalize()` — finalize topology before solving
+  - `solve(config)` — solve with fallback strategy
+  - `solve_newton(config)` — solve with Newton-Raphson only
+  - `get_node_result(idx)` — get thermodynamic state at a node after solving
+- `WasmNewtonConfig` — Newton-Raphson solver configuration
+  - `set_max_iterations(n)`, `set_tolerance(tol)`
+- `WasmPicardConfig` — Sequential substitution solver configuration
+  - `set_max_iterations(n)`, `set_relaxation_factor(omega)` — omega clamped to (0, 1]
+- `WasmFallbackConfig` — Intelligent fallback solver configuration
+  - `set_fallback_enabled(bool)`, `set_return_to_newton_threshold(f64)`, `set_max_fallback_switches(usize)`
+- `WasmConvergedState` — Solver result with `converged`, `iterations`, `final_residual`, `status`
+
+### Fluid Management
+
+- `list_available_fluids()` — returns array of available fluid names
+- `load_fluid_table(json_string)` — load a custom fluid table from JSON

 ## Build Requirements

@@ -95,13 +160,22 @@ git clone https://github.com/entropyk/entropyk.git
 cd entropyk/bindings/wasm

 # Build for browsers
-npm run build
+wasm-pack build --target web

 # Build for Node.js
-npm run build:node
+wasm-pack build --target nodejs

-# Run tests
-npm test
+# Run Rust WASM tests
+wasm-pack test --node
+```
+
+## TypeScript Support
+
+TypeScript definitions are auto-generated by `wasm-pack build` in the `pkg/` directory.
+After building, import the generated `.d.ts` file:
+
+```typescript
+import init, { WasmSystem } from './pkg/entropyk_wasm';
 ```

 ## Performance
@@ -115,17 +189,8 @@ npm test
 ## Limitations

 - **CoolProp unavailable**: The WASM build uses TabularBackend with pre-computed tables. CoolProp C++ cannot compile to WebAssembly.
- **Limited fluid library**: By default, only R134a is embedded. Additional fluids can be loaded from JSON tables.
-
-## Loading Custom Fluid Tables
-
-```javascript
-import { load_fluid_table } from '@entropyk/wasm';
-
-// Load a custom fluid table (generated from the entropyk CLI)
-const r410aTable = await fetch('/path/to/r410a.json').then(r => r.text());
-await load_fluid_table(r410aTable);
-```
+- **Limited fluid library**: By default, only R134a is embedded. Additional fluids can be loaded from JSON tables generated by the entropyk CLI.
+- **Custom fluid tables**: `load_fluid_table` validates the table but registration in the global backend requires additional infrastructure (planned).

 ## Browser Compatibility