simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/gate-study/README.md

@@ -0,0 +1,137 @@
+# Template · Gate study
+
+A **ready-to-run** early-stage gating study: drive the Simcon cloud AI solver through the
+typical decisions for an injection-moulded part — **how many gates, where, and what process** —
+scoring each run for filling pressure, fill evenness and **weld lines**, organised into tidy
+cloud groups. It ships with the original prompt, the playbook, and all the code, pointed at a
+neutral sample part (`simple_plate.stl`), so you start from something that already runs instead
+of a blank page.
+
+## Why a custom REST client (not `cadmould.cloud`)?
+
+The `cadmould.cloud` SDK wraps the **per-simulation** surface — upload geometry, look up materials,
+run a filling simulation, download the result. It does **not** wrap the **management** surface an
+organised study needs: **projects, groups, and the decision log** (project notes/events). This
+study groups runs by phase (gate count → placement → process → validation) and records *why* each
+choice was made, so it drives the cloud over the **REST API** directly via the `cadmould_cloud`
+package that ships beside this file (`client.py::PlatformAPI` + Auth0 PKCE login). For a
+simple one-off run you don't need any of this — the **run-one-simulation** template shows the SDK
+path; reach for REST only when you need the management/decision-log surface (or just prefer your
+own client). The API itself is documented at <https://api.simcon.ai/scalar>.
+
+## Prerequisites
+
+<!-- simcon-toolkit:setup -->
+**Python 3.12 or newer**, and a virtual environment created *with that interpreter* — a venv
+isolates packages, not the interpreter, so naming it is what makes the version real.
+
+**Three sign-ins, each in your browser, and each does a different job.**
+
+1. **The package index**, once, in the steps below: `cadmould-sdk-auth` lets pip install the
+   licensed `cadmould` wheel from SIMCON's private index. Your company's email domain has to be
+   enabled for it: if you can sign in but the browser tab then says `Access denied: your email
+   domain is not authorized for this API`, ask SIMCON support.
+2. **Your licence**, the first time the code opens a licence session. It first checks the
+   Thales Sentinel run-time on your machine, and prints `License init failed: HASP driver
+   version too old` or `... runtime version too old` when that needs installing or updating.
+3. **The cloud**, the first time the code calls it.
+
+⚠️ A failed licence sign-in does not stop the script. It prints `License init failed: ...` or
+`License acquisition failed.` to the terminal and carries on, so the error you meet later is `Cadmould API licence (LICENCE_API)
+required`. When you see that one, scroll up to the first.
+
+**macOS / Linux (bash):**
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip cadmould-sdk-auth
+cadmould-sdk-auth          # opens a browser; sign in with your Simcon account
+pip install .              # installs cadmould and everything this study needs
+```
+
+**Windows (PowerShell):**
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip cadmould-sdk-auth
+$env:VIRTUAL_ENV = "$PWD\.venv"          # tell the login CLI which venv to configure
+.\.venv\Scripts\cadmould-sdk-auth.exe    # opens a browser; sign in with your Simcon account
+.\.venv\Scripts\python.exe -m pip install .
+```
+
+The Windows route never activates the environment. `Activate.ps1` is blocked by the default
+execution policy on many machines; naming the interpreter outright avoids it.
+<!-- /simcon-toolkit:setup -->
+
+The first cloud run opens the third sign-in, for the cloud — no manual token needed.
+
+## Run it
+
+All commands assume you are **in this folder**.
+
+**macOS / Linux (bash):**
+```bash
+# each phase is its own cloud group; the FIRST run opens the cloud login
+python main.py group1   # gate count: 1 vs 2 vs 3 vs 4
+python main.py group2   # single-gate placement sweep
+python main.py group3   # process / flow-rate sweep
+python main.py group4   # validation
+```
+
+**Windows (PowerShell):**
+```powershell
+python main.py group1
+python main.py group2
+python main.py group3
+python main.py group4
+```
+
+Study your own part instead of the sample one — no code edit needed:
+```bash
+python main.py group1 --part path/to/your-part.stl
+```
+
+The part is meshed and uploaded **once**; `cache/<part>.study_state.json` holds the
+geometry id and the decisions so later phases reuse them — one file per part, so studying a
+second part never inherits the first one's geometry. Each group prints a scored table and
+writes results + a `manifest.json` under `output/<group>/`.
+
+The kit stops at the scored numbers. Turning them into a deck or a write-up is your assistant's
+job, working from the `manifest.json` and the result files — that way the document is in your
+format rather than ours.
+
+## Layout
+
+```
+gate-study/
+├── main.py                      # the driver: group1..4 (run this)
+├── pipeline.py                  # cloud project/group/upload/batch-run + scoring
+├── INITIAL_PROMPT.md            # the prompt that kicks off a study
+├── GATING_STUDY_PLAYBOOK.md     # HOW TO run a gate study + every gotcha (read this)
+├── sample/                      # your copy of the sample part (written when the project
+│                                #   is generated; not present in this repository)
+├── output/                      # yours: scored results, one folder per group
+└── cache/                       # ours: the meshed .cfex and study_state.json
+```
+`output/` and `cache/` are both safe to delete — clearing the cache costs a re-mesh and a
+re-upload, never a different answer. The cloud project is found again by its name.
+
+Running it **inside this repository** needs the shared packages on the path, because the
+generator has not copied them in yet:
+```bash
+PYTHONPATH=packages python templates/gate-study/main.py group1 --part assets/parts/simple_plate.stl
+```
+
+## What each script does
+
+- **`main.py`** — `group1`…`group4`; builds gate configs, submits them concurrently (low
+  concurrency + retry, because the endpoint sheds load), downloads + scores each.
+- **`cadmould_scoring.metrics`** (in `packages/`) — peak pressure (bar), fill evenness (`tail`), and weld lines via
+  convergence of the flow-direction field. Pure numpy, h5py and scipy: reading and scoring a
+  result needs no graphics stack.
+
+## Read this before adapting to a new part
+
+[`GATING_STUDY_PLAYBOOK.md`](GATING_STUDY_PLAYBOOK.md) — the method, the
+metrics, **§7 how to repoint at a new part**, and §5 the non-obvious cloud/SDK/data details
+(weld-detector calibration, the fill-front format, re-centred geometry, endpoint concurrency
+limits, the numerical-solver path).

simcon_toolkit/_kit/templates/gate-study/main.py

@@ -0,0 +1,344 @@
+"""Driver for the gating study (live Simcon cloud AI solver).
+
+Each phase is a subcommand and a logical cloud *group* under one *project*:
+
+    python main.py group1   # gate-count: 1 vs 2 vs 3 vs 4 gates
+    python main.py group2   # gate placement for the chosen count
+    python main.py group3   # process / pressure tuning
+    python main.py group4   # validation of the final design
+
+The part is meshed and the geometry uploaded **once**; the cached state under
+``cache/`` remembers the project + geometry ids (and decisions) so later phases
+reuse them. Scored results land under ``output/``.
+
+The sample part is a default, not a fixture: pass ``--part path/to/your.stl``
+to study your own geometry.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import pipeline
+
+from cadmould_geometry.mesh import Geometry, gate_line, parse_cfex_nodes, prepare_geometry
+
+HERE = Path(__file__).resolve().parent
+# Written by the generator, so this path resolves in your project and not in ours.
+DEFAULT_PART = HERE / "sample" / "simple_plate.stl"
+# Yours: scored results, one folder per group. Safe to delete.
+OUTPUT = HERE / "output"
+# Ours: the meshed geometry and the study's own bookkeeping, both per part. Deleting
+# it costs a re-mesh and a re-upload, never a wrong answer — the cloud project is
+# found again by name.
+CACHE = HERE / "cache"
+
+NOMINAL_FLOW = 45.0  # cm^3/s -> ~2.3 s fill for the 103.6 cm^3 sample part
+
+
+# --------------------------------------------------------------------------
+def part_key(part: Path) -> str:
+    """Cache identity for a part: its name, plus enough of its content to be honest.
+
+    The name alone is not an identity. Two different parts can both be bracket.stl,
+    and re-exporting the same part changes its bytes but not its path — either way a
+    name-keyed cache hands the study a mesh and an uploaded geometry from the wrong
+    version of the part, with nothing to show that it happened.
+    """
+    digest = hashlib.sha256(part.read_bytes()).hexdigest()[:12]
+    return f"{part.stem}-{digest}"
+
+
+def state_path(part: Path) -> Path:
+    """One state file per part: ids and decisions describe a geometry, not a folder."""
+    return CACHE / f"{part_key(part)}.study_state.json"
+
+
+def studies_on_file() -> list[str]:
+    """Every part a study has actually been started for."""
+    if not CACHE.is_dir():
+        return []
+    return sorted(p.name.removesuffix(".study_state.json") for p in CACHE.glob("*.study_state.json"))
+
+
+def resolve_part(explicit: Path | None) -> Path:
+    """The geometry this phase studies, refusing to guess when the flag was left off.
+
+    A later phase reads state a previous one wrote, so falling back to the bundled sample
+    is not a harmless default: run ``group1 --part mine.stl`` and then a bare ``group2``,
+    and the second phase studies the SAMPLE - scoring it, writing its results, and saying
+    nothing. The default therefore stands only while it is unambiguous, which is the demo
+    case of the sample being the only study on file.
+    """
+    if explicit is not None:
+        return explicit
+    started = studies_on_file()
+    mine = part_key(DEFAULT_PART) if DEFAULT_PART.is_file() else None
+    if [k for k in started if k != mine]:
+        listed = "\n  ".join(started)
+        raise SystemExit(
+            "this phase continues a study, so it needs to know which one.\n"
+            "Pass --part pointing at the geometry you ran group1 on.\n"
+            f"Studies on file:\n  {listed}"
+        )
+    return DEFAULT_PART
+
+
+def load_state(state: Path) -> dict:
+    return json.loads(state.read_text()) if state.exists() else {}
+
+
+def save_state(state: Path, **kw) -> None:
+    st = load_state(state)
+    st.update(kw)
+    CACHE.mkdir(parents=True, exist_ok=True)
+    state.write_text(json.dumps(st, indent=2))
+
+
+def get_geometry(part: Path, state: Path) -> Geometry:
+    """Reuse the meshed .cfex if we already have it, else mesh now."""
+    cfex = CACHE / f"{part_key(part)}.cfex"
+    st = load_state(state)
+    if cfex.exists() and st.get("suggested_gate"):
+        nodes = parse_cfex_nodes(cfex)
+        print(f"  reusing meshed {cfex.name} ({len(nodes)} nodes)")
+        return Geometry(cfex, nodes, st["suggested_gate"], st["volume_cm3"], st["long_axis"])
+    CACHE.mkdir(parents=True, exist_ok=True)
+    geo = prepare_geometry(part, cfex)
+    # A fresh mesh invalidates the upload that went with the old one: keeping the id would
+    # skip the upload and run the new gates against the geometry already in the cloud.
+    save_state(
+        state,
+        geometry_id=None,
+        suggested_gate=geo.suggested_gate,
+        volume_cm3=geo.volume_cm3,
+        long_axis=geo.long_axis,
+    )
+    return geo
+
+
+def make_study(geo: Geometry, part: Path, state: Path) -> pipeline.Study:
+    """One cloud project per part, named after it, reused across the four phases."""
+    st = load_state(state)
+    study = pipeline.Study(part.stem, geo, part.name, OUTPUT, geometry_id=st.get("geometry_id"))
+    study.upload_geometry()
+    save_state(state, geometry_id=study.geometry_id)
+    return study
+
+
+def table(results: list[pipeline.RunResult]) -> None:
+    print(
+        f"\n  {'config':20s} {'g':>2} {'flow':>5} {'maxP(bar)':>9} {'shear(1/s)':>10} "
+        f"{'fill%':>6} {'t_fill':>7} {'tail':>5} {'welds':>6}  weld axis-pos/angle"
+    )
+    print("  " + "-" * 116)
+    for r in results:
+        a = r.analysis
+        if a is None:
+            print(f"  {r.config.name:20s}  FAILED: {r.error}")
+            continue
+        wl = ", ".join(f"{c.axis_pos:.2f}/{c.mean_angle_deg:.0f}" for c in a.weld_clusters[:5]) or "-"
+        print(
+            f"  {r.config.name:20s} {len(r.config.gates_mm):>2} {r.config.flow_rate_cm3_s:>5.0f} "
+            f"{a.max_pressure_bar:>9.1f} {a.max_shear_rate_1s:>10.0f} "
+            f"{a.fill_pct:>6.1f} {a.total_fill_time_s:>7.2f} {a.tail_fraction:>5.2f} "
+            f"{a.n_welds:>6}  {wl}"
+        )
+
+
+# --------------------------------------------------------------------------
+def group1(study: pipeline.Study, geo: Geometry, state: Path) -> list[pipeline.RunResult]:
+    """Gate-count study at a fixed nominal process (1 vs 2 vs 3 vs 4 gates)."""
+    cfgs = [
+        study.make_config(
+            "1gate_center",
+            gate_line(geo, [0.5]),
+            flow_rate_cm3_s=NOMINAL_FLOW,
+            notes="single central gate (= cadmould suggestion)",
+        ),
+        study.make_config(
+            "2gate", gate_line(geo, [0.25, 0.75]), flow_rate_cm3_s=NOMINAL_FLOW, notes="2 gates at 1/4, 3/4 length"
+        ),
+        study.make_config(
+            "3gate",
+            gate_line(geo, [1 / 6, 0.5, 5 / 6]),
+            flow_rate_cm3_s=NOMINAL_FLOW,
+            notes="3 gates at 1/6, 1/2, 5/6",
+        ),
+        study.make_config(
+            "4gate",
+            gate_line(geo, [0.125, 0.375, 0.625, 0.875]),
+            flow_rate_cm3_s=NOMINAL_FLOW,
+            notes="4 gates evenly",
+        ),
+    ]
+    res = study.run_group(
+        "G1 - gate count (nominal process)",
+        cfgs,
+        description=(
+            f"Gate-count study on {study.stl_name} at fixed {NOMINAL_FLOW:.0f} cm3/s, "
+            f"melt {study.melt_K - 273.15:.0f}C, wall {study.wall_K - 273.15:.0f}C. "
+            "Trade flow length / pressure against number of weld lines."
+        ),
+    )
+    return res
+
+
+def group2(study: pipeline.Study, geo: Geometry, state: Path) -> list[pipeline.RunResult]:
+    """Single-gate placement: sweep position along the length for balanced fill."""
+    fracs = [0.40, 0.45, 0.50, 0.55, 0.60]
+    cfgs = [
+        study.make_config(
+            f"pos_{int(f * 100):02d}",
+            gate_line(geo, [f]),
+            flow_rate_cm3_s=NOMINAL_FLOW,
+            notes=f"single gate at {f:.2f} of length",
+        )
+        for f in fracs
+    ]
+    res = study.run_group(
+        "G2 - single-gate placement",
+        cfgs,
+        description=(
+            "Single central gate swept along the part length at fixed "
+            f"{NOMINAL_FLOW:.0f} cm3/s. Find the flow-balanced position: "
+            "most even fill (lowest tail), lowest peak pressure, welds at the "
+            "hidden ends. The part tapers, so the optimum may be off geometric centre."
+        ),
+    )
+    # pick: most even fill (low tail) then lowest pressure, among full fills
+    ok = [r for r in res if r.analysis and not r.analysis.short_shot]
+    if ok:
+        best = min(ok, key=lambda r: (round(r.analysis.tail_fraction, 2), r.analysis.max_pressure_bar))
+        save_state(
+            state,
+            best_gate_frac=float(best.config.name.split("_")[1]) / 100.0,
+            best_gate_mm=best.config.gates_mm,
+            best_gate_flow=best.config.flow_rate_cm3_s,
+        )
+        print(
+            f"\n  >> best single-gate placement: {best.config.name} "
+            f"(P={best.analysis.max_pressure_bar:.0f}bar, tail={best.analysis.tail_fraction:.2f}) "
+            f"-> saved to state"
+        )
+    return res
+
+
+def chosen_gate(geo: Geometry, state: Path) -> tuple[list[list[float]], str]:
+    """The gate later phases run at, and an honest name for it.
+
+    Each phase can be run on its own, so group2 may not have happened. Falling back to a
+    central gate is the right behaviour — it is a legitimate baseline — but the description
+    travels to the cloud as this study's record, so it has to say which of the two it got.
+    """
+    gate = load_state(state).get("best_gate_mm")
+    if gate:
+        return gate, "the gate placement group2 selected"
+    return gate_line(geo, [0.5]), "a central gate (group2 has not run, so nothing was selected)"
+
+
+def group3(study: pipeline.Study, geo: Geometry, state: Path) -> list[pipeline.RunResult]:
+    """Process tuning: flow-rate sweep at the gate group2 chose, or at a central baseline."""
+    gate, placement = chosen_gate(geo, state)
+    print(f"  process sweep at {placement}")
+    flows = [25.0, 35.0, 45.0, 60.0, 80.0]  # -> ~4.1, 3.0, 2.3, 1.7, 1.3 s fill
+    cfgs = [
+        study.make_config(
+            f"flow_{int(fl):02d}",
+            gate,
+            flow_rate_cm3_s=fl,
+            notes=f"{fl:.0f} cm3/s -> ~{geo.volume_cm3 / fl:.1f} s fill",
+        )
+        for fl in flows
+    ]
+    res = study.run_group(
+        "G3 - process tuning (flow sweep)",
+        cfgs,
+        description=(
+            f"Flow-rate sweep at {placement} to map the process window: "
+            "peak pressure and shear vs fill time. Pick the fastest fill that "
+            "keeps pressure and shear comfortable."
+        ),
+    )
+    return res
+
+
+def group4(study: pipeline.Study, geo: Geometry, state: Path) -> list[pipeline.RunResult]:
+    """Validate the final design: timestep-resolution stability + numerical cross-check."""
+    gate, placement = chosen_gate(geo, state)
+    print(f"  validating at {placement}")
+    flow = 45.0
+    cfgs = [
+        study.make_config(
+            "final_ai_50steps",
+            gate,
+            flow_rate_cm3_s=flow,
+            notes=f"final design: {placement}, {flow:.0f} cm3/s, 50 steps",
+        ),
+        study.make_config(
+            "final_ai_100steps",
+            gate,
+            flow_rate_cm3_s=flow,
+            num_timesteps=100,
+            notes="resolution check: same design at 100 timesteps",
+        ),
+        study.make_config(
+            "final_numerical",
+            gate,
+            flow_rate_cm3_s=flow,
+            solver_type="numerical",
+            notes="numerical-solver cross-check (best-effort; may be async/unavailable)",
+        ),
+    ]
+    return study.run_group(
+        "G4 - validation (final design)",
+        cfgs,
+        max_workers=1,
+        description=(
+            f"Validation of the recommended design ({placement}, at "
+            f"{flow:.0f} cm3/s). Confirms metrics are stable under finer time resolution "
+            "and cross-checks the AI surrogate against the numerical solver."
+        ),
+    )
+
+
+GROUPS = {"group1": group1, "group2": group2, "group3": group3, "group4": group4}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="gating study driver")
+    ap.add_argument("group", choices=sorted(GROUPS), help="which study phase to run")
+    # Defaults to None rather than to the sample, so a phase can tell "the user said
+    # nothing" from "the user asked for the sample" and refuse to guess between studies.
+    ap.add_argument(
+        "--part",
+        type=Path,
+        default=None,
+        help=f"STL to study (default: {DEFAULT_PART.name} under sample/)",
+    )
+    args = ap.parse_args()
+    args.part = resolve_part(args.part)
+
+    if not args.part.is_file():
+        print(f"geometry not found: {args.part}", file=sys.stderr)
+        print("Pass your own STL with --part, or put one back at sample/simple_plate.stl.", file=sys.stderr)
+        return 2
+
+    state = state_path(args.part)
+    geo = get_geometry(args.part, state)
+    study = make_study(geo, args.part, state)
+    try:
+        results = GROUPS[args.group](study, geo, state)
+    finally:
+        study.close()
+
+    table(results)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())