simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/run-one-simulation/README.md

@@ -0,0 +1,133 @@
+# Run one simulation
+
+The shortest path from a part file to a cloud result, using the `cadmould.cloud` SDK.
+One script runs the whole loop:
+
+**mesh locally → upload geometry → pick material → run AI filling → read peak pressure.**
+
+The SDK handles the cloud login for you — there is no token to manage. It just has to run
+inside an active licence session, and `main.py` wraps the whole script in one.
+
+## Install
+
+<!-- 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 script 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 -->
+
+## Run it
+
+```bash
+python main.py                           # uses the bundled sample part
+python main.py --part path/to/part.stl   # your own geometry
+```
+
+The first cloud call opens a browser once so you can sign in. Output lands in `build/`:
+the meshed `.cfex` and the result `.h5`. The script prints the peak cavity pressure and the
+id of the simulation it ran.
+
+## View the result
+
+Open <https://cadmould.simcon.ai> and find the simulation by the id the run printed. There
+is nothing to install — the viewer is part of the platform.
+
+*(The script cannot give you a direct link: the platform returns one, but the SDK does not
+yet expose it. That is a known gap on our side, not something you have configured wrongly.)*
+
+## Work with the numbers
+
+The downloaded `.h5` is written **complete**. Cloud results carry the field data only, so
+`main.py` adds back an `/input` group holding the gate position and the process settings the
+run was given — meaning the file still tells you what it was asked for, months later.
+
+Read it with the `cadmould_results` package that came with this project:
+
+```python
+from cadmould_results import PRESSURE, PredictionResult
+
+with PredictionResult("build/<the file>.h5") as res:
+    snap = res.snapshot(step=res.n_timesteps - 1)        # every field at the last step
+    at_gate = res.node_history(PRESSURE, node=res.gate_node)   # pressure at the gate over time
+```
+
+## What it shows
+
+```python
+import cadmould
+from cadmould import cloud
+
+with cadmould.Session.user_based():                        # ONE licence session…
+    cloud.set_base_url("https://api.simcon.ai", cloud.OidcEnvironment.Production)   # …gated, so inside it
+    geometry_id = cloud.geometry.upload_geometry("part.cfex")                        # upload once
+    mat = cloud.material.get_materials("PP Generic")[0]                              # find a material
+    sim = cloud.simulation.create_filling_simulation(                                # run (AI = synchronous)
+        geometry_id=geometry_id, material_id=mat.material_id, ...)
+    sim.download("build/")                                                           # fetch the result .h5
+```
+
+**The one rule worth remembering:** `cadmould.cloud` needs an active licence session carrying
+the API entitlement, and `set_base_url` is gated too. Use a *single* `Session.user_based()`
+for both the meshing and the cloud calls. Do not nest sessions — an inner one releases the
+licence when it exits, and every later cloud call then fails.
+
+## The sample part
+
+`sample/` holds one geometry so the script runs the moment you generate the project. It is
+ours, not yours. Replace the file with your own and `python main.py` keeps working; delete
+the folder and you must pass a path every time, which is a perfectly good way to work.
+
+## Changing the cloud address
+
+The script targets production, and that is the cloud you have. SIMCON engineers can point it
+elsewhere without editing the source:
+
+```bash
+CADMOULD_API_BASE_URL=https://api.dev.simcon.ai python main.py
+```
+
+The sign-in configuration and the web app address both travel with it, so a run and the page
+you look at it on can never disagree. An address the script does not recognise is refused,
+with the known ones named.
+
+## Prefer your own client?
+
+`cadmould.cloud` is the convenient default, but the platform is a plain REST API and you are
+free to build your own client in any language — see <https://api.simcon.ai/scalar>.

simcon_toolkit/_kit/templates/run-one-simulation/main.py

@@ -0,0 +1,216 @@
+"""Run one AI filling simulation on the cloud — via the cadmould.cloud SDK.
+
+The minimal end-to-end on the **recommended default** cloud path: mesh a part locally,
+upload it, pick a material, run an AI filling simulation, and read the peak pressure from
+the result. Everything runs inside one `cadmould.Session.user_based()`: `cadmould.cloud`
+requires an active licence session (with the API entitlement). `set_base_url` selects the
+OIDC config and the SDK opens a browser once to sign in.
+
+Run it from this folder:
+
+    python main.py                           # uses sample/simple_plate.stl
+    python main.py --part path/to/part.stl   # your own geometry
+
+The downloaded result is written viewer-ready (an `/input` group is added back), so the
+arrays read back together with the process settings that produced them — the layout
+`cadmould_results.ProcessInputs` reads.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import sys
+from pathlib import Path
+
+import h5py
+import numpy as np
+
+import cadmould
+from cadmould import cloud
+from cadmould_geometry import stl
+
+HERE = Path(__file__).resolve().parent
+DEFAULT_PART = HERE / "sample" / "simple_plate.stl"
+BUILD = HERE / "build"
+
+# The clouds that exist. Production is the only one a customer has; the override is for
+# SIMCON engineers. An address carries its own sign-in configuration AND its own web app,
+# so they are kept in one row: naming an address can never pair a run with the wrong
+# tenant or send you to a viewer that does not hold the result. An unrecognised address
+# is refused rather than guessed at.
+CLOUDS = {
+    "https://api.simcon.ai": (cloud.OidcEnvironment.Production, "https://cadmould.simcon.ai"),
+    "https://api.dev.simcon.ai": (cloud.OidcEnvironment.Development, "https://cadmould.dev.simcon.ai"),
+}
+DEFAULT_API = "https://api.simcon.ai"
+
+MATERIAL = "PP Generic"
+FLOW_CM3_S = 45.0
+
+
+def cloud_target() -> tuple[str, cloud.OidcEnvironment, str]:
+    """The API address, its sign-in configuration and its web app — always from one row."""
+    raw = os.environ.get("CADMOULD_API_BASE_URL", DEFAULT_API).strip().rstrip("/")
+    # The SDK wants the API root. The REST templates use CLOUD_BASE_URL, which includes the
+    # /api/v1 prefix, so accept that spelling too rather than reading it as a fourth cloud.
+    base = raw.removesuffix("/api/v1")
+    if base not in CLOUDS:
+        raise ValueError(f"CADMOULD_API_BASE_URL={raw!r} is not a Cadmould cloud. Known: {', '.join(sorted(CLOUDS))}")
+    oidc, web_app = CLOUDS[base]
+    return base, oidc, web_app
+
+
+def _mesh_classes():
+    """Resolve the meshing classes from whichever namespace the wheel exposes."""
+    mesh_mod = getattr(cadmould, "mesh", None)
+    io_mod = getattr(mesh_mod, "io", None) if mesh_mod else None
+    return (
+        getattr(mesh_mod, "Mesh", None) or cadmould.domain.Mesh,
+        getattr(mesh_mod, "Mesher", None) or cadmould.tools.Mesher,
+        getattr(io_mod, "CfexWriter", None) or cadmould.io.CfexWriter,
+    )
+
+
+def write_input_group(h5_path, gate_mm, flow_cm3_s, melt_c, wall_c, fill_time_s) -> None:
+    """Make a cloud result self-contained by writing back the submitted process settings.
+
+    Cloud results carry the primary fields only — no `/input` group — so the gate positions and
+    process settings that produced them are lost the moment the file is downloaded. Write them
+    back in the layout `cadmould_results.ProcessInputs` expects (gate `/input/gate_locations` +
+    process attrs), so anything reading the result later can see what was asked for.
+    """
+    gl_dt = np.dtype([("x", "<f8"), ("y", "<f8"), ("z", "<f8"), ("kno", "<i4")])
+    with h5py.File(h5_path, "a") as f:
+        if "input" in f:
+            return
+        g = f.create_group("input")
+        g.attrs["filling_time"] = float(fill_time_s)
+        g.attrs["flowrate"] = float(flow_cm3_s)
+        g.attrs["melt_temperature"] = float(melt_c)  # °C (ProcessInputs reads °C)
+        g.attrs["wall_temperature"] = float(wall_c)  # °C
+        gl = np.zeros(len(gate_mm), dtype=gl_dt)
+        for i, (x, y, z) in enumerate(gate_mm):
+            gl["x"][i], gl["y"][i], gl["z"][i], gl["kno"][i] = x, y, z, -1
+        g.create_dataset("gate_locations", data=gl)
+
+
+def peak_pressure_bar(h5_path: str) -> float:
+    """Peak per-node Pressure over all steps, in bar (honours the stored `unit`)."""
+    pmax, unit = 0.0, ""
+    with h5py.File(h5_path, "r") as f:
+        for k in f:
+            if k.startswith("TimeStep_") and "Pressure" in f[k]:
+                ds = f[k]["Pressure"]
+                unit = unit or str(ds.attrs.get("unit", ""))
+                pr = np.asarray(ds[()], dtype=np.float64)
+                if np.isfinite(pr).any():
+                    pmax = max(pmax, float(np.nanmax(pr)))
+    return pmax / 1e5 if unit.strip().lower() == "pa" else pmax
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run one AI filling simulation on the Cadmould cloud.")
+    # Named rather than positional, and the same spelling in every template: these
+    # workflows will grow inputs, and a flag keeps that from reordering anyone's command.
+    parser.add_argument(
+        "--part",
+        type=Path,
+        default=DEFAULT_PART,
+        help="STL geometry to run. Defaults to the bundled sample/simple_plate.stl.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Windows consoles default to cp1252 and choke on the non-ASCII glyphs below
+    # (…, ≈, →, °, ³) — switch stdout to UTF-8 so the final print can't crash a finished run.
+    with contextlib.suppress(Exception):
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+
+    args = parse_args(argv)
+    part = args.part
+    if not part.is_file():
+        print(f"geometry not found: {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
+
+    try:
+        base_url, oidc, web_app = cloud_target()
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    BUILD.mkdir(exist_ok=True)
+    Mesh, Mesher, CfexWriter = _mesh_classes()
+
+    # cadmould.cloud needs an ACTIVE licence session carrying the API entitlement
+    # (LICENCE_API). Run meshing AND every cloud call — including set_base_url, which is
+    # gated too — inside ONE session. Don't nest or close it early: an inner session's
+    # exit releases the licence, leaving later cloud calls unlicensed.
+    with cadmould.Session.user_based():
+        # 1. Mesh the part locally and let the SDK suggest a gate (a real mesh node).
+        print("1. meshing the part (local cadmould)…")
+        pts, faces = stl.read_stl(part)
+        volume_cm3 = stl.volume_mm3(pts, faces) / 1000.0
+        meshed = Mesher(Mesh(pts.ravel(), faces.ravel())).with_surface_triangulation().with_thickness_and_w2w().build()
+        gate = cadmould.tools.suggest_gates(meshed).points[0]
+        gate_mm = [[float(gate.x), float(gate.y), float(gate.z)]]
+        cfex = BUILD / "part.cfex"
+        CfexWriter().save(meshed, str(cfex))
+        print(f"   {meshed.node_count()} nodes; suggested gate {[round(v, 1) for v in gate_mm[0]]}")
+
+        # 2. Point the SDK at the cloud (set_base_url is gated → must be inside the session).
+        print("2. connecting to the cloud (cadmould.cloud)…")
+        cloud.set_base_url(base_url, oidc)
+
+        # 3. Upload the geometry once → geometry_id.
+        geometry_id = cloud.geometry.upload_geometry(str(cfex), description="run-one-simulation")
+        print(f"   geometry_id = {geometry_id}")
+
+        # 4. Resolve the material and its recommended temperatures.
+        mats = cloud.material.get_materials(MATERIAL)
+        mat = next((m for m in mats if m.name.lower() == MATERIAL.lower()), mats[0])
+        ver = cloud.material.get_material_version(mat.versions[0].material_version_id)
+        print(
+            f"   material {mat.name}: melt {ver.suggested_mass_temp_K - 273.15:.0f}°C, "
+            f"mould {ver.suggested_wall_temp_K - 273.15:.0f}°C"
+        )
+
+        # 5. Run an AI filling simulation (synchronous — completes on return).
+        print("3. running the AI filling simulation…")
+        sim = cloud.simulation.create_filling_simulation(
+            geometry_id=geometry_id,
+            material_id=mat.material_id,
+            melt_temperature_K=ver.suggested_mass_temp_K,
+            wall_temperature_K=ver.suggested_wall_temp_K,
+            flow_rate_cm3_s=FLOW_CM3_S,
+            gate_positions_mm=gate_mm,
+            estimated_filling_time_s=volume_cm3 / FLOW_CM3_S,
+        )
+        simulation_id = sim.id
+        print(f"   simulation {simulation_id} — status {sim.status}")
+
+        # 6. Download the result (still inside the session).
+        h5_path = sim.download(str(BUILD))
+
+    # Reading + augmenting the result needs no licence — do it after the session is released.
+    # Write back the submitted inputs so the result carries what it was run with.
+    write_input_group(
+        h5_path,
+        gate_mm,
+        FLOW_CM3_S,
+        ver.suggested_mass_temp_K - 273.15,
+        ver.suggested_wall_temp_K - 273.15,
+        volume_cm3 / FLOW_CM3_S,
+    )
+    print(f"4. result → {h5_path}\n   peak cavity pressure ≈ {peak_pressure_bar(h5_path):.1f} bar")
+    # The SDK exposes no viewer link, so name the id and let the reader open it themselves.
+    print(f"   view it: open {web_app} and find simulation {simulation_id}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates.toml

@@ -0,0 +1,83 @@
+# What each template is, stated once.
+#
+# The filesystem is the truth about which templates exist; this file holds the
+# metadata a directory cannot carry. tests/test_repository_layout.py fails when the
+# two disagree in either direction, and when a value here names something absent.
+#
+# Every field is derived from the template's own code, not chosen:
+#   client   "sdk" when the workflow reaches the cloud through the licensed cadmould
+#            wheel, "rest" when it calls the platform API over HTTP itself. It records
+#            the cloud client only — a "rest" template may still use the wheel for
+#            meshing or for reading a licensed material file.
+#   needs    "licence" when any code path reaches the licensed cadmould wheel — the
+#            template's own, or a shared module it imports; "cloud" when it calls the
+#            platform. Descriptive, so a reader knows what a run requires. All four
+#            need both today: cadmould_geometry.mesh.prepare_geometry opens a licence
+#            session, so importing it is enough even where the template never says
+#            `import cadmould` itself.
+#   heavy    true when the template pulls the graphics stack. Nothing does any more:
+#            quoting was the last user and its ray-casting moved to trimesh.
+#   modules  the shared packages the generator copies into the project, each under its
+#            own name:
+#            those the code imports, plus any the template's own README tells the
+#            reader to use.
+#   package  the folder inside the template holding the workflow's code. Absent when
+#            the template is a single script at its root.
+#   sample   the file under assets/parts/ this template's generated sample/ receives.
+#            Two templates share a geometry, which is why it is a mapping here rather
+#            than a committed folder.
+#   category unused today; the hook for a future menu grouping. Present now because
+#            adding it later would mean touching every entry.
+
+[templates.run-one-simulation]
+title       = "Run one simulation"
+description = "Run one AI filling simulation via the cadmould.cloud SDK"
+category    = "quickstart"
+client      = "sdk"
+needs       = ["licence", "cloud"]
+heavy       = false
+# cadmould_results is not imported by the workflow; the template's README instructs the
+# reader to open the result with it, so a generated project without it is broken.
+modules     = ["cadmould_geometry", "cadmould_results"]
+sample      = "simple_plate.stl"
+
+[templates.gate-study]
+title       = "Gate study"
+description = "Drive a full gating decision, with its own REST client"
+category    = "study"
+client      = "rest"
+# The study drives the cloud over REST, but it meshes first: main.py imports
+# prepare_geometry, which opens a licence session.
+needs       = ["licence", "cloud"]
+heavy       = false
+modules     = ["cadmould_cloud", "cadmould_geometry", "cadmould_scoring"]
+# No `package`: the workflow is main.py plus one module at the template root. An inner
+# folder would become a package name in the customer's project, and two files do not
+# earn one.
+sample      = "simple_plate.stl"
+
+[templates.process-window]
+title       = "Process window"
+description = "A rigorous design-of-experiments campaign"
+category    = "study"
+client      = "rest"
+# The campaign talks to the cloud over REST, but four scripts use the wheel for work the
+# platform exposes no endpoint for: meshing, inspection, the numerical .rm1 path, and
+# reading a licensed .plb material card.
+needs       = ["licence", "cloud"]
+heavy       = false
+modules     = ["cadmould_cloud", "cadmould_geometry", "cadmould_scoring"]
+package     = "process_window"
+sample      = "simple_plate.stl"
+
+[templates.quoting]
+title       = "Quoting"
+description = "An agentic quoting flow with its own, self-improving context"
+category    = "business"
+client      = "rest"
+# Meshing opens a licence session before any cloud call.
+needs       = ["licence", "cloud"]
+heavy       = false
+modules     = ["cadmould_cloud", "cadmould_geometry", "cadmould_scoring"]
+package     = "quoting"
+sample      = "clip_frame.stl"

simcon_toolkit/choices.py

@@ -0,0 +1,11 @@
+"""The package managers a project can be set up for, read by both the CLI and the generator.
+
+Its own module, importing nothing, because `cli.py` must not import the manifest before it
+has checked the interpreter, and the generator must not import the CLI. One list, so the flag
+and the generator cannot disagree about what is accepted.
+"""
+
+from __future__ import annotations
+
+PACKAGE_MANAGERS = ("uv", "pip")
+DEFAULT_PACKAGE_MANAGER = "uv"