simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/process-window/configs/simple-plate.yaml

@@ -0,0 +1,116 @@
+# Frontloaded DOE — runnable configuration against the sample part shipped with this repo.
+#
+# Paths are relative to this template's root (the folder containing main.py and configs/).
+#
+# This config points at the sample part in `sample/`, so the pipeline can be executed end to
+# end without any private input. Replace the `part:` block to run it on your own geometry.
+#
+# Expect a modest answer: run
+#   python main.py inspect
+# first. A thick, generously-proportioned plate fills long before its walls freeze, so the
+# feasibility gate will very likely never bite and the whole box will come back green. That is a
+# true result, not a broken run: it is what a thick-walled part looks like, and it is the signal
+# to try a thinner-walled one.
+
+part:
+  name: Simple Plate
+  stl: "sample/simple_plate.stl"
+  scale: 1.0                                     # 1.0 = already in mm
+
+material:
+  # NOT SHIPPED. A .plb is a licensed Cadmould material file and is not in this repository.
+  #
+  # It is only needed for the G4 numerical decks (SimulationConfig.Builder wants a Material
+  # object, and PlbReader is the only loader). G0-G3 do not need it: the cloud catalogue's
+  # material version carries no_flow_temperature_K, the thermal data and the processing window,
+  # and they agree with the local card exactly.
+  #
+  # Point this at your own .plb export, or drop the G4 stage.
+  plb: "PP Generic.plb"
+  catalogue_name: "PP Generic"
+  is_placeholder: true
+
+gates:
+  # `suggest` asks the SDK for an on-mesh gate. The surrogate requires the gate to be a real mesh
+  # node — never an off-mesh point, never (0,0,0).
+  mode: suggest
+  # positions_mm: [[x, y, z]]   # set this to override, snapped to the nearest node
+
+variables:
+  # The only three variables the AI filling solver can see. Bounds are DERIVED:
+  #   melt, wall  -> the material card's full processing window
+  #   flow        -> nominal +/- 50 %
+  # Temperature bounds are not a percentage: temperature is an interval scale, so "+/-50 %" of it
+  # is not a well-defined instruction. The card's own processing window is the honest wide box.
+  melt:
+    from: material_card
+  wall:
+    from: material_card
+  flow:
+    from: sdk_suggestion        # suggest_fill_profile + estimate_fill_time, never a guessed time
+    rel_span: 0.50
+
+  # Switchover is NOT swept: the AI endpoint has no switchover input. It is a read-out axis on
+  # every run, and a swept input only in the G4 numerical decks.
+  switchover_readout_phi: [0.90, 0.95, 0.98, 0.99]
+
+packing_cooling:
+  from: sdk_suggestion
+
+feasibility_gate:
+  primary: no_flow_margin_end_K   # absolute superheat above no-flow, in K
+  fill_completeness:
+    use_as_gate: auto             # only if the residual is ~0 AND flow-independent
+    residual_tolerance: 0.005
+    report_always: true
+
+budget:
+  # Deliberately small so a first run finishes quickly.
+  # Sobol is incremental, so raising this later reuses every run already done.
+  epsilon_floor_runs: 17
+  sweep_points: 256
+  refine_points: 96
+  confirmation_points: 14
+  fake_real_anchors: 3
+
+solver:
+  num_timesteps: 50            # 50-64 safe; ~100 returns 502 from the gateway
+  htc_W_m2K: 1000.0            # fixed, not swept
+  max_concurrency: 4           # the endpoint sheds load above this
+  retry:
+    attempts: 4
+    backoff_s: 2.0
+    on_status: [429, 500, 502, 503, 504]
+
+cloud:
+  rest_base_url: "https://api.simcon.ai/api/v1"
+  # Driven over REST rather than the SDK: the SDK cannot set num_timesteps (which controls both
+  # the phi resolution the KPIs depend on and the result file size) or pin model_version.
+  model_version: "v0.1.0"
+  project: "DOE Frontloading"
+  group_per_stage: true
+
+storage:
+  # Results are 25-220 MB each. Score, write a ~2 kB summary, then delete the raw file — except
+  # where the run is worth keeping. A per-part subfolder is appended automatically.
+  #
+  # Under cache/ because it is ours and safe to delete: everything here can be recomputed,
+  # it only costs time and solver runs. The campaign's answer lands in output/.
+  runs_dir: "cache/runs"
+  keep_h5:
+    - boundary
+    - anomaly
+    - anchor
+
+machine_limits:
+  # Applied as a final feasibility ANNOTATION only, never as a screening criterion: a machine
+  # limit is a constraint, and guardrail 1 forbids absolute pressure thresholds in criteria.
+  max_injection_pressure_bar: 1500.0
+  max_clamp_force_kN: 1000.0
+  applied_as: annotation_only
+
+stated_limitations:
+  - "sample geometry, not a production part"
+  - "material is PP Generic as a PLACEHOLDER"
+  - "no runner system in the AI model, so any hot runner is absent rather than approximated"
+  - "AI solver under-predicts absolute pressure on multi-gate parts (~0.3x on 8 gates)"

simcon_toolkit/_kit/templates/process-window/doe_spec.schema.md

@@ -0,0 +1,249 @@
+# `doe_spec.yaml` — schema
+
+No schema was supplied, so this is ours. Designed against one question: **can the process
+engineer in Arbeitsvorbereitung take this file to the machine tomorrow morning, and can an
+auditor later reconstruct why every number in it is what it is?**
+
+Three rules shaped it:
+
+1. **The answer comes first.** `centre_point` and `factors` are at the top, because that is
+   what the engineer actually needs: which parameters to vary, where to start, how wide. The
+   provenance lives below and is for the auditor, not the operator.
+2. **Every bound carries its basis.** No number appears without `*_basis` saying where it came
+   from — material card, derived, measured, or judgement. A bound whose basis is "judgement"
+   is allowed; a bound with no basis is not.
+3. **Absolute values are quarantined.** Any field whose value depends on the solver's absolute
+   pressure scale sits under a key marked `absolute: true` and carries `caveats`. The
+   guardrail lint (`process_window/guardrails.py`) walks this file and fails if an absolute pressure
+   appears inside `acceptance_criteria`.
+
+Temperatures are emitted in **both** °C and K. The engineer works in °C, the API works in K,
+and the whole project's worst failure mode is a silent confusion between them — so the file
+states both rather than making a reader convert.
+
+---
+
+## Structure
+
+```yaml
+schema: simcon.doe_spec/1
+generated_at: 2026-08-04T14:22:07+02:00
+generated_by: "frontloaded-doe POC, commit <sha>"
+status: draft | confirmed          # confirmed only after G4 has run
+
+# ---------------------------------------------------------------- the answer
+centre_point:
+  definition: chebyshev_centre_shrunk    # deepest interior point of the green region,
+                                         # shrunk inward by the safety margin.
+                                         # NOT the survivor mean, NOT the default settings.
+  melt:  {value_C: 245.0, value_K: 518.15, basis: derived}
+  wall:  {value_C: 40.0,  value_K: 313.15, basis: derived}
+  flow:  {value_cm3_s: 9.4, basis: derived}
+  safety_margin:                         # in VARIABLE space, not KPI space
+    melt_C: 6.2
+    wall_C: 3.1
+    flow_cm3_s: 0.7
+    basis: >
+      KPI uncertainty band divided by the local gradient of that KPI from the G2
+      surrogate. Band = derived noise floor (+ AI-to-numerical disagreement once G4
+      has run).
+    band_source: {kpi: p80, band: 1.8, unit: bar, floor_run_ids: [...]}
+
+factors:                                 # what to vary, ranked by effect share
+  - name: melt_temperature
+    unit_engineer: degC
+    unit_api: K
+    role: control                        # control | inert | readout | uncertainty
+    centre_C: 245.0
+    low_C: 232.0
+    high_C: 258.0
+    bounds_basis: derived                # from the green region, inset by the margin
+    effect_share: 0.54                   # normalised, per KPI below
+    effect_share_per_kpi: {p80: 0.61, weld_front_temp: 0.88, hotspot: 0.42}
+    rank: 1
+    above_noise_floor: true
+
+  - name: injection_rate
+    unit_engineer: cm3_s
+    role: control
+    centre_cm3_s: 9.4
+    low_cm3_s: 7.1
+    high_cm3_s: 11.8
+    bounds_basis: derived
+    effect_share: 0.39
+    rank: 2
+    above_noise_floor: true
+
+fixed_factors:                           # held, with the reason it is held
+  - name: mould_wall_temperature
+    value_C: 40.0
+    value_K: 313.15
+    reason: inert                        # inert | tool_property | out_of_scope | judgement
+    detail: >
+      Entire effect across the card window sits below the derived floor for every KPI.
+      Declared inert and fixed, not ranked low (guardrail 2).
+    floor_comparison: {kpi: p80, effect: 0.9, floor: 1.8, unit: bar}
+
+  - name: htc
+    value_W_m2K: 1000.0
+    reason: out_of_scope
+    detail: "Melt-to-mould contact property, not a machine setting. Not swept (user directive)."
+
+  - name: gate_positions_mm
+    value: [[...]]
+    reason: tool_property
+    detail: "Gate layout is tool design, not a machine parameter. Fixed across the DOE."
+
+readouts:                                # free axes, not swept inputs
+  - name: switchover_point
+    unit: phi                            # injected-volume fraction
+    values: [0.90, 0.95, 0.98, 0.99]
+    method: >
+      Field state read at fill fraction phi from runs already paid for. This is the state
+      AT switchover, not the effect OF switching there — the effect is in packing and is
+      swept in numerical_confirmation below.
+    caveats: [incompressible_melt_phi]
+
+# ---------------------------------------------------------------- what was ruled out
+excluded_regions:                        # "which 90%", and specifically why each
+  - id: X1
+    bounds: {melt_C: [220.0, 231.0]}
+    reason: no_flow_margin
+    detail: "Melt within <8 K of the card's no-flow temperature at the last-filled region."
+    kpi: no_flow_margin
+    evidence_run_ids: [...]
+    absolute: false
+  - id: X2
+    bounds: {flow_cm3_s: [13.1, 13.5], melt_C: [220.0, 236.0]}
+    reason: hotspot_rank
+    detail: "Thermal heterogeneity in the worst decile across the sweep."
+    kpi: hotspot
+    evidence_run_ids: [...]
+    absolute: false
+
+# ---------------------------------------------------------------- how it was decided
+acceptance_criteria:                     # MUST be rank / ratio / comparison only
+  - name: pressure_ordering
+    kind: rank
+    expression: "p80_rank <= 0.70"       # keep the best 70% by rank
+    kpi: p80
+    absolute: false
+    note: "Ordering only. p80 never compared to a threshold in bar (guardrail 1)."
+  - name: no_flow_guard
+    kind: ratio
+    expression: "(T_min_at_front - no_flow_temp) / (melt_C - no_flow_temp) >= 0.15"
+    kpi: no_flow_margin
+    absolute: false
+
+noise_floor:                             # derived here, never imported
+  method: epsilon_input_micro_experiment
+  mechanism: >
+    Solver is deterministic, so this is float16 storage quantization plus model
+    conditioning — not run-to-run scatter. Replicates carry zero information.
+  per_kpi:
+    p80:              {floor: 1.8, unit: bar, n_runs: 16}
+    weld_front_temp:  {floor: 0.6, unit: K,   n_runs: 16}
+    hotspot:          {floor: 0.02, unit: "-", n_runs: 16}
+
+feasibility_gate:
+  primary: no_flow_margin                # physics-based freeze-off guard
+  fill_completeness:
+    used_as_gate: false | true
+    residual_unfilled_at_best_point: 0.0
+    flow_dependence: none | present
+    detail: >
+      Fill completeness is used as a gate only if the residual unfilled fraction at the
+      best point is ~0 and shows no flow-rate dependence. A flow-dependent residual is a
+      known model artifact, not physics, and must not drive exclusion.
+
+# ---------------------------------------------------------------- the confirmation set
+numerical_confirmation:
+  solver: cadmould_numerical
+  mesh: same_as_ai                       # same .cfex — apples to apples
+  points:
+    - id: C0
+      role: centre                       # centre | face | probe
+      melt_C: 245.0
+      wall_C: 40.0
+      flow_cm3_s: 9.4
+      switchover_phi: 0.97
+      holding_pressure_bar: 420.0
+      holding_time_s: 4.5
+      cooling_time_s: 12.0
+      pack_cool_basis: sdk_suggestion
+      rm1: "cache/runs/<part-key>/G4_confirmation/C0.rm1"
+      rm1_validated: true                # Rm1Writer -> Rm1Reader round trip, field-checked
+      submit: {tier: 1, endpoint: "POST /simulations"}
+      status: prepared | submitted | done
+  rule: >
+    Where a numerical result disagrees with the AI-solver ordering, step the bounds
+    INWARD, never outward.
+
+# ---------------------------------------------------------------- provenance / audit
+provenance:
+  part: {name: clip_frame, geometry_id: ..., cfex_sha256: ..., nodes: 6201,
+         volume_cm3: ..., max_wall_mm: ...}
+  material: {catalogue_name: "PP Generic", material_id: ..., version_id: ...,
+             plb_sha256: ..., no_flow_temp_C: ...,
+             window: {melt_C: [.., ..], mold_C: [.., ..]}}
+  machine_limits:
+    max_injection_pressure_bar: 1500.0
+    max_clamp_force_kN: 1000.0
+    applied_as: annotation_only          # a constraint, never a screening criterion
+    absolute: true
+    caveats: [multi_gate_pressure_underprediction, cavities_1_of_32, no_runner_system]
+  wide_box:
+    melt_C: {low: .., high: .., basis: material_card}
+    mold_C: {low: .., high: .., basis: material_card}
+    flow_cm3_s: {low: .., high: .., basis: nominal_ratio, rel_span: 0.5}
+  ai_runs:
+    stages:
+      - {stage: G1, group_id: ..., design: sobol, seed: 0, n_planned: 1024, n_completed: ...}
+      - {stage: G3, group_id: ..., design: adaptive_boundary, n_completed: ...}
+    total_completed: ...
+    determinism_note: "Identical request returns identical result; no replicates run."
+  surrogate:
+    type: rbf | quadratic_rs
+    loo_error_per_kpi: {p80: 0.016, weld_front_temp: 0.008}
+  self_diagnosis:
+    verdict: green | warn | alarm
+    thresholds_basis: derived_from_anchor_spread
+    anchors: [...]
+    fake_real_source: ai_with_hidden_deviation | numerical_with_hidden_deviation
+    limitation: >
+      AI-vs-AI-with-hidden-deviation measures sensitivity to input misspecification,
+      not the AI-to-physics offset.
+
+guardrail_report:
+  absolute_pressure_in_criteria: pass    # lint fails the run otherwise
+  noise_floor_derived_not_imported: pass
+  caveats_attached_to_absolute_claims: pass
+
+caveats:                                 # auto-attached to absolute-valued claims
+  cavities_1_of_32: "1 of 32 cavities modelled, single gate."
+  no_runner_system: "No runner system in the model; the hot runner is absent, not approximated."
+  no_process_description: "Almost no description of the real process beyond the material."
+  multi_gate_pressure_underprediction: >
+    AI solver under-predicts absolute pressure on multi-gate parts (~0.3x on an 8-gate
+    part). Every criterion is therefore a rank, ratio or comparison.
+  weld_temp_circularity: >
+    Weld-front temperature ordered points well (Spearman ~0.95, roughly constant offset)
+    but was tested against a melt perturbation while melt drives that KPI roughly 1:1.
+  incompressible_melt_phi: >
+    The phi axis equates injected with filled volume. Sub-percent during fill, worst as
+    phi -> 1, which is where switchover lives.
+  fill_race_not_transferable: >
+    Fill-race metrics measured not to transfer (Spearman 0.10-0.23). Computed as an
+    anomaly detector only, never as a screening criterion.
+```
+
+## Field conventions
+
+| Convention | Rule |
+|---|---|
+| `*_C` / `*_K` | Temperatures are always emitted in both. |
+| `*_basis` | `material_card` \| `derived` \| `measured` \| `sdk_suggestion` \| `judgement` \| `user_directive`. Required next to every bound. |
+| `absolute: true` | Marks a value that depends on the solver's absolute pressure scale. Requires non-empty `caveats`. Forbidden inside `acceptance_criteria`. |
+| `role` | `control` (swept, kept) \| `inert` (below floor, fixed) \| `readout` (free axis) \| `uncertainty` (robustness axis). |
+| `unset` | Explicit, not omitted — so the dossier can state that a limit was unavailable rather than silently skipping it. |
+| run ids | Every exclusion and every threshold cites the run ids it rests on. |

simcon_toolkit/_kit/templates/process-window/main.py

@@ -0,0 +1,82 @@
+"""Find the process window for a part, before you book machine time.
+
+One campaign, run a step at a time:
+
+    python main.py --list                      what the steps are, in order
+    python main.py inspect                     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. Judgement belongs between them, which is why there is no command that
+runs the whole campaign: a sweep costs thousands of solver runs, and you decide whether
+the result is worth refining before paying for the next stage.
+
+Everything after the step name belongs to that step — `python main.py refine --help`
+prints the refinement step's own options. The steps do not share a flag set on purpose:
+`--grid` means one thing to `refine` and another to `economics`, and folding them into
+one option here would silently change what a campaign ran.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+# Step name -> the module that implements it, in the order a campaign runs them.
+# The name is the verb a reader types; the module keeps the name the campaign uses
+# for the stage internally.
+STEPS: dict[str, tuple[str, str]] = {
+    "inspect": ("inspect_part", "G0 — geometry, wall, L/t. Free; run it first"),
+    "epsilon-floor": ("run_epsilon_floor", "G1a — this part's resolution floor"),
+    "probe": ("probe_proxy", "G1b — does the feasibility gate discriminate?"),
+    "sweep": ("run_sweep", "G1 — space-filling sweep, resumable"),
+    "screen": ("run_screening", "G2 — rank the variables, map what is excluded"),
+    "refine": ("run_refine", "G3 — adaptive boundary refinement + centre point"),
+    "confirm": ("run_confirm", "G4 — numerical confirmation decks"),
+    "feedback": ("run_feedback", "G6 — hidden-deviation self-diagnosis"),
+    "emit": ("emit", "G5 — write doe_spec.yaml and dossier.md"),
+    "economics": ("economics", "cycle time vs robustness"),
+}
+
+
+def print_steps() -> None:
+    width = max(len(name) for name in STEPS)
+    print("Campaign steps, in the order they run:\n")
+    for name, (_module, blurb) in STEPS.items():
+        print(f"  {name:<{width}}  {blurb}")
+    print("\nRun one with:  python main.py <step> [its own options]")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv or argv[0] in {"-h", "--help"}:
+        print(__doc__)
+        print_steps()
+        return 0
+    if argv[0] in {"-l", "--list"}:
+        print_steps()
+        return 0
+
+    step, rest = argv[0], argv[1:]
+    if step not in STEPS:
+        print(f"unknown step: {step}", file=sys.stderr)
+        print(f"expected one of: {', '.join(STEPS)}", file=sys.stderr)
+        return 2
+
+    module_name, _blurb = STEPS[step]
+    # Imported here rather than at module level, so listing the steps and reading this
+    # help never needs the licensed cadmould wheel. Every step reaches it — one directly,
+    # the rest through the module that builds the campaign — so an eager command table
+    # would make `--list` impossible without a licence.
+    module = importlib.import_module(f"process_window.{module_name}")
+
+    # Re-present the command line as though the step had been run directly: each step
+    # owns its own parser, and this is what keeps `main.py refine --grid 41` identical
+    # to what that step has always accepted.
+    sys.argv = [f"main.py {step}", *rest]
+    return int(module.main() or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates/process-window/process_window/__init__.py

@@ -0,0 +1,5 @@
+"""The process-window campaign: a design-of-experiments study run before a machine trial.
+
+Each module under here is one stage of the campaign, or a library those stages share.
+Run them through `main.py` at the project root rather than directly.
+"""