Atomizer/projects/hydrotech-beam/USER_GUIDE.md

Hydrotech Beam — User Guide (Living)

Audience: Antoine, future users, and Atomizer agents/bots. Status: Living document — update after each meaningful run/decision.

1) Purpose

This guide explains how to run Hydrotech Beam studies safely and reproducibly, how to interpret outputs, and how to avoid common pitfalls (backend mix-up, sync conflicts, stale results).

2) Quick Start

Study folder

C:\Users\antoi\Atomizer\Projects\hydrotech-beam\studies\01_doe_landscape

Core command (real NX run)

python .\run_doe.py --backend nxopen --model-dir "<PATH_TO_NX_MODELS>" --clean --study-name hydrotech_beam_doe_phase1_real

Dev/testing command (fake physics)

python .\run_doe.py --backend stub --clean --study-name hydrotech_beam_doe_phase1_stub

⚠️ stub is synthetic. Do not use stub outputs for engineering decisions.

3) Critical Rules

1. Always specify --backend explicitly (never rely on defaults).
2. Before a decision review, confirm whether results are from nxopen or stub.
3. Keep result artifacts clean (archive conflicts, avoid mixed appended runs unless intentional).
4. After every run, write a run log entry (template below).

4) Run Log Template (required)

Copy this into DECISIONS.md or project log after every run:

## Run Record — YYYY-MM-DD HH:MM
- Operator:
- Command:
- Backend: nxopen | stub
- Model dir:
- Study name:
- Constraints: displacement=__ mm, stress=__ MPa
- Result summary: total=__, solved=__, geo_infeasible=__, feasible=__
- Gate check: PASS | FAIL
- Notes/issues:
- Next action:

5) Playbooks

• playbooks/NX_REAL_RUN.md — clean real run checklist + validation
• playbooks/DOE.md — DOE execution and gate rules
• playbooks/SYNCTHING_RECOVERY.md — sync conflict and stale data recovery

6) Current Known Pitfalls

• run_doe.py default backend is stub unless overridden.
• Mixing old + new runs in same DB/file can produce misleading totals.
• Syncthing conflict files (*.sync-conflict-*) can silently fork truth.
• NX expression names must match exactly (e.g., typo-sensitive names in model).

7) Ownership

• CEO (Antoine): go/no-go and final technical decisions.
• Manager: orchestration + process + documentation enforcement.
• Study Builder: run scripts and settings correctness.
• Tech Lead: engineering validity of constraints and interpretation.
• Auditor: quality gate before external conclusions.