measur-tools-suite 1.1.3 → 1.1.4-beta.0

package/.claude/CLAUDE.md

@@ -0,0 +1,33 @@
+# Project Memory
+
+When generating code, always follow the coding standards and conventions in the [Style Guide](../contributing/style-guide.md). When documenting code, always follow the documentation standards in [Documentation](../contributing/documentation.md). If either linked file is not available in context, ask the user to provide it before proceeding.
+
+When tasked to refactor code using namespaces, follow these phases in order. In all phases, maintain a **one file per logical module** rule: each .h/.cpp pair produces exactly one corresponding binding file, one C++ test file, and one wasm test file.
+
+**Phase 1 — Headers and Source**
+Update the .h and .cpp files to reflect the new structure.
+
+**Phase 2 — WebAssembly Bindings**
+For each .h/.cpp pair, create or update exactly one binding file in bindings-wasm/ (one binding file per logical module, matching its .h and .cpp filenames). If no existing binding file exists for a given pair, create one from scratch following the structure used in processHeat/bindings-wasm/.
+
+**Phase 3 — C++ Unit Tests**
+Update the .cpp unit tests in tests/cpp to reflect the new structure. Each .cpp file must have its own dedicated test file. If an existing test file covers multiple classes that are being split into separate .cpp files, split the test file accordingly.
+
+**Phase 4 — WebAssembly Unit Tests**
+Update or add a unit test in tests/wasm-mocha for each binding file (one test file per binding file). Move old unit tests from tests/wasm to tests/wasm-mocha and update them to reflect the new structure. Once a test has been successfully migrated, delete the original file from tests/wasm.
+
+**Phase 5 — Documentation**
+Update the documentation in the docs/dox-content directory. Organize the content logically following the pattern that has already been established.
+
+**Reference example:** refer to processHeat/ as the canonical example of how to structure the code, WebAssembly bindings, unit tests, and documentation.
+
+**Checklist (verify before finishing):**
+- [ ] Phase 1: All .h and .cpp files updated
+- [ ] Phase 2: One binding file per .h/.cpp pair; new files created where none existed
+- [ ] Phase 3: One C++ test file per .cpp file; split if needed
+- [ ] Phase 4: One wasm test file per binding file; old tests/wasm files migrated and deleted
+- [ ] Phase 5: Documentation updated and organized
+
+## Context
+
+The MEASUR Tools Suite is a collection of industrial efficiency calculations written in C++ with WebAssembly bindings for browser and Node.js environments. The suite provides computational engines for the [MEASUR](https://github.com/ORNL-AMO/AMO-Tools-Desktop) (Manufacturing Energy Assessment Suite for Utility Reduction) application ecosystem.

package/.claude/projects/-Users-txr-dev-MEASUR-Tools-Suite/memory/MEMORY.md

@@ -0,0 +1,3 @@
+# Memory Index
+
+- [CompressedAir namespace refactoring progress](project_compressedair_refactor.md) — tracks which compressedAir calculators are refactored; compressed_air_leak_survey done 2026-05-29

package/.claude/projects/-Users-txr-dev-MEASUR-Tools-Suite/memory/project_compressedair_refactor.md

@@ -0,0 +1,27 @@
+---
+name: CompressedAir namespace refactoring progress
+description: Tracks which compressedAir calculators have been refactored to namespace pattern with docs
+type: project
+---
+
+Progress on refactoring compressedAir calculators to the namespace pattern (free functions, snake_case structs, full doxygen docs, value_object wasm bindings, dox documentation).
+
+**Completed:**
+- `bag_method` — done 2026-05-27
+- `decibels_method` — done (pre-existing)
+- `estimate_method` — done (pre-existing)
+- `orifice_method` — done (pre-existing)
+- `receiver_tank` — done (pre-existing)
+- `compressed_air_leak_survey` — done 2026-05-29
+  - New `include/compressedAir/compressed_air_leak_survey.h` (namespace + enums + full doxygen)
+  - New `src/compressedAir/compressed_air_leak_survey.cpp`
+  - New `bindings-wasm/compressedAir/compressed_air_leak_survey.cpp` (value_object pattern)
+  - Old `bindings-wasm/compressedAir/compressedAirLeakSurvey.cpp` → deleted
+  - New `tests/cpp/compressedAir/compressed_air_leak_survey.unit.cpp`
+  - Old `tests/cpp/compressedAir/CompressedAirLeakSurvey.unit.cpp` → deleted
+  - Updated `tests/wasm-mocha/compressedAir/wasm_compressed_air_leak_survey.test.js`
+  - New `docs/dox-content/calculators/compressedAir/compressed_air_leak_survey_calculator.dox`
+
+**Why:** Namespace pattern improves readability, enables auto-generated API docs, and makes the codebase consistent for the MEASUR Tools Suite.
+
+**How to apply:** When continuing refactoring, check this list to avoid duplicating completed work.

package/BUILD.md

@@ -67,11 +67,12 @@ Install only what you need for the scenario you plan to use.
 
 ## 4. CMake Options
 
-| Option          | Default | Purpose                             |
-| --------------- | ------- | ----------------------------------- |
-| `BUILD_TESTING` | ON      | Build C++ unit tests (`cpp_tests`)  |
-| `BUILD_WASM`    | OFF     | Build WebAssembly module (`client`) |
-| `BUILD_PACKAGE` | OFF     | Enable install + packaging targets  |
+| Option                   | Default | Purpose                                                              |
+| ------------------------ | ------- | -------------------------------------------------------------------- |
+| `BUILD_TESTING`          | ON      | Build C++ unit tests (`cpp_tests`)                                   |
+| `BUILD_WASM`             | OFF     | Build WebAssembly module (`client`)                                  |
+| `BUILD_PACKAGE`          | OFF     | Enable install + packaging targets                                   |
+| `STEAM_MODELER_LOGGING`  | 0       | Enable verbose SteamModeler debug output (see [§10](#10-steammodeler-debug-logging)) |
 
 Mutually influential behavior:
 - When `BUILD_WASM=ON` the build disables `BUILD_TESTING` & `BUILD_PACKAGE` internally (see `CMakeLists.txt`). Toggle intentionally—do not expect tests with WASM in a single configure.
@@ -178,17 +179,26 @@ Artifacts appear under `bin/`
 
 ### 6.5 WebAssembly Usage Example
 
-```js
-// Initialize module
-const moduleFactory = (await import('/path/to/client.js')).default;
-const toolsSuiteModule = await moduleFactory({
+```ts
+import createModule, { type MeasurToolsSuite } from 'measur-tools-suite';
+
+const toolsSuiteModule: MeasurToolsSuite = await createModule({
 	locateFile: (filename) => '/path/to/client.wasm'
 });
 
-// Example call
+// Example 1: wallTotalHeatLoss — returns a number directly
 const totalHeatLoss = toolsSuiteModule.wallTotalHeatLoss(
 	500, 80, 225, 10, 0.9, 1.394, 1
 );
+console.log('Wall total heat loss:', totalHeatLoss);
+
+// Example 2: DryerOperatingCost — class-based API
+// Always call delete() on class instances and output objects to free WASM memory
+const doc = new toolsSuiteModule.DryerOperatingCost(1752, 50, 100, 24, 7, 52, 0.08, 0.2, 0.25);
+const res = doc.calculate(toolsSuiteModule.DryerType.Heatless);
+console.log('DryerOperatingCost => Water removed:', res.waterRemoved);
+res.delete();
+doc.delete();
 ```
 
 ### 6.6 WebAssembly Tests (Browser)
@@ -437,4 +447,45 @@ docker compose down
 
 ---
 
+## 10. SteamModeler Debug Logging
+
+The SteamModeler and all of its supporting classes include verbose debug logging that is **disabled by default** so it never appears in production or WebAssembly builds.
+
+The toggle lives in a single header: `include/steamModeler/util/SteamModelerLogger.h`
+
+```cpp
+#ifndef STEAM_MODELER_LOGGING
+#define STEAM_MODELER_LOGGING 0   // 0 = silent (default), 1 = verbose
+#endif
+```
+
+### Enabling logging
+
+**Option A — Edit the header (local debug session)**
+
+Change the define to `1` and rebuild:
+
+```cpp
+#define STEAM_MODELER_LOGGING 1
+```
+
+**Option B — Compiler flag (no source changes required)**
+
+Pass the flag at configure time:
+
+```bash
+cmake -S . -B build-cpp -DSTEAM_MODELER_LOGGING=1
+cmake --build build-cpp
+```
+
+Or directly via the compiler (without CMake):
+
+```bash
+make CXXFLAGS="-DSTEAM_MODELER_LOGGING=1"
+```
+
+> **Note:** Always revert to `0` (or remove the flag) before building the WASM module for production. Debug output through `std::cout` is visible in the browser DevTools console when `STEAM_MODELER_LOGGING=1` is set in a WASM build.
+
+---
+
 If any scenario you need is missing here, open an issue or submit a PR to extend this guide.

package/README.md

@@ -25,6 +25,8 @@ Check out the [Master List of MEASUR Calculators](https://github.com/ORNL-AMO/AM
 npm install measur-tools-suite
 ```
 
+**JavaScript**
+
 ```js
 // Initialize module
 const moduleFactory = (await import('/path/to/client.js')).default;
@@ -32,10 +34,34 @@ const toolsSuiteModule = await moduleFactory({
 	locateFile: (filename) => '/path/to/client.wasm'
 });
 
-// Example call
+// Plain function call — returns a number directly
 const totalHeatLoss = toolsSuiteModule.wallTotalHeatLoss(
 	500, 80, 225, 10, 0.9, 1.394, 1
 );
+console.log('Wall total heat loss:', totalHeatLoss);
+
+// Class-based API — always call delete() to free WASM memory
+const doc = new toolsSuiteModule.DryerOperatingCost(1752, 50, 100, 24, 7, 52, 0.08, 0.2, 0.25);
+const res = doc.calculate(toolsSuiteModule.DryerType.Heatless);
+console.log('Water removed:', res.waterRemoved);
+res.delete();
+doc.delete();
+```
+
+**TypeScript** — `MeasurToolsSuite` is the fully-typed module instance; no casts needed.
+
+```ts
+import createModule, { type MeasurToolsSuite } from 'measur-tools-suite';
+
+const toolsSuiteModule: MeasurToolsSuite = await createModule({
+	locateFile: (filename) => '/path/to/client.wasm'
+});
+
+const doc = new toolsSuiteModule.DryerOperatingCost(1752, 50, 100, 24, 7, 52, 0.08, 0.2, 0.25);
+const res = doc.calculate(toolsSuiteModule.DryerType.Heatless);
+console.log('Water removed:', res.waterRemoved);
+res.delete();
+doc.delete();
 ```
 
 ### Building from Source

package/bin/client.d.ts

@@ -0,0 +1,198 @@
+export * from "./ts_def_modules/binding/registered_vectors";
+
+export * from "./ts_def_modules/compressedAir/compressedAir";
+export * from "./ts_def_modules/compressedAir/compressed_air_utils";
+export * from "./ts_def_modules/compressedAir/compressorsCalc";
+export * from "./ts_def_modules/compressedAir/dryer_operating_cost";
+export * from "./ts_def_modules/compressedAir/operating_cost";
+export * from "./ts_def_modules/compressedAir/pipe_sizing";
+export * from "./ts_def_modules/compressedAir/pneumatic_air_requirement";
+export * from "./ts_def_modules/compressedAir/pneumatic_valve";
+export * from "./ts_def_modules/compressedAir/receiver_tank";
+
+export * from "./ts_def_modules/compressedAir/leak_survey/bag_method";
+export * from "./ts_def_modules/compressedAir/leak_survey/compressed_air_leak_survey";
+export * from "./ts_def_modules/compressedAir/leak_survey/decibels_method";
+export * from "./ts_def_modules/compressedAir/leak_survey/estimate_method";
+export * from "./ts_def_modules/compressedAir/leak_survey/orifice_method";
+
+export * from "./ts_def_modules/databases/default_data";
+
+export * from "./ts_def_modules/motorDriven/fans/fan";
+export * from "./ts_def_modules/motorDriven/fans/fanEnum";
+export * from "./ts_def_modules/motorDriven/fans/fan_affinity_laws";
+
+export * from "./ts_def_modules/motorDriven/motor/motor";
+export * from "./ts_def_modules/motorDriven/motor/motorEnum";
+
+export * from "./ts_def_modules/motorDriven/pump/pump";
+export * from "./ts_def_modules/motorDriven/pump/pump_valve_power_loss";
+
+export * from "./ts_def_modules/motorDriven/pumpFan/pumpFan";
+
+export * from "./ts_def_modules/other/chp";
+export * from "./ts_def_modules/other/lighting_data";
+export * from "./ts_def_modules/other/powerFactor";
+
+export * from "./ts_def_modules/physics/gas_compositions";
+
+export * from "./ts_def_modules/processCooling/chillers";
+export * from "./ts_def_modules/processCooling/process_cooling";
+
+export * from "./ts_def_modules/processHeat/air_heating_using_exhaust";
+export * from "./ts_def_modules/processHeat/cascade_heat_high_to_low";
+export * from "./ts_def_modules/processHeat/energy_equivalency";
+export * from "./ts_def_modules/processHeat/flow_calculations_energy_use";
+export * from "./ts_def_modules/processHeat/o2_enrichment";
+export * from "./ts_def_modules/processHeat/water_heating_using_exhaust";
+
+export * from "./ts_def_modules/processHeat/losses/atmosphere_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/auxiliary_power_used";
+export * from "./ts_def_modules/processHeat/losses/energy_input_electric_arc_furnace";
+export * from "./ts_def_modules/processHeat/losses/energy_input_exhaust_gas_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/exhaust_gas_heat_loss_electric_arc_furnace";
+export * from "./ts_def_modules/processHeat/losses/fixture_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/gas_cooling_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/gas_flue_gas_material";
+export * from "./ts_def_modules/processHeat/losses/gas_load_charge_material_heat_required";
+export * from "./ts_def_modules/processHeat/losses/leakage_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/liquid_cooling_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/liquid_load_charge_material_heat_required";
+export * from "./ts_def_modules/processHeat/losses/load_charge_material";
+export * from "./ts_def_modules/processHeat/losses/opening_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/slag_other_material_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/solid_liquid_flue_gas_material";
+export * from "./ts_def_modules/processHeat/losses/solid_load_charge_material_heat_required";
+export * from "./ts_def_modules/processHeat/losses/wall_heat_loss";
+export * from "./ts_def_modules/processHeat/losses/water_cooling_heat_loss";
+
+export * from "./ts_def_modules/steam/air_water_cooling_using_flue";
+export * from "./ts_def_modules/steam/steam_leak_survey";
+export * from "./ts_def_modules/steam/water_heating_using_flue";
+export * from "./ts_def_modules/steam/water_heating_using_steam";
+
+export * from "./ts_def_modules/steamModeler/ssmt";
+export * from "./ts_def_modules/steamModeler/ssmtEnum";
+export * from "./ts_def_modules/steamModeler/ssmtModeler";
+
+export * from "./ts_def_modules/treasureHunt/compressed_air_pressure_reduction";
+export * from "./ts_def_modules/treasureHunt/compressed_air_reduction";
+export * from "./ts_def_modules/treasureHunt/electricity_reduction";
+export * from "./ts_def_modules/treasureHunt/insulated_pipe_reduction";
+export * from "./ts_def_modules/treasureHunt/insulated_tank_reduction";
+export * from "./ts_def_modules/treasureHunt/natural_gas_reduction";
+export * from "./ts_def_modules/treasureHunt/steam_reduction";
+export * from "./ts_def_modules/treasureHunt/water_reduction";
+
+export * from "./ts_def_modules/wasteWater/svi";
+export * from "./ts_def_modules/wasteWater/wasteWater";
+
+export * from "./ts_def_modules/water/waterAssessment";
+
+/**
+ * Represents the fully-initialized MEASUR Tools Suite WebAssembly module instance.
+ * This is the intersection of all sub-module types, giving full typed access to every
+ * calculator, class, and enum exposed by the WASM bindings.
+ *
+ * Use this type to annotate the result of the module factory without any casting:
+ * @example
+ * ```ts
+ * import createModule, { type MeasurToolsSuite } from 'measur-tools-suite';
+ * const m: MeasurToolsSuite = await createModule({ locateFile: (f) => `/wasm/${f}` });
+ * ```
+ */
+export type MeasurToolsSuite =
+    // binding
+    import("./ts_def_modules/binding/registered_vectors").RegisteredVectorsModule &
+    // compressedAir
+    import("./ts_def_modules/compressedAir/compressedAir").CompressedAirModule &
+    import("./ts_def_modules/compressedAir/compressed_air_utils").CompressedAirUtilsModule &
+    import("./ts_def_modules/compressedAir/compressorsCalc").CompressorsCalcModule &
+    import("./ts_def_modules/compressedAir/dryer_operating_cost").DryerOperatingCostModule &
+    import("./ts_def_modules/compressedAir/operating_cost").OperatingCostModule &
+    import("./ts_def_modules/compressedAir/pipe_sizing").PipeSizingModule &
+    import("./ts_def_modules/compressedAir/pneumatic_air_requirement").PneumaticAirRequirementModule &
+    import("./ts_def_modules/compressedAir/pneumatic_valve").PneumaticValveModule &
+    import("./ts_def_modules/compressedAir/receiver_tank").ReceiverTankModule &
+    // compressedAir/leak_survey
+    import("./ts_def_modules/compressedAir/leak_survey/bag_method").BagMethodModule &
+    import("./ts_def_modules/compressedAir/leak_survey/compressed_air_leak_survey").CompressedAirLeakSurveyModule &
+    import("./ts_def_modules/compressedAir/leak_survey/decibels_method").DecibelsMethodModule &
+    import("./ts_def_modules/compressedAir/leak_survey/estimate_method").EstimateMethodModule &
+    import("./ts_def_modules/compressedAir/leak_survey/orifice_method").OrificeMethodModule &
+    // databases
+    import("./ts_def_modules/databases/default_data").DefaultDataModule &
+    // motorDriven/fans
+    import("./ts_def_modules/motorDriven/fans/fan_affinity_laws").FanAffinityLawsModule &
+    import("./ts_def_modules/motorDriven/fans/fanEnum").FanEnumModule &
+    import("./ts_def_modules/motorDriven/fans/fan").FanModule &
+    // motorDriven/motor
+    import("./ts_def_modules/motorDriven/motor/motorEnum").MotorEnumModule &
+    import("./ts_def_modules/motorDriven/motor/motor").MotorModule &
+    // motorDriven/pump
+    import("./ts_def_modules/motorDriven/pump/pump").PumpModule &
+    import("./ts_def_modules/motorDriven/pump/pump_valve_power_loss").PumpValvePowerLossModule &
+    // motorDriven/pumpFan
+    import("./ts_def_modules/motorDriven/pumpFan/pumpFan").PumpFanModule &
+    // other
+    import("./ts_def_modules/other/chp").ChpModule &
+    import("./ts_def_modules/other/lighting_data").LightingDataModule &
+    import("./ts_def_modules/other/powerFactor").PowerFactorModule &
+    // physics
+    import("./ts_def_modules/physics/gas_compositions").GasCompositionsModule &
+    // processCooling
+    import("./ts_def_modules/processCooling/chillers").ChillersModule &
+    import("./ts_def_modules/processCooling/process_cooling").ProcessCoolingModule &
+    // processHeat
+    import("./ts_def_modules/processHeat/air_heating_using_exhaust").AirHeatingUsingExhaustModule &
+    import("./ts_def_modules/processHeat/cascade_heat_high_to_low").CascadeHeatHighToLowModule &
+    import("./ts_def_modules/processHeat/energy_equivalency").EnergyEquivalencyModule &
+    import("./ts_def_modules/processHeat/flow_calculations_energy_use").FlowCalculationsEnergyUseModule &
+    import("./ts_def_modules/processHeat/o2_enrichment").O2EnrichmentModule &
+    import("./ts_def_modules/processHeat/water_heating_using_exhaust").WaterHeatingUsingExhaustModule &
+    // processHeat/losses
+    import("./ts_def_modules/processHeat/losses/atmosphere_heat_loss").AtmosphereHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/auxiliary_power_used").AuxiliaryPowerUsedModule &
+    import("./ts_def_modules/processHeat/losses/energy_input_electric_arc_furnace").EnergyInputElectricArcFurnaceModule &
+    import("./ts_def_modules/processHeat/losses/energy_input_exhaust_gas_heat_loss").EnergyInputExhaustGasHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/exhaust_gas_heat_loss_electric_arc_furnace").ExhaustGasHeatLossElectricArcFurnaceModule &
+    import("./ts_def_modules/processHeat/losses/fixture_heat_loss").FixtureHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/gas_cooling_heat_loss").GasCoolingHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/gas_flue_gas_material").GasFlueGasMaterialModule &
+    import("./ts_def_modules/processHeat/losses/gas_load_charge_material_heat_required").GasLoadChargeMaterialHeatRequiredModule &
+    import("./ts_def_modules/processHeat/losses/leakage_heat_loss").LeakageHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/liquid_cooling_heat_loss").LiquidCoolingHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/liquid_load_charge_material_heat_required").LiquidLoadChargeMaterialHeatRequiredModule &
+    import("./ts_def_modules/processHeat/losses/load_charge_material").LoadChargeMaterialModule &
+    import("./ts_def_modules/processHeat/losses/opening_heat_loss").OpeningHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/slag_other_material_heat_loss").SlagOtherMaterialHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/solid_liquid_flue_gas_material").SolidLiquidFlueGasMaterialModule &
+    import("./ts_def_modules/processHeat/losses/solid_load_charge_material_heat_required").SolidLoadChargeMaterialHeatRequiredModule &
+    import("./ts_def_modules/processHeat/losses/wall_heat_loss").WallHeatLossModule &
+    import("./ts_def_modules/processHeat/losses/water_cooling_heat_loss").WaterCoolingHeatLossModule &
+    // steam
+    import("./ts_def_modules/steam/air_water_cooling_using_flue").AirWaterCoolingUsingFlueModule &
+    import("./ts_def_modules/steam/steam_leak_survey").SteamLeakSurveyModule &
+    import("./ts_def_modules/steam/water_heating_using_flue").WaterHeatingUsingFlueModule &
+    import("./ts_def_modules/steam/water_heating_using_steam").WaterHeatingUsingSteamModule &
+    // steamModeler
+    import("./ts_def_modules/steamModeler/ssmtEnum").SsmtEnumModule &
+    import("./ts_def_modules/steamModeler/ssmt").SsmtModule &
+    import("./ts_def_modules/steamModeler/ssmtModeler").SsmtModelerModule &
+    // treasureHunt
+    import("./ts_def_modules/treasureHunt/compressed_air_pressure_reduction").CompressedAirPressureReductionModule &
+    import("./ts_def_modules/treasureHunt/compressed_air_reduction").CompressedAirReductionModule &
+    import("./ts_def_modules/treasureHunt/electricity_reduction").ElectricityReductionModule &
+    import("./ts_def_modules/treasureHunt/insulated_pipe_reduction").InsulatedPipeReductionModule &
+    import("./ts_def_modules/treasureHunt/insulated_tank_reduction").InsulatedTankReductionModule &
+    import("./ts_def_modules/treasureHunt/natural_gas_reduction").NaturalGasReductionModule &
+    import("./ts_def_modules/treasureHunt/steam_reduction").SteamReductionModule &
+    import("./ts_def_modules/treasureHunt/water_reduction").WaterReductionModule &
+    // wasteWater
+    import("./ts_def_modules/wasteWater/svi").SviModule &
+    import("./ts_def_modules/wasteWater/wasteWater").WasteWaterModule &
+    // water
+    import("./ts_def_modules/water/waterAssessment").WaterAssessmentModule;
+
+declare const _default: (moduleArg?: Record<string, unknown>) => Promise<MeasurToolsSuite>;
+export default _default;