diff --git a/src/sim_plugin_comsol/_skills/comsol/SKILL.md b/src/sim_plugin_comsol/_skills/comsol/SKILL.md index 6dea64c..05eb3c7 100644 --- a/src/sim_plugin_comsol/_skills/comsol/SKILL.md +++ b/src/sim_plugin_comsol/_skills/comsol/SKILL.md @@ -29,22 +29,34 @@ Choose the control path first: **Routing rule:** an already-open ordinary COMSOL Desktop is **not** a reason to choose Java Shell. For any serious model build, reproduction, solve, sweep, checkpointed artifact, or task where Codex needs -structured verification, start or attach through the sim runtime in -`visual_mode=shared-desktop`. The existing standalone Desktop may stay open for -screenshots or reference, but it is not the live server-client model unless -`session.health` confirms `effective_ui_mode="shared-desktop"`, -`ui_capabilities.model_builder_live=true`, and a valid `active_model_tag`. +structured verification, start or attach through the sim runtime. The existing +standalone Desktop may stay open for screenshots or reference, but it is not +the live server-client model unless `session.health` confirms a structured +server-backed binding and a valid `active_model_tag`. Batch (`comsolcompile` + `comsolbatch`) is a valid third path — not a fallback — for settled, deterministic one-shot work that needs no live introspection; see the decision table and "Choosing between live session and batch" below. +If the user already has a `comsolmphserver` plus `comsol.exe mphclient -host +... -port ...` Desktop open with the target model loaded, first attach the +agent without launching another Desktop client: + +```powershell +uv run sim connect --solver comsol --ui-mode no_gui ` + --driver-option attach_only=true ` + --driver-option port= +``` + +Then verify model tags and binding through `session.health`/`ModelUtil.tags()`. +Use `visual_mode=shared-desktop` only when the plugin should launch or manage +the visible Desktop client. If the user explicitly refuses server-client mode, pause and explain that the Java Shell fallback is deprecated and not accepted evidence for serious automation. | Path | Use it for | Avoid it for | |---|---|---| -| sim runtime / JPype | Stateful/incremental model building, live introspection (discovering tags and property names before editing), debugging, checkpointing across a long build, and reliable live GUI co-editing with `visual_mode=shared-desktop`. | Settled deterministic recipes that need no live introspection — batch is lighter-weight and more reproducible there (see the batch row). Also when the user explicitly refuses a server-backed/shared Desktop session. | +| sim runtime / JPype | Stateful/incremental model building, live introspection (discovering tags and property names before editing), debugging, checkpointing across a long build, no-GUI attach to a user-owned existing `comsolmphserver`, and reliable live GUI co-editing when the plugin owns `visual_mode=shared-desktop`. | Settled deterministic recipes that need no live introspection — batch is lighter-weight and more reproducible there (see the batch row). Also when the user explicitly refuses a server-backed/shared Desktop session. | | `comsolcompile` + `comsolbatch` | One-shot Java execution against COMSOL's own batch executables — write a `.java` with `public static Model run()`, compile with `comsolcompile.exe`, run with `comsolbatch.exe`; or run a saved model directly with `comsolbatch.exe -inputfile in.mph -outputfile out.mph`. Settled/known-good deterministic recipes (build→solve→extract KPIs, or run-saved-model→get-outputs); reproducibility and isolation (fresh process per run, no session-state drift — regression runs, CI, deterministic artifacts); fan-out over many independent cases; minimal lifecycle (no `comsolmphserver` to start/monitor/leak; works from files on disk even when `sim serve` is down); unattended runs with no human watching and no GUI co-editing. | Stateful/incremental model building, debugging, or anything needing introspection of intermediate live model state (e.g. discovering property names before editing — see the hard rule below); GUI co-editing / shared-desktop; checkpointing across a long exploratory build. Use a live session for those. | | saved `.mph` inspection | Offline summaries, archive diffs, and artifact review without starting COMSOL. | Mutating live model state. | @@ -376,16 +388,20 @@ assignment. - **Live sim runtime** for stateful/incremental building, live introspection, debugging, or GUI collaboration. Use `uv run sim connect --solver comsol --ui-mode gui --driver-option visual_mode=shared-desktop` when the user - wants real-time Model Builder visibility and the agent needs structured - `uv run sim inspect`/JPype state; use plain `uv run sim connect --solver - comsol` for no-GUI/server execution and driver-managed artifacts. + wants plugin-managed real-time Model Builder visibility and the agent + needs structured `uv run sim inspect`/JPype state; use plain + `uv run sim connect --solver comsol` for no-GUI/server execution and + driver-managed artifacts. - **Batch** (`comsolcompile` + `comsolbatch`, or `comsolbatch -inputfile`) for a settled, deterministic one-shot recipe that needs no live introspection — see "Choosing between live session and batch" above. - If the user says COMSOL is already open, treat that as visual context only. - Do not infer that Java Shell is preferred; ask whether to preserve unsaved - standalone Desktop edits only if needed, then proceed with - `shared-desktop` for serious work. + Do not infer that Java Shell is preferred. If it is already a + server-backed `mphclient` connected to `comsolmphserver`, use no-GUI + `attach_only=true` for the agent/API client and do not launch a second + Desktop. If it is an ordinary standalone Desktop, ask whether to preserve + unsaved edits only if needed, then use a structured path (`shared-desktop`, + no-GUI server, batch, or saved `.mph` inspection) for serious work. 2. For sim runtime, run `uv run sim check comsol`, connect if needed, and read `session.versions` plus `uv run sim inspect session.health`. 3. Establish or verify model identity, working folder, and checkpoint target. @@ -435,8 +451,13 @@ too GUI-fragile and reports submission, not verified execution. Keep it out of normal agent workflows, reproduction work, long model builders, solves, screenshots-as-proof, and validation. If a legacy troubleshooting task names `sim-comsol-attach` explicitly, state that it is deprecated, keep the action -read-only or very small, and do not treat it as acceptance evidence. Prefer -server-client `shared-desktop` instead. +read-only or very small, and do not treat it as acceptance evidence. Do not +recommend GUI automation plus Java Shell as a way to operate COMSOL: it depends +on focus, language/layout, visible shell state, dialogs, and clipboard/text +submission behavior. Prefer a structured server-backed path instead: no-GUI +attach for a user-owned existing server session, plugin-owned +`shared-desktop` for live Model Builder collaboration, or `comsolbatch` for +settled file-based recipes. Shared-desktop gotcha for COMSOL 6.4: launching `comsol.exe mphclient -host localhost -port ` does attach a full @@ -471,7 +492,23 @@ instead of mixing sim and ad hoc JPype scripts. The user or agent starts & "C:\Program Files\COMSOL\COMSOL64\Multiphysics\bin\win64\comsolmphserver.exe" -port 2036 -multi on -login auto -silent ``` -Then connect through sim with explicit attach-only ownership: +Then connect through sim with explicit attach-only ownership. If the user has +already opened a server-backed Desktop with: + +```powershell +& "C:\Program Files\COMSOL\COMSOL64\Multiphysics\bin\win64\comsol.exe" mphclient -host localhost -port 2036 +``` + +attach the agent/API client without launching another Desktop: + +```powershell +uv run sim connect --solver comsol --ui-mode no_gui ` + --driver-option attach_only=true ` + --driver-option port=2036 +``` + +Use plugin-owned `shared-desktop` only when the agent should launch or manage +the visible Desktop client: ```powershell uv run sim connect --solver comsol --ui-mode gui ` diff --git a/src/sim_plugin_comsol/_skills/comsol/base/reference/java_api_patterns.md b/src/sim_plugin_comsol/_skills/comsol/base/reference/java_api_patterns.md index ed9f5fa..01ed698 100644 --- a/src/sim_plugin_comsol/_skills/comsol/base/reference/java_api_patterns.md +++ b/src/sim_plugin_comsol/_skills/comsol/base/reference/java_api_patterns.md @@ -3,6 +3,10 @@ This is not a COMSOL API reference. It is a small set of stable probing patterns for discovering the live model shape before modifying it. +These snippets are for the supported server-backed Java API path: the sim +runtime/JPype connection to `comsolmphserver`, or equivalent structured COMSOL +Java API execution. Do not translate them to Java Shell or GUI automation. + ## Rules - Ask for `tags()` before accessing a child by tag. @@ -105,6 +109,15 @@ for sel_tag in out["selections"]: _result = out ``` +### Creating Box selections + +When creating Box selections through JPype, set the entity dimension before +range properties and prefer string scalar values for dimension-like properties. +For example, boundary selections should use `sel.set("entitydim", "2")` before +`xmin`/`xmax`/`zmin`/`zmax` ranges. This avoids ambiguous Java overloads and +makes `sel.entities()` return the expected boundary ids instead of an empty +selection. + ## Before setting a property Use this pattern before writing to an unfamiliar feature: @@ -127,3 +140,11 @@ else: Do not record the resulting property list as a global truth. It is only confirmed for this COMSOL version, module set, physics interface, and feature type. + +## Store provenance outside parameter values + +COMSOL global parameters are parsed as expressions, not arbitrary strings. A +value like `"arXiv:2510.11461"` is rejected even though it looks useful as a +paper identifier. Put human-readable provenance in the model label, comments, +or parameter descriptions; keep parameter values numeric expressions with +optional units. diff --git a/uv.lock b/uv.lock index 6958686..e8af3b5 100644 --- a/uv.lock +++ b/uv.lock @@ -912,7 +912,7 @@ wheels = [ [[package]] name = "sim-plugin-comsol" -version = "0.1.12" +version = "0.1.14" source = { editable = "." } dependencies = [ { name = "mph" },