simcon-toolkit 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,281 @@
+"""Cloud study harness for the gating study.
+
+Wraps the live Cloud Solver Service (via ``cadmould_cloud.client``) and
+the local ``cadmould`` SDK into the few operations a gating study repeats:
+
+  * **one project, many groups** - the cloud project is created once; each study
+    phase is its own group so the run list stays legible.
+  * **upload geometry once** - reused by every simulation.
+  * **run a batch**       - submit a list of gate/process configs concurrently
+    (the AI filling path is synchronous), download each result, and score it
+    with :mod:`cadmould_scoring.metrics`.
+
+Meshing and gate placement are not here: they are shared code, in
+``cadmould_geometry.mesh``.
+
+Units mirror the API: temperatures Kelvin, spatial mm, flow cm^3/s.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures as cf
+import json
+import os
+import re
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+import numpy as np
+
+from cadmould_cloud import auth as cloud_auth
+from cadmould_cloud.client import PlatformAPI
+from cadmould_geometry.mesh import Geometry
+from cadmould_scoring import metrics as M
+
+# --- platform config (override via env: CLOUD_BASE_URL) ----------------------
+BASE_URL = os.environ.get("CLOUD_BASE_URL", "https://api.simcon.ai/api/v1")
+MODEL_VERSION = "v0.1.0"
+MATERIAL_NAME = "PP Generic"
+NUM_TIMESTEPS = 50
+HTC_W_M2K = 1000.0
+
+GATELOC_DT = np.dtype([("x", "<f8"), ("y", "<f8"), ("z", "<f8"), ("kno", "<i4")])
+
+
+# ==========================================================================
+# simulation config + batch runner
+# ==========================================================================
+@dataclass
+class GateConfig:
+    name: str
+    gates_mm: list[list[float]]
+    flow_rate_cm3_s: float
+    melt_K: float
+    wall_K: float
+    fill_time_s: float
+    notes: str = ""
+    num_timesteps: int = NUM_TIMESTEPS
+    solver_type: str = "ai"
+
+
+@dataclass
+class RunResult:
+    config: GateConfig
+    simulation_id: str
+    h5_path: Path
+    analysis: M.Analysis
+    error: str = ""
+
+    def row(self) -> str:
+        a = self.analysis
+        ng = len(self.config.gates_mm)
+        return f"  {self.config.name:22s} {ng}g  " + (a.summary() if a else f"FAILED: {self.error}")
+
+
+def _augment_for_viewer(path: Path, cfg: GateConfig, geometry_name: str) -> None:
+    """Inject the /input group + root attrs the result loader expects."""
+    import h5py
+
+    with h5py.File(path, "a") as f:
+        f.attrs.setdefault("geometry", geometry_name)
+        f.attrs.setdefault("material", MATERIAL_NAME)
+        if "input" in f:
+            return
+        inp = f.create_group("input")
+        inp.attrs["filling_time"] = float(cfg.fill_time_s)
+        inp.attrs["flowrate"] = float(cfg.flow_rate_cm3_s)
+        inp.attrs["melt_temperature"] = float(cfg.melt_K - 273.15)
+        inp.attrs["wall_temperature"] = float(cfg.wall_K - 273.15)
+        gl = np.zeros(len(cfg.gates_mm), dtype=GATELOC_DT)
+        for i, (x, y, z) in enumerate(cfg.gates_mm):
+            gl["x"][i], gl["y"][i], gl["z"][i], gl["kno"][i] = x, y, z, -1
+        inp.create_dataset("gate_locations", data=gl)
+
+
+class Study:
+    """One cloud project; meshes once, uploads once, runs many grouped batches."""
+
+    def __init__(
+        self,
+        project_name: str,
+        geo: Geometry,
+        stl_name: str,
+        results_root: Path,
+        *,
+        token: str | None = None,
+        geometry_id: str | None = None,
+        logger=print,
+    ):
+        self.geo = geo
+        self.stl_name = stl_name
+        self.results_root = Path(results_root)
+        self.logger = logger
+        self.long_axis = geo.long_axis
+        token = token or cloud_auth.get_access_token()
+        self.api = PlatformAPI(BASE_URL, token, logger=logger)
+        self.project = self.api.get_or_create_project(project_name, notes=f"Gating study for {self.stl_name}")
+        self.project_id = self.project["id"]
+        # material
+        mat = self.api.find_material(MATERIAL_NAME)
+        self.material_id = mat["material_id"]
+        ver = self.api.get_material_version(mat["latest_version"]["version_id"])
+        self.melt_K = float(ver["suggested_mass_temp_K"])
+        self.wall_K = float(ver["suggested_wall_temp_K"])
+        self.geometry_id: str | None = geometry_id  # reuse a prior upload if given
+        self.logger(f"  project '{project_name}' id={self.project_id}")
+        self.logger(
+            f"  material {MATERIAL_NAME} id={self.material_id} "
+            f"melt={self.melt_K - 273.15:.0f}C wall={self.wall_K - 273.15:.0f}C"
+        )
+
+    def close(self):
+        self.api.close()
+
+    def upload_geometry(self):
+        if self.geometry_id:
+            return self.geometry_id
+        up = self.api.request_geometry_upload(self.geo.cfex_path.name, description=f"gating study: {self.stl_name}")
+        self.geometry_id = up["geometry_id"]
+        self.api.put_cfex(up["presigned_put_url"], self.geo.cfex_path)
+        self.logger(f"  geometry_id={self.geometry_id}")
+        return self.geometry_id
+
+    def _filling_with_retry(
+        self, cfg: GateConfig, group_name: str, group_id: str, *, retries: int = 4, backoff: float = 2.0
+    ) -> dict:
+        """run_filling with backoff on transient 503/timeout (the endpoint cold-starts
+        and sheds load under concurrency)."""
+        last = None
+        for attempt in range(retries + 1):
+            try:
+                return self.api.run_filling(
+                    geometry_id=self.geometry_id,
+                    material_id=self.material_id,
+                    gate_positions_mm=cfg.gates_mm,
+                    melt_temperature_K=cfg.melt_K,
+                    wall_temperature_K=cfg.wall_K,
+                    flow_rate_cm3_s=cfg.flow_rate_cm3_s,
+                    estimated_filling_time_s=cfg.fill_time_s,
+                    model_version=MODEL_VERSION,
+                    num_timesteps=cfg.num_timesteps,
+                    htc_W_m2K=HTC_W_M2K,
+                    label=f"{group_name} / {cfg.name}",
+                    project_id=self.project_id,
+                    group_id=group_id,
+                    solver_type=cfg.solver_type,
+                )
+            except httpx.HTTPStatusError as exc:
+                last = exc
+                if exc.response.status_code not in (429, 500, 502, 503, 504):
+                    raise
+            except (httpx.TimeoutException, httpx.TransportError) as exc:
+                last = exc
+            if attempt < retries:
+                time.sleep(backoff * (attempt + 1))  # 2,4,6,8 s
+        raise last
+
+    def make_config(
+        self,
+        name: str,
+        gates_mm,
+        *,
+        flow_rate_cm3_s: float,
+        melt_K: float | None = None,
+        wall_K: float | None = None,
+        notes: str = "",
+        num_timesteps: int = NUM_TIMESTEPS,
+        solver_type: str = "ai",
+    ) -> GateConfig:
+        melt_K = self.melt_K if melt_K is None else melt_K
+        wall_K = self.wall_K if wall_K is None else wall_K
+        fill_time = self.geo.volume_cm3 / flow_rate_cm3_s if flow_rate_cm3_s > 0 else 1.0
+        return GateConfig(
+            name,
+            [list(map(float, g)) for g in gates_mm],
+            float(flow_rate_cm3_s),
+            float(melt_K),
+            float(wall_K),
+            float(round(fill_time, 3)),
+            notes,
+            int(num_timesteps),
+            str(solver_type),
+        )
+
+    def run_group(
+        self,
+        group_name: str,
+        configs: list[GateConfig],
+        *,
+        description: str = "",
+        max_workers: int = 8,
+        group_id: str | None = None,
+    ) -> list[RunResult]:
+        """Create a group (or reuse ``group_id``) and run its configs concurrently."""
+        self.upload_geometry()
+        if group_id is None:
+            grp = self.api.create_group(
+                self.project_id, group_name, description=description or f"{len(configs)} configs"
+            )
+            group_id = grp["id"]
+        else:
+            self.logger(f"  reusing existing group id={group_id}")
+        out_dir = self.results_root / re.sub(r"[^A-Za-z0-9_-]+", "_", group_name)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        self.logger(f"\n  group '{group_name}' id={group_id} -> {len(configs)} sims")
+
+        quiet = self.api.logger
+        self.api.logger = lambda *_: None
+
+        def run_one(cfg: GateConfig) -> RunResult:
+            try:
+                res = self._filling_with_retry(cfg, group_name, group_id)
+                sim_id = res["simulation_id"]
+                h5 = out_dir / f"{cfg.name}__{sim_id[:8]}.h5"
+                self.api.download_to(res["result"]["download"]["url"], h5)
+                _augment_for_viewer(h5, cfg, self.stl_name)
+                analysis = M.analyze(h5, cfg.gates_mm, long_axis=self.long_axis)
+                return RunResult(cfg, sim_id, h5, analysis)
+            except Exception as exc:
+                return RunResult(cfg, "", out_dir / f"{cfg.name}.FAILED", None, error=f"{type(exc).__name__}: {exc}")
+
+        results: list[RunResult] = []
+        with cf.ThreadPoolExecutor(max_workers=min(max_workers, len(configs))) as pool:
+            futs = {pool.submit(run_one, c): c for c in configs}
+            for fut in cf.as_completed(futs):
+                r = fut.result()
+                results.append(r)
+                self.logger(r.row())
+        self.api.logger = quiet
+
+        results.sort(key=lambda r: configs.index(r.config))
+        manifest = out_dir / "manifest.json"
+        manifest.write_text(
+            json.dumps(
+                {
+                    "group": group_name,
+                    "group_id": group_id,
+                    "project_id": self.project_id,
+                    "results": [
+                        {
+                            "name": r.config.name,
+                            "gates_mm": r.config.gates_mm,
+                            "flow_rate_cm3_s": r.config.flow_rate_cm3_s,
+                            "melt_K": r.config.melt_K,
+                            "wall_K": r.config.wall_K,
+                            "fill_time_s": r.config.fill_time_s,
+                            "notes": r.config.notes,
+                            "simulation_id": r.simulation_id,
+                            "h5": str(r.h5_path),
+                            "metrics": r.analysis.as_dict() if r.analysis else None,
+                            "error": r.error,
+                        }
+                        for r in results
+                    ],
+                },
+                indent=2,
+            )
+        )
+        self.logger(f"  wrote {manifest}")
+        return results

simcon_toolkit/_kit/templates/process-window/.gitignore

@@ -0,0 +1,20 @@
+# The campaign writes nothing that is committed. cache/ is ours (mesh, campaign state,
+# and the records each stage leaves for the next) and output/ is yours (the spec and the
+# dossier). Both are listed here rather than left to the kit's root ignore file, because
+# a generated project receives this file and not that one. The output schema is tracked,
+# in doe_spec.schema.md.
+cache/
+output/
+*.h5
+*.car
+*.rm1
+*.cfex
+
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# never commit tokens
+*token*.json
+.env

simcon_toolkit/_kit/templates/process-window/AGENTS.md

@@ -0,0 +1,49 @@
+# Process window — how to drive this template
+
+A design-of-experiments campaign that works out which machine parameters to vary, where to
+centre them and how wide to set the bounds, before anyone books machine time. It sweeps the
+cheap AI solver, screens the result for feasibility, refines the boundary, and writes a DOE
+specification plus a dossier.
+
+The method is in [`METHOD.md`](METHOD.md) — the guardrails, what may be swept, which KPI is
+allowed to decide what, and two traps that silently corrupt a screening. **Read it before
+running a sweep or changing what the campaign measures.**
+
+## What to run
+
+```
+python main.py --list                             # every step, in order
+python main.py inspect --part path/to/part.stl    # is this part worth a campaign at all?
+python main.py sweep configs/simple-plate.yaml
+```
+
+Each step is resumable and writes what the next one reads, so they run in the order `--list`
+prints. There is deliberately no command that runs the whole campaign: judgement belongs
+between the steps.
+
+Everything after the step name belongs to that step — `python main.py refine --help` prints
+that step's own options. The steps do not share a flag set, because the same flag name means
+different things to different steps and folding them together would silently change what a
+campaign ran.
+
+## What is in this folder
+
+- `main.py` is the only thing you run; `process_window/` is the pipeline.
+- `configs/` holds one file per part; `doe_spec.schema.md` is the output schema.
+- `cadmould_cloud/`, `cadmould_geometry/` and `cadmould_scoring/` arrive as packages.
+- `sample/` holds the default geometry, and it is ours.
+- `output/` is yours — the spec and the dossier. `cache/` is ours — the mesh and campaign
+  state. Both are safe to delete; only the cache costs time.
+
+## Things to get right here
+
+**Run `inspect` first.** It is free, and it tells you whether the part is thermally marginal
+enough for a campaign to find anything.
+
+**Every criterion must be relative.** The code fails the run if an absolute pressure threshold
+appears in one, and that guard is there because the model under-reads absolute pressure.
+
+**A campaign is keyed on the part's contents, not its filename.** Re-export the part and it is
+a different campaign, deliberately.
+
+**Do not run anything else while a sweep is running.** It already holds the concurrency budget.

simcon_toolkit/_kit/templates/process-window/METHOD.md

@@ -0,0 +1,155 @@
+---
+# Front matter so the generator can emit this file unchanged as a Claude skill; it is
+# inert everywhere else, and the method below is the same either way.
+name: process-window
+description: >-
+  Find the process window for an injection-moulded part before machine trials: which machine
+  parameters to vary, what centre point to start from, and how wide the bounds should be.
+  Runs a cheap AI sweep over melt temperature, mould temperature and injection rate, screens
+  it for feasibility, refines the boundary, and emits a DOE specification plus a dossier. Use
+  whenever someone asks which settings to trial, how wide to set the bounds, or what a safe
+  starting point is for a new mould.
+---
+
+# Finding a process window
+
+The campaign replaces "standard settings ±10 % and a guess" with a large number of near-free
+AI-solver runs plus a handful of numerical confirmations.
+
+```
+config -> AI sweep -> screening -> boundary refinement
+       -> numerical confirmation set -> doe_spec.yaml + dossier.md
+```
+
+Judgement belongs between the stages, which is why there is no command that runs the whole
+campaign. A sweep costs thousands of solver runs, and whether the result is worth refining is
+a decision, not a step.
+
+## Three guardrails, enforced in code
+
+**1. Relative statements only.** The AI solver under-predicts absolute pressure substantially
+on multi-gate parts, and a campaign usually models fewer cavities than the real tool. Every
+criterion must therefore be a rank, a ratio or a comparison. `process_window/guardrails.py`
+fails the run if an absolute pressure threshold appears in any criterion.
+
+**2. Derive the noise floor for this part, never import one.** Run the epsilon-input micro
+experiment and let it tell you the floor. Any variable whose entire effect sits below it is
+declared inert and fixed, rather than ranked low. Figures measured on another part are
+part-specific and do not transfer.
+
+What the floor is matters: the solver is deterministic, so this measures storage quantisation
+and model conditioning, not run-to-run scatter. Name that mechanism in the dossier rather
+than calling it noise.
+
+**3. Limitations travel with the claim.** How many cavities were modelled, whether a runner
+system was present at all, and how much of the real process is described beyond the material.
+Every dossier claim resting on absolute values carries the caveat automatically.
+
+## What can actually be swept
+
+The AI filling endpoint takes one constant flow rate. There is no switchover input and no
+velocity profile, so exactly three variables are AI-visible:
+
+- melt temperature
+- mould wall temperature
+- injection rate
+
+Anything derived from those is derived, never swept alongside them — sweeping a fill time
+independently of the flow that produces it submits self-inconsistent inputs.
+
+**Switchover is a read-out axis, not a swept input.** Every run holds the full field state at
+every fill fraction, so the pressure, weld-front temperature and unfilled fraction at a
+candidate switchover point come free from runs already paid for. That is the state *at*
+switchover, not the effect *of* switching there — the effect lives in packing, so switchover
+becomes a genuinely swept variable only in the numerical decks.
+
+**Numerical-only variables**, entering at the confirmation stage: switchover point, holding
+pressure level, holding pressure time, cooling time.
+
+## The box
+
+Temperature is an interval scale, so "±50 %" of it depends on the unit chosen and is not a
+well-defined instruction. The campaign therefore takes:
+
+- **melt and mould temperature** — the material card's full processing window, read at
+  runtime, so the box is automatically grade-specific and every corner is physically runnable.
+- **injection rate** — ±50 % around nominal, which is a ratio scale where that is meaningful.
+
+Expect most of the box to be excluded. Knowing *which* part is the whole exercise.
+
+## The KPIs, and what each is allowed to decide
+
+| KPI | Role |
+|---|---|
+| No-flow margin at end of fill | **The hard feasibility gate.** Whether the flow channel stayed open |
+| No-flow margin at arrival | Reported, never a gate — fountain flow keeps the front near melt temperature, so it does not discriminate |
+| Complete fill | Diagnostic only, reported not gated |
+| Max cavity pressure at 80 % fill | Primary continuous KPI. **Ordering only, never an absolute threshold** |
+| Weld-front temperature | Fill-phase quality proxy. Orders points well; carries a circularity caveat when melt temperature drives it |
+| Thermal heterogeneity | Warpage **risk flag** only |
+
+**Never screen on a fill-race metric** — a fill-time difference between two points was
+measured not to transfer. It may be computed as an anomaly detector, clearly labelled.
+
+**Machine limits are a constraint, not a criterion.** They annotate the recommended box; they
+never include or exclude a sweep point. Comparing a pressure the model under-reads against a
+correct machine maximum would pass every point and tell you nothing. Any clamp-force statement
+rests on the projected area actually modelled, so state the extrapolation or omit the claim.
+
+## Two traps that silently corrupt a screening
+
+**Do not gate on fill completeness.** A residual unfilled fraction is a model artefact, and it
+has grown with flow rate — so a "fill percentage must exceed 99" gate rejects every run and
+produces "high injection rate causes short shots", a conclusion that sounds like textbook
+plastics and points the same way a real effect would, while being pure artefact.
+
+Use the no-flow margin instead. It is better engineering regardless: a short shot is a
+*consequence* of the melt freezing before the cavity fills, so the margin is the causal
+quantity, and being continuous it gives a distance to infeasibility, which is what boundary
+refinement needs. A binary gate carries almost no gradient. Measure the residual anyway and
+report the regime.
+
+**Do not average replicates.** The solver is deterministic, so repeats carry no information
+and there are no error bars to be had from them.
+
+## Two practical rules
+
+**Predict whether a sweep will discriminate from fill time against freeze time, not from
+length-to-thickness ratio.** A part can be trivially fillable by that ratio and still be
+thermally marginal, because a thin wall freezes faster than it fills. The inspect step reports
+the wall thickness both times are computed from, and it is free — run it before spending
+anything.
+
+**Never derive the nominal flow from a guessed fill time.** Use the SDK's own suggestion
+tools. A hand-picked fill time was measured 3.5× too slow on a real part, which would have put
+the whole box into freeze-off.
+
+**Do not run anything concurrently with a sweep.** The sweep already holds the concurrency
+budget; adding more makes the endpoint shed load.
+
+## Storage
+
+Results are tens to hundreds of megabytes each and scale with nodes × timesteps, so a
+thousand-run campaign is measured in tens of gigabytes. Score each result, write a small
+record, then delete the result file. Keep the full file only for boundary runs, flagged
+anomalies and confirmation anchors, and never let raw results accumulate in a synced folder.
+Re-scoring a discarded run means re-running it, which is cheap because the solver is
+deterministic.
+
+The timestep count is a knob on both file size and metric fidelity: fewer steps shrink files
+but coarsen the fill-fraction grid the pressure and switchover read-outs depend on.
+
+## Resuming
+
+Assume the session dies mid-sweep. Every run's inputs and outputs go to disk immediately and
+re-running the command resumes rather than restarts. The design sequence is incremental, so a
+sweep can stop early or continue without recommitting.
+
+The KPI definition is part of every run id, so redefining a KPI invalidates records rather
+than letting a resume report them done while permanently missing the new field. Superseded
+records stay on disk as history, so readers must filter.
+
+## Before scaling up
+
+Authenticate, submit one simulation, read the result, print the KPIs. Prove that loop before
+any sweep runs. That is where data-format surprises surface.

simcon_toolkit/_kit/templates/process-window/README.md

@@ -0,0 +1,176 @@
+# Frontloaded DOE — find the process window before the machine trial
+
+A process engineer gets a new mould and has machine trials tomorrow. He needs three things: **which
+parameters to vary, where to start, and how wide the bounds should be.** The usual answer is
+standard settings ±10 % and a guess.
+
+This template replaces the guess with a few thousand near-free AI-solver simulations and a validated
+set of numerical confirmation jobs — from one config file and one command per stage.
+
+```
+config.yaml -> [wide sweep] -> [screening] -> [boundary refinement]
+            -> [numerical confirmation decks] -> doe_spec.yaml + dossier.md
+```
+
+The pipeline writes two things: `doe_spec.yaml`, the machine-readable answer, and `dossier.md`,
+the written one. Both land in `output/<part-key>/` as it runs.
+
+---
+
+## What is and isn't in this directory
+
+| | |
+|---|---|
+| ✅ the full pipeline | `process_window/`, ten stages plus four test suites, numpy only |
+| ✅ the output schema | [`doe_spec.schema.md`](doe_spec.schema.md) — what `doe_spec.yaml` contains |
+| ✅ a working config | [`configs/simple-plate.yaml`](configs/simple-plate.yaml), wired to the sample part |
+| ❌ any campaign output | **not included** — the pipeline writes its own as it runs |
+
+[`configs/simple-plate.yaml`](configs/simple-plate.yaml) points at the sample geometry in
+`sample/`, so you can execute the pipeline end to end immediately. It is also the default every
+stage falls back to when you pass no config, while that is unambiguous. To run the method on
+your own part, copy it and
+change the `part:` block — the part is configured, not passed on the command line, because it
+travels with the material, the bounds and the budget that make a campaign mean something.
+
+Two folders appear as it runs. `cache/` is ours — the mesh and the campaign state — and is safe
+to delete at the cost of recomputing it. `output/` is yours: the spec and the dossier.
+
+## Running it
+
+One command per stage, in this order. `python main.py --list` prints the same list.
+
+```bash
+python main.py inspect                    # free: will a sweep even discriminate?
+python main.py epsilon-floor              # derive THIS part's resolution floor
+python main.py probe                      # does the feasibility gate discriminate?
+python main.py sweep --n 256              # space-filling sweep, resumable
+python main.py screen                     # rank variables, map what is excluded
+python main.py refine                     # adaptive boundary refinement + centre
+python main.py confirm                    # numerical .rm1 decks
+python main.py feedback                   # hidden-deviation self-diagnosis
+python main.py emit                       # doe_spec.yaml + dossier.md
+python main.py economics                  # cycle time vs robustness
+```
+
+Every stage takes the config as an optional argument and falls back to
+`configs/simple-plate.yaml`. Each keeps its own options — `python main.py refine --help`.
+
+⚠️ **Once you have run a campaign on your own part, pass the config every time.** The
+fallback is withdrawn as soon as a second campaign exists, because from then on a bare
+stage could mean either — and picking wrong would read and write the sample's campaign
+while looking like it continued yours. A stage that cannot tell says so and lists what it
+found, rather than guessing.
+
+There is deliberately no command that runs the whole campaign: a sweep costs thousands of
+solver runs, and the point is that you look at each stage before paying for the next.
+
+To inspect several candidate parts side by side:
+
+```bash
+python main.py inspect --part a.stl b.stl
+```
+
+Every stage is **resumable**: a run's identity is a hash of its inputs — including the geometry, the
+model version and the KPI definition — so re-running continues rather than restarts, and redefining
+a KPI invalidates stale records instead of silently reusing them.
+
+Tests need no cloud access and run in seconds:
+
+```bash
+python -m process_window.test_design
+python -m process_window.test_guardrails
+python -m process_window.test_surrogate
+python -m process_window.test_centre
+```
+
+Three modules are runnable the same way, as diagnostics rather than stages — score one
+result file, read a material card, or print the campaign's derived bounds:
+
+```bash
+python -m process_window.kpis <result.h5> [melt_K] [wall_K] [no_flow_K]
+python -m process_window.material_card <your.plb>
+python -m process_window.setup_campaign [configs/simple-plate.yaml]
+```
+
+## What makes this more than a parameter sweep
+
+**Three guardrails are enforced in code, not in comments.**
+
+1. **Relative statements only.** The AI solver under-predicts absolute cavity pressure on multi-gate
+   parts, so every criterion must be a rank, ratio or comparison. `process_window/guardrails.py` *fails the
+   run* if an absolute pressure threshold appears in any criterion.
+2. **The resolution floor is derived per part, never imported.** Nudge the inputs by amounts no
+   machine can hold, measure how far the outputs move anyway, and treat everything below that as the
+   solver's own arithmetic. The floor is a property of the part, not of the
+   method, so importing one part's figure into another wrecks every downstream verdict.
+3. **Stated limitations attach themselves** to any claim that rests on an absolute value.
+
+**The centre point is the Chebyshev centre** — the deepest interior point of the feasible region,
+not the mean of the surviving runs. On an awkwardly shaped region that mean can fall *outside* the
+region entirely, which `process_window/test_centre.py` demonstrates.
+
+## Layout
+
+```
+main.py               the only file you run       configs/   one yaml per part
+process_window/       the pipeline + tests        sample/    the bundled sample part
+doe_spec.schema.md    the output schema
+cache/                mesh + campaign state, ours, safe to delete
+output/               the spec and the dossier, yours
+METHOD.md             the method: guardrails, KPIs, and the traps worth reading first
+```
+
+`METHOD.md` is the highest-value file for anyone extending this: it records the three
+guardrails, which KPI is allowed to decide what, and the two traps that silently corrupt a
+screening. The unit boundaries and the result-file semantics moved to `AGENTS.md`, which
+carries them for every workflow rather than this one.
+
+## Requirements
+
+<!-- simcon-toolkit:setup -->
+**Python 3.12 or newer**, and a virtual environment created *with that interpreter* — a venv
+isolates packages, not the interpreter.
+
+**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 campaign 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 -->
+
+No sklearn: the Sobol sequence,
+the Gaussian-process surrogate, the Sobol sensitivity indices and the distance transform are all
+implemented on numpy and validated against closed-form benchmarks in the test suites.