simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/pyproject.toml

@@ -0,0 +1,232 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cadmould-api-toolkit-starter-kit"
+version = "0.1.0"
+description = "Getting-started kit for the Simcon cadmould Python SDK and cloud platform: docs plus four ready-to-run templates."
+readme = "README.md"
+# A supported window, not the SDK's whole wheel range. The floor is the Python in
+# Ubuntu 24.04 LTS (supported to 2029) and the one our own platform runs; the ceiling
+# is the current release, which is also the Python in Ubuntu 26.04 LTS. CI tests both
+# ends, and tests/test_repository_layout.py fails if the two ever disagree.
+# ⚠️ The upper bound is a standing chore: 3.15 arrives in October 2026 and anyone on it
+# is refused until this line and the CI matrix are bumped together.
+requires-python = ">=3.12,<3.15"
+# Apache-2.0: same convention as cadmould-sdk-auth — the starter kit is OSS, the
+# cadmould SDK it demonstrates stays proprietary. SPDX expression (PEP 639); the
+# license-files default picks up LICENSE and NOTICE. No License:: classifier —
+# deprecated alongside an SPDX expression.
+license = "Apache-2.0"
+authors = [{ name = "SIMCON kunststofftechnische Software GmbH" }]
+keywords = ["cadmould", "simcon", "injection-molding", "simulation", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering",
+]
+
+# Shared runtime dependencies every template uses. The licensed `cadmould` SDK
+# lives on Simcon's private index (AWS CodeArtifact); after running
+# `cadmould-sdk-auth` the index is configured and pip resolves it normally.
+dependencies = [
+    "cadmould>=0.1.0",
+    "numpy>=1.26",
+    "h5py>=3.10",
+    # Reads STL into vertex and face arrays. numpy is its only dependency and it costs
+    # about 3 MB, where the graphics stack it replaced cost roughly 600 MB to do the same job.
+    "trimesh>=4.0",
+]
+
+# Per-template extras — the single source for each template's open deps. Install only
+# what you need, e.g. `pip install ".[gate-study]"` (or `".[templates]"` for all of them).
+#
+# matplotlib, python-pptx and pillow are deliberately absent: the kit no longer renders
+# images or builds decks. A result is opened in the web viewer via the URL the API
+# returns, and a customer's own assistant writes whatever document they want.
+#
+# The graphics stack is gone entirely. quoting was its last user, for ray-casting the
+# geometry; that measurement is now trimesh's, which is both a core dependency already and
+# the only one of the two that gives the same answer twice.
+[project.optional-dependencies]
+# Declares nothing beyond the core dependencies. It stays listed because a template
+# directory with no extra of its own is one nobody can install.
+run-one-simulation = []
+gate-study = ["httpx>=0.27", "scipy>=1.11"]
+quoting = [
+    "rtree>=1.0",  # spatial index behind trimesh's thickness and ray queries (~2 MB)
+    "httpx>=0.27", # cloud REST + the Auth0 PKCE login
+    "scipy>=1.11", # KD-tree behind weld detection (metrics.knn_indices)
+]
+process-window = ["httpx>=0.27", "pyyaml>=6.0", "scipy>=1.11"]
+# Everything the templates need, in one shot. ⚠️ Nothing checks this against the union of
+# the per-template extras above — `AGGREGATE_EXTRAS` in tests/_layout.py only SUBTRACTS the
+# aggregates so they are not mistaken for templates. What the suite does check is that a
+# template directory and its own extra agree. Keeping this list correct is by hand.
+templates = [
+    "rtree>=1.0",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+    "scipy>=1.11",
+]
+# Kept as an extra for `pip install -e ".[test]"` compatibility. scipy is here because the
+# weld-detection golden test drives the scoring module, which resolves neighbours with it.
+test = ["pytest>=7", "scipy>=1.11"]
+
+[project.urls]
+Homepage = "https://github.com/Simcon-Software/cadmould-api-toolkit-starter-kit"
+Repository = "https://github.com/Simcon-Software/cadmould-api-toolkit-starter-kit"
+Documentation = "https://api.simcon.ai/scalar"
+
+# Developer tooling in a PEP 735 dependency group (as in cadmould-sdk-auth). CI and local dev
+# install it with `pip install --upgrade pip && pip install --group dev` — the `--group` flag
+# needs pip >= 25.1, newer than the pip bundled with Python 3.12.
+[dependency-groups]
+dev = [
+    # Source of truth for the ruff version. CI installs ruff via `--group dev`; the only other
+    # copy is `.pre-commit-config.yaml`'s `rev` (it can't read pyproject) — keep the two equal.
+    "ruff==0.15.16",
+    "pre-commit>=3.5",
+    "pytest>=7",
+]
+
+# This project is the kit's own development environment, and it is deliberately never
+# published: it declares the licensed `cadmould` wheel, so a customer resolving it
+# against public PyPI would be refused. It ships no packages for the same reason —
+# pyproject.toml here exists for project metadata, dependency groups and tool
+# configuration.
+#
+# The published artefact is a SECOND project, `cli/`, which declares nothing but its prompt
+# library and carries the templates, the shared libraries, the sample geometry and the
+# manifest inside its own wheel. tests/test_wheel_contents.py builds it and checks that
+# every one of those files arrived.
+[tool.setuptools]
+packages = []
+
+# --- Ruff ----------------------------------------------------------------
+# One rule set for the whole tree. Template code is what customers read and copy, so
+# it is linted like everything else — the blanket amnesty it used to carry excused
+# twelve rule families and hid 970 findings.
+#
+# The selection matches what comparable projects apply to their own teaching code
+# (FastAPI's docs_src, Typer's docs_src): correctness, imports, modernisation and
+# simplification. Annotations (ANN), docstrings (D) and naming (N) are deliberately
+# NOT selected repo-wide — none of those projects selects them for any code, they
+# accounted for 777 of the 970 findings, and annotating every template function makes
+# a tutorial denser rather than clearer. `packages/` is held to a higher bar instead,
+# via its own config file, because that is a library customers import.
+#
+# Exceptions are narrow and each carries its reason: per-file `noqa` for a specific
+# rule, never a directory waved through. tests/ keeps the exemptions every project
+# gives tests.
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+# Never auto-fix implicitly: `ruff check` (no flag) must not rewrite files.
+# Use `ruff check --fix` / `ruff format` explicitly.
+fix = false
+# Honour `exclude` even when pre-commit passes file paths explicitly.
+force-exclude = true
+exclude = [
+    ".git",
+    ".ruff_cache",
+    ".venv",
+    "venv",
+    "build",
+    "dist",
+    "node_modules",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "W",   # pycodestyle warnings
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "PT",  # pytest style
+    "SIM", # flake8-simplify
+    "Q",   # flake8-quotes
+    # A `noqa` naming a rule this repository does not enable suppresses nothing, and
+    # tells a reader the opposite. Five such comments shipped inside the published wheel.
+    "RUF100", # unused-noqa
+]
+ignore = [
+    # Line length is the formatter's job; the linter flagging it too is noise.
+    "E501",
+]
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+# `D` is not selected repo-wide, so this setting does nothing here today. It is kept
+# because `packages/` will select `D` through a config file that extends this one, and
+# the convention has to be inherited rather than restated there.
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.isort]
+# Both the names that exist today and the ones the restructure creates. isort ignores a
+# name that matches nothing, so listing both keeps every intermediate state sorted the same.
+known-first-party = [
+    "cadmould",
+    # Our own tooling, not a template dependency: the code that assembles a project, and
+    # the installer it lives in.
+    "generator",
+    "simcon_toolkit",
+    "cadmould_cloud",
+    "cadmould_geometry",
+    "cadmould_results",
+    "cadmould_scoring",
+]
+split-on-trailing-comma = true
+combine-as-imports = true
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+inline-quotes = "double"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "lf"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests may import fixtures and helpers by name from a sibling module, which reads as
+# an unused import to pyflakes. Every project exempts something here; this is the one
+# thing ours needs now that annotations, docstrings and naming are not selected at all.
+"**/tests/**/*.py" = [
+    "PT011",  # broad pytest.raises without `match` — fine for the SDK errors we re-raise
+]
+
+# --- Pytest --------------------------------------------------------------
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+# The shared libraries in `packages/` are imported by name, not installed: the
+# distribution ships no packages, so pytest is what puts them on the path.
+
+# "." puts the repository root on the path so the tests can import `generator`, the code
+# that assembles a project. The instruction-file tests import its join rather than
+# reimplementing it, so there is one definition of what a customer receives.
+# "cli/src" puts the installer on the path: it owns the manifest reader, because that is
+# the copy that ships, and `generator` reads the manifest through it.
+pythonpath = ["packages", ".", "cli/src"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-ra"
+# Markers say what a test needs, so a lane deselects what it cannot run instead of the
+# test skipping itself from the inside. Nothing here skips on a missing licence or wheel:
+# a lane that selects these and cannot satisfy them must go red, not quietly green.
+markers = [
+    "sdk: needs the licensed cadmould wheel installed (no licence session).",
+    "licence: needs a usable cadmould licence session (HASP or cloud account).",
+    "cloud: hits the live cloud API; needs a licence carrying the LICENCE_API entitlement.",
+]

simcon_toolkit/_kit/templates/_shared/AGENTS.base.md

@@ -0,0 +1,101 @@
+# Working with Cadmould
+
+Rules that hold for every Cadmould workflow. The section after this one describes the
+workflow in this folder.
+
+## Temperatures cross a unit boundary, and getting it wrong is silent
+
+| Where | Unit |
+|---|---|
+| Cloud API (`POST /simulations/filling`, `create_filling_simulation`) | **K** |
+| `.plb` material card (`ProcessTemperatures`, `no_flow_temp`) | **K** |
+| SDK deck builder (`with_material(melt_temp=…)`, `ConstantWallTemp`) | **°C** |
+| `/input` group written for the viewer | **°C** |
+
+Both units appear inside the SDK itself, so a value read from a material card and passed
+straight to the deck builder is wrong by 273.15 and still builds a valid-looking deck.
+Engineers will say Celsius; the wire wants Kelvin. Convert explicitly at every crossing and
+range-check rather than coercing — 513 offered as °C is an error, not a warning.
+
+## Runs are deterministic, so never repeat one
+
+An identical configuration returns an identical result. Re-running for confidence or
+averaging adds nothing, replicates carry zero information, and there are no error bars to
+be had from repeats. Spend every run on a new configuration; get robustness from coverage.
+
+A **failed** run produced nothing, so that one should be re-run.
+
+Do not be conservative with the number of simulations. Run as many as the analysis genuinely
+needs, and prefer breadth over caution.
+
+## A gate must sit on a real geometry node
+
+Gate positions are node positions from the meshed geometry. They cannot be invented, and
+`0, 0, 0` is not one. Nothing the platform returns will give you node coordinates, so take
+them from the mesh you built.
+
+## One licence session, never nested
+
+`cadmould.cloud` needs an active session carrying the API entitlement — including
+`set_base_url`, not only the calls that follow it. Open one session and do everything inside
+it: the base URL, every cloud call, and the local meshing.
+
+A nested session releases the licence when its inner block exits, leaving later calls
+unlicensed. If a meshing helper opens its own session, have it skip that when the caller
+already holds one.
+
+Outside a session you get `LicenceError: Cadmould API licence (LICENCE_API) required` (a
+`RuntimeError`). Inside one, the same error means the licence sign-in failed (see below) or an
+inner session released it. A licence without SDK access
+fails at the session itself, with `Cadmould licence does not include SDK access.`: that is a
+provisioning problem, not a code one.
+
+## Three separate sign-ins, and they fix different things
+
+`cadmould-sdk-auth` configures the package index so the licensed wheel installs. Opening a
+licence session signs in to the licence in the browser, after checking the Thales Sentinel
+run-time on this machine.
+A bearer token authorises *running* simulations. Conflating them is the usual setup failure.
+
+A failed licence sign-in does not raise. It prints `License init failed: <reason>` (or
+`License acquisition failed.`) to the terminal and carries on, so a later `LICENCE_API required`
+is its symptom: find that first line before debugging the call that raised.
+
+When a cloud call fails on auth, do a clean re-login before debugging anything else. Tokens
+go stale in ways that still look valid — a plain `401`, a missing-claim error, or an odd
+audience error — and a fresh login clears most of them:
+
+```
+python -m cadmould_cloud.auth --logout
+python -m cadmould_cloud.auth --print-token --force
+```
+
+Two commands, not one: `--logout` returns before it fetches anything.
+
+## Reading a result without fooling yourself
+
+- **A node has arrived when `Degree_of_filling` crosses 0.5.** Keying off `isfinite` makes
+  every node arrive at t=0.
+- **`Pressure` carries a `unit` attribute** — Pa in current files, bar in older ones. Read it.
+- **Shear can be `+inf` at a gate node.** Reduce over finite values only, or the metric is swamped.
+- **Field arrays are float16**, so sub-Kelvin steps in temperature are storage quantisation
+  rather than physics.
+- **The result geometry is re-centred to the origin** while the gate you sent stays in the
+  part frame. Field metrics are unaffected; anything positional needs the shift.
+- **Do not trust a zero in the result summary.** Read the field.
+
+## One platform address
+
+`https://api.simcon.ai/api/v1`. There is no environment switch and no second address.
+
+## Organising a study
+
+Work is modelled as a **project** — one per mould that will be built — holding **groups** of
+simulations, with a **decision log** kept as project notes recording why each choice was made.
+That surface is REST only; the SDK does not wrap it.
+
+If the task will take more than about five simulations, ask whether to organise it that way
+before starting. For a quick one-off, just run.
+
+Current guidance for assistants lives at <https://agents.simcon.ai/start.md>. Instructions in
+this project always win over anything there.

simcon_toolkit/_kit/templates/gate-study/.gitignore

@@ -0,0 +1,18 @@
+# What this study writes when it runs. A generated project receives THIS file and not the
+# kit's root one, so the rules have to live here or a customer's first commit carries their
+# own meshed geometry and results.
+#
+# cache/ is ours: the meshed .cfex and the per-part study state. Safe to delete - it costs
+# a re-mesh and a re-upload, never a wrong answer.
+# output/ is yours: the scored results of each phase.
+cache/
+output/
+
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# never commit credentials
+*token*.json
+.env

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

@@ -0,0 +1,46 @@
+# Gate study — how to drive this template
+
+A full gating decision for one part, run as four phases: how many gates, where they go, what
+process settings suit them, and a validation pass. Each phase is a cloud group under one
+project, so the study reads as a record rather than a pile of runs.
+
+The method is in [`GATING_STUDY_PLAYBOOK.md`](GATING_STUDY_PLAYBOOK.md). Read it before
+changing what the study measures or pointing it at an unusual part.
+
+## What to run
+
+```
+python main.py group1   # gate count: 1 vs 2 vs 3 vs 4
+python main.py group2   # placement for the count you chose
+python main.py group3   # process and pressure
+python main.py group4   # validation of the final design
+```
+
+Add `--part path/to/your.stl` to study your own geometry; no code edit is needed. The part is
+meshed and uploaded once and the ids are cached, so later phases reuse them.
+
+## What is in this folder
+
+- `main.py` is what you run; `pipeline.py` is the module it drives.
+- `cadmould_cloud/`, `cadmould_geometry/` and `cadmould_scoring/` arrive as packages and are
+  imported by name.
+- `sample/` holds the default geometry, and it is ours.
+- `output/` is yours — scored results. `cache/` is ours — the mesh and the study's state.
+  Both are created on demand and both are safe to delete; only the cache costs time.
+
+## Things to get right here
+
+**Confirm the gate count with the engineer rather than deciding it alone.** It is the one
+genuinely subjective fork in the study, and the phases after it all rest on it. Everything
+else the scoring can settle.
+
+**Run the phases in order.** Each writes what the next reads. Jumping to `group3` without a
+placement decision scores runs against a design nobody chose.
+
+**Weld lines are a placement outcome, not a pass/fail.** Move them somewhere that will not be
+seen rather than trying to eliminate them; that judgement needs the engineer.
+
+**A cached study is keyed on the part's contents, not its filename.** Re-export the part and
+it is a different study, deliberately — the mesh and the decisions on file describe the
+previous revision. If a phase says there is no study on file for a part you have already run,
+the part changed.

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

@@ -0,0 +1,219 @@
+# Gating-study playbook — how to run an early-stage gate/process study
+
+How to drive the cloud AI solver through the early gating decisions for a part, scoring each run
+for filling pressure, fill evenness and weld lines. It ships pointed at `simple_plate.stl` as a
+neutral sample part; the method and tooling generalise to any part.
+
+> TL;DR: mesh the STL with the `cadmould` SDK → upload once to the cloud → run batches of
+> gate/process configs through the filling endpoint → score each result for pressure /
+> fill-evenness / weld lines → decide in four phases (gate **count** → **placement** →
+> **process** → **validation**). Tooling: `pipeline.py`, `metrics.py`, `main.py`.
+
+---
+
+## 0. Mental model
+
+Early-stage gating answers, in order:
+
+1. **How many gates?** Fewer = higher pressure but fewer/cleaner weld lines; more = lower
+   pressure but a weld line between every pair of gates.
+2. **Where do they go?** Position sets flow-length balance (→ even fill + min pressure) and
+   *where the weld lines land* (push them to hidden areas).
+3. **What process?** Flow rate (and melt/wall temp) set the pressure/shear/cycle-time window.
+4. **Is it trustworthy?** Determinism, resolution, sanity vs the numerical solver.
+
+The levers and their effects are in the **physics cheat-sheet** (§6).
+
+---
+
+## 1. Environment
+
+- **venv** with `numpy, h5py, scipy, trimesh, httpx`. No graphics stack: STL reading is
+  trimesh (`cadmould_geometry.stl`) and weld-detection kNN is a scipy KD-tree
+  (`metrics.knn_indices`).
+- **cadmould SDK** (licensed; install via `cadmould-sdk-auth` — see
+  [`README.md`](README.md)) — used for *local meshing* only; the licence
+  is cached (`Session.user_based()`, ~5 s). Meshing/IO live under `cadmould.mesh` /
+  `cadmould.mesh.io` / `cadmould.tools`. The `cadmould.cloud` SDK wraps geometry, materials and
+  simulations but **not** project/group/decision-log management, so this study drives the cloud
+  over the **REST API** via `cadmould_cloud.client::PlatformAPI`.
+- **Cloud auth**: a bearer token for the REST API. `CLOUD_SOLVER_TOKEN` is an optional
+  override; with it unset the study resolves one from the token cache, refreshes it if it has
+  expired, and otherwise opens the browser sign-in — see
+  [`README.md`](README.md). Base URL is a constant in `pipeline.py`
+  (override with `CLOUD_BASE_URL`).
+
+---
+
+## 2. The reusable tooling
+
+| File | What it does |
+|---|---|
+| `pipeline.py` | `Study` = one cloud project; meshes+uploads **once**, runs grouped batches concurrently with retry, downloads + scores. |
+| `cadmould_geometry.mesh` | Shared, in `packages/`. Mesh STL→`.cfex`, **parse cfex node coords**, snap gates to real nodes, gate-line layouts. |
+| `cadmould_scoring.metrics` | Shared, in `packages/`. From a result HDF5: peak **pressure** (bar), max **shear**, **fill %**, **fill evenness** (`tail`), **weld-line detection** + clustering. numpy/h5py/scipy only — no graphics stack. |
+| `main.py` | Driver: `group1` (count) / `group2` (placement) / `group3` (process) / `group4` (validation). Caches the geometry id + decisions in `cache/<part>.study_state.json`. |
+
+Run: `python main.py group1` (then `group2`, …). State persists between
+phases, so the part is meshed + uploaded once.
+
+---
+
+## 3. The workflow
+
+1. **Inspect the geometry first** (bbox, volume, wall thickness, watertight?, holes?, long axis,
+   taper). This *predicts* the gating answer before any simulation — for `simple_plate` the 150 mm
+   length / 1.5 mm wall (L/t ≈ 100, under PP's ~200) already says "one gate is feasible." A
+   quick trimesh script does it (no cloud, no licence) — the kit installs no graphics stack,
+   and `cadmould_geometry.stl` is the reader every template uses.
+2. **Validate the metrics offline first**, against an existing result file, before spending cloud
+   runs — cloud runs are slow and rate-limited, so don't debug metrics on live runs.
+3. **Group 1 — gate count** at a fixed nominal process (1/2/3/4 gates). Also confirms multi-gate
+   is respected and that the weld detector behaves on *this* part.
+4. **Decide the count.** Trade pressure (is it even a constraint?) against weld count/location —
+   a genuine fork worth confirming with the user.
+5. **Group 2 — placement** for the chosen count: sweep position, find the flow-balanced point
+   (lowest `tail`, lowest pressure), check where welds land. A good place to run a **determinism
+   check** (repeat one identical config a few times).
+6. **Group 3 — process**: flow-rate sweep at the chosen gate(s). Map pressure + shear + fill
+   time; pick the fastest fill that keeps pressure & shear comfortable.
+7. **Group 4 — validation**: resolution check (e.g. 50 vs 64 timesteps) and, when available, a
+   numerical cross-check (§5.5). Confirm the headline metrics are stable.
+8. **The write-up.** Hand the scored results and the `manifest.json` to your assistant and ask
+   for the summary you need. The kit produces the numbers, not the document.
+
+Keep each phase its own **cloud group** so the run list stays legible.
+
+---
+
+## 4. Metrics (`metrics.py`)
+
+- **`max_pressure_bar`** — peak per-node `Pressure` over all steps, in **bar** (reads the stored
+  unit). Use this, not the API's `FillingResponse.summary` pressure (not populated).
+- **`fill_time(f)`** → per-node first-arrival time of the front (basis for everything below).
+- **fill evenness `tail_fraction`** — share of total fill time spent filling the last 10 %.
+  ~0.1 = balanced; large = a region lags (imbalance / air-trap risk). `last_filled_region`
+  tells you *where* it finishes (= where to vent).
+- **weld lines** — `detect_welds`: convergence of the **flow-direction field** (gradient of
+  fill-time). A weld node = neighbours' flow vectors point *into* it from opposite sides AND the
+  two incoming fronts are near head-on. Clustered into lines; `cluster_member_mask` keeps only
+  real lines (≥4 connected nodes). Each `WeldCluster` has an `axis_pos` (0..1 along the long
+  axis), so you can say "weld at mid-length" vs "at the end."
+- **`max_shear_rate`** — peak shear rate [1/s] over the fill; the real limiter at high flow rate.
+
+---
+
+## 5. Things to know
+
+### 5.1 Auth
+
+Cloud REST calls need a bearer token, resolved in that order; a `401` means it is missing or
+expired — set a fresh one. (Install-time SDK auth is the separate `cadmould-sdk-auth` login.)
+
+### 5.2 The result file
+
+- `Degree_of_filling` is a per-node 0→1 front: 0 before the front arrives, ramps to 1 once
+  filled. A node is "filled" once it crosses ~0.5 (this is what `fill_time` keys off).
+- Read `Pressure` via `res.pressure_series_bar()` / `metrics.max_pressure_bar` (bar) and shear
+  via `res.shear_rate(step)` (1/s) — both read the stored unit so you don't hard-code it.
+- A result carries the **primary fields only** — no `/input` (process settings) or injection
+  curve. The result loader needs the gate/process settings to place the gate marker, so
+  inject an `/input` group from the values you submitted (`pipeline._augment_for_viewer`).
+- The result is on the solver's **remeshed** geometry, **re-centred to the origin** — not your
+  STL's vertices, and translated from your part's coordinates. So a gate marker from `/input`
+  (your part frame) must be shifted onto the result frame before it's drawn (the viewer's
+  `align_shift` does this), or just placed at the earliest-filled node. Field metrics are
+  unaffected — they live entirely in the result's own frame.
+
+### 5.3 Weld detection
+
+The detector is the convergence of the flow-direction field, gated by a head-on meeting-angle
+check. Two simpler ideas **don't** work and are worth knowing why: (a) "two earlier neighbours on
+opposite sides arriving simultaneously" fires on ordinary flow (two points on the same advancing
+front arc look opposed); (b) "node is a local terminus" labels most nodes on a fine mesh, where
+neighbours fill barely a step apart. **Calibration check:** a single gate should give ~0 interior
+welds (only a tiny one where the front wraps to the far end); two gates should give one line at
+their midpoint. The midsurface mesh has an open rim where flow simply ends and also "converges" —
+those show up as isolated specks and are filtered out by keeping only clusters of ≥4 nodes.
+
+### 5.4 Cloud endpoint
+
+- The AI filling call is **synchronous** (~9 s warm) and **sheds load under concurrency**
+  (5xx). Run **low concurrency** (`max_workers ≈ 2`) with **retry + backoff** (in
+  `_filling_with_retry`); if requests time out, the model is cold — one request warms it.
+- The AI model is **deterministic**: an identical request gives an identical result, so rank
+  configs directly — no need to average repeats.
+- The filling endpoint serves the AI solver; the numerical solver is a separate async flow (§5.5).
+
+### 5.5 Numerical (physics) cross-check
+
+The numerical solver runs on a Cadmould **`.rm1`** input deck (not the `.cfex`, not the AI
+filling request) via a separate **async** flow. Build the rm1 with the SDK:
+
+```python
+from cadmould import io
+from cadmould.domain import SimulationConfig, GatePoints, GatePoint, ConstantWallTemp
+from cadmould.material.io import PlbReader
+mat = PlbReader().load(<plb path>)                          # a material .plb
+cfg = (SimulationConfig.Builder([meshed_mesh])              # parts = list of cadmould.mesh.Mesh
+          .with_material(mat, melt_temp=240.0)              # °C
+          .with_injection(GatePoints([GatePoint(*gate_mm)]))
+          .with_wall_temperature(ConstantWallTemp(40.0))   # mould °C
+          .build())
+io.Rm1Writer().save(cfg, "part.rm1")
+```
+
+Then submit async: `POST /api/v1/simulations` `{file_name, simulation_type:"FILL", rm1_file_name}`
+→ PUT the bytes → `POST /simulations/{id}/submit` (`tier` 1..5) → poll `GET /simulations/{id}` →
+`GET /simulations/{id}/downloads`. **Requires a material `.plb`** for `with_material` (the cloud
+catalogue exposes materials by id, not as a downloadable `.plb`); supply one to enable this path.
+
+### 5.6 Placing custom gates
+
+- The AI surrogate needs each gate to be a **real mesh node**. `run_filling` takes
+  `gate_positions_mm` as a list (multi-gate works).
+- The SDK's `Mesh` / `MeshArray` expose no coordinate getters, so to place gates yourself
+  **parse the written `.cfex`** (ASCII `#NODDAT,N` block: `index,x,y,z` per node —
+  `cadmould_geometry.mesh.parse_cfex_nodes`) and snap your target to the nearest node.
+- `cadmould.tools.suggest_gates` returns a single suggested gate (it doesn't size the count).
+
+---
+
+## 6. Physics cheat-sheet (how to read results)
+
+- **Pressure ∝ longest flow path**, super-linearly → fewer gates / off-centre placement raise it
+  steeply (off-centre placement can easily double the peak versus a centred gate). Centre a single gate to minimise
+  it. For PP, a couple hundred bar cavity pressure is comfortable; machines do far more.
+- **Weld lines land between adjacent gates** (≈ midpoints) and wherever a front wraps and meets
+  itself (a single gate on a long part → welds at the two **ends**). To hide a weld, position
+  gates so their midpoint sits over a hidden feature (end, flange, step).
+- **`flow_rate_cm3_s` is the TOTAL** volumetric rate (fill time = volume/flow, independent of
+  gate count).
+- **Even fill** = both extremities finish together → minimise `tail`; for a single gate on a
+  tapered part the balance point shifts slightly toward the bigger end.
+- **Shear rate rises strongly with flow** and usually caps the flow rate before pressure does.
+- Last-to-fill region = **vent location**.
+
+---
+
+## 7. Adapting to a new part
+
+1. Pass your part on the command line: `python main.py group1 --part path/to/newpart.stl`. The
+   cloud project is named after it and its cache entries carry a fingerprint of its contents,
+   so re-exporting the same part re-meshes and re-uploads on its own. To force that by hand,
+   delete only that part's files — `cache/<part>-*` — and leave the other parts' alone.
+2. Re-inspect the geometry (§3.1); the pipeline auto-picks the long axis from the bounding box.
+3. Run `group1..4`; revisit the gate-count fork with the user.
+4. The weld-detector thresholds (`conv_min=0.45`, `min_angle_deg=120`) are tuned for this mesh
+   density — **re-validate on the new part's 1-gate vs 2-gate runs** (single gate ≈ no interior
+   weld; 2 gates ≈ one line at the midpoint) and adjust if needed.
+
+---
+
+## 8. Limitations
+
+- AI surrogate, one prediction per config. A numerical cross-check needs a material `.plb` (§5.5).
+- The weld detector finds head-on collisions well; the cluster threshold is empirical.
+- **"Visible" vs "hidden" is judged geometrically** (ends/edges = hidden) — confirm against the
+  part's actual Class-A surface definition.
+- 50–64 timesteps is the working range for the filling call.

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

@@ -0,0 +1,26 @@
+# The initial prompt
+
+The gate-study pipeline here is driven by a prompt like the one below — a good template for
+kicking off a gating study: state the goal and the constraints, and let the agent drive the cloud
+solver and make the decisions. (Point the study at your own part with `--part path/to/part.stl`;
+the sample one under `sample/` is only a default.)
+
+> I have a new part to study. I want to use python wheels and
+> simcon's cloud functionality to go through the typical early stage decisions in designing
+> injection molded parts. Place the necessary number of gates, move them to locations that
+> ensure that the part is filled evenly with an acceptable filling-pressure. Ideally, weldlines
+> (so areas where flow fronts meet) are prevented or at least moved to areas where they won't be
+> visibly noticeable. Do as many simulations as necessary. Validate if you feel the need to.
+> Create a new Project for the part, group simulations into logical groups so I won't be
+> overwhelmed by the number of simulations.
+
+## How the harness turns that into a study
+
+It meshes and uploads the part **once**, then runs the cloud AI solver in four logical groups —
+**gate count → gate placement → process window → validation** — scoring each run for filling
+pressure, fill evenness and weld lines, and deciding between groups. The method, the metrics, and
+every gotcha are in
+[`GATING_STUDY_PLAYBOOK.md`](GATING_STUDY_PLAYBOOK.md).
+
+Tip: confirm the one genuinely subjective fork (gate count) with the user mid-study rather than
+guessing — a good pattern.