comsol-sim

# comsol-sim This file is the **COMSOL Multiphysics** agent workflow index. Its job is to help an agent choose and execute the most reliable real COMSOL control path for the task: saved `.mph` inspection, local COMSOL documentation, direct COMSOL executables, a server-backed Java API session, or the sim COMSOL runtime when that adds useful structure. This skill is self-contained for COMSOL work. Do not require a separate skill checkout or an external sim-cli skill. Use this file for COMSOL workflow routing, and load the plugin-bundled references below only when the task needs them. --- ## COMSOL-specific layered content Choose the control path from the task and the current COMSOL state. Identify whether you have a saved `.mph`, a standalone Desktop, an `mphclient` connected to `comsolmphserver`, an external `comsolmphserver`, or no running session. Then pick the smallest path that can produce real evidence. | Path | Use it for | Evidence to collect | |---|---|---| | saved `.mph` inspection | Offline summaries, archive diffs, parameters, physics tags, mesh/solution metadata, and artifact review without starting COMSOL. | `inspect_mph(path)`, `MphArchive`, or `mph_diff` output. | | local COMSOL docs | Unknown physics feature names, module capability, property names, examples, and API terms before writing code. | `sim-comsol-doc search` / `retrieve` hits from the installed COMSOL help tree. | | direct `comsolbatch -inputfile` | Running a saved model headlessly, stripping solutions with `-norun`, regression/CI/fan-out over `.mph` files, and one-shot saved-model output artifacts. | output `.mph`, `-batchlog`, shell exit status, and extracted KPIs/artifacts. | | `comsolcompile` + `comsolbatch` | Settled Java recipes that build, solve, and extract KPIs in a fresh COMSOL process. | compiled class, batch log/stdout KPI lines, output `.mph` or exported data. | | `comsolmphserver` / Java API | Stateful model exploration, live property/tag probing, incremental mutation, debugging, and API work where the agent needs to ask the live model questions. | model tags/properties, run/build results, saved checkpoints, and explicit model identity. | | sim runtime / shared Desktop | The same server-backed Java API work when the plugin's structured `inspect`/`exec`/checkpoint tools or managed visible Model Builder collaboration are useful. | `session.health`, `comsol.model.identity`, `last.result`, live binding checks, checkpoints. | If the user already has a `comsolmphserver` plus `comsol.exe mphclient -host ... -port ...` Desktop open with the target model loaded, 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=<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. For the `comsolcompile` path, Java code needs chain-style `model.X("tag").Y("tag2")...` calls. There is no public `Component`, `Geometry`, `HeatTransfer`, etc. type; writing `Component comp = ...` gets `cannot be resolved to a type` from `comsolcompile`. Read [`base/reference/java_batch_patterns.md`](base/reference/java_batch_patterns.md) before writing a batch `.java`. ### Choosing between live session and batch These are not either/or - they compose. The natural arc is **explore live -> solidify -> graduate to batch**: 1. **Explore live.** Use local docs, saved `.mph` inspection, or a server-backed Java API session to discover model shape, tags, properties, and module behavior. 2. **Solidify.** Once the workflow is settled and known-good, capture it as a batch `.java` file (`comsolcompile` + `comsolbatch`) or, for a saved model, a `comsolbatch -inputfile` run. 3. **Graduate to batch.** Run the captured recipe headless for reproducible/CI/fan-out execution — fresh process each run, no session-state drift, no `comsolmphserver` lifecycle, parallelizable across cases. Quick test: if you still need to *ask the live model questions*, stay in a session. If you are *executing a recipe you already trust*, run it as batch. For the sim runtime, use `uv run sim check comsol` when `sim-cli` is available, then `uv run sim connect --solver comsol`, then inspect `session.health`. Missing `sim-cli` is not evidence that COMSOL is missing: fall back to `COMSOL_ROOT`, `sim-comsol-doc where`, COMSOL launcher/default path probes, or the user-provided install path before reporting that COMSOL is not installed. When the user wants to watch the live Model Builder while the agent builds or solves, use: ```bash uv run sim connect --solver comsol --ui-mode gui --driver-option visual_mode=shared-desktop uv run sim inspect session.health ``` Confirm `ui_capabilities.model_builder_live: true`, `active_model_tag`, and `live_model_binding.ok: true` before treating the GUI as synchronized with agent edits. The returned `session.versions` payload tells you which COMSOL-specific subfolders to load. Require `version_source: active_runtime` before using release-specific notes; another COMSOL installation detected on the host is not evidence about this session: ```json "session.versions": { "solver_version": "6.4", "version_source": "active_runtime", "profile": "mph_1_2_comsol_6_4", "active_sdk_layer": null, // single SDK line (mph 1.x), no overlay "active_solver_layer": "6.4" // or "6.2" / "6.1" / "6.0" } ``` There is no `sdk/` overlay because all supported COMSOL versions pin a single `mph` line (1.2.x). Load the smallest reference needed for the chosen path: usually `base/` plus the active `solver/<slug>/` notes only when version specific behavior matters. ### `base/` — references to load when relevant | Path | What's there | |---|---| | `base/workflows/block_with_hole/` | Steady-state thermal of a heated block with a cylindrical hole. 6 numbered Python steps (`00_create_geometry.py` … `05_plot_temperature.py`). The smallest plugin-owned smoke/reference workflow for this driver. | | `base/workflows/model_review_loop.md` | Checkpoint loop for live/incremental geometry, materials, physics, mesh, study, and results work. | | `base/workflows/debug_failed_exec.md` | Failure and divergence triage: preserve the first causal error, inspect live state, separate singular/setup/mesh/nonlinear causes, then retry one hypothesis at a time. | | `base/reference/runtime_introspection.md` | Live-session inspection contract: preferred `uv run sim inspect` targets, compatibility rules, partial results, and raw Java fallbacks. | | `base/reference/java_api_patterns.md` | Stable Java API probing patterns: tags first, properties before `set`, selection checks, and version-safe try/except snippets. | | `base/reference/java_batch_patterns.md` | Read before writing `.java` for `comsolcompile`: chain-style calls, anti-patterns that fail to compile, source-property toggles (`<prop>_src`), study/sol skeleton, KPI extraction via stdout, error triage. | | `base/reference/mph_file_format.md` | `.mph` is a ZIP archive — internal layout, the three `nodeType` variants (compact/solved/preview), the Global Parameter `T="33"` contract, and the stdlib `mph_inspect` reader. Read this when you need to introspect a `.mph` *without* spinning up `comsolmphserver`. | | `base/reference/offline_postprocessing_exports.md` | Optional pattern for COMSOL-free/Python postprocessing after a solve. Use when the user asks for reusable result artifacts, full-domain VTU field exports, CSV tables, or postprocessing without keeping COMSOL open. | Larger engineering examples do not live in this plugin skill. Keep this plugin-owned content focused on the driver protocol, live introspection, debug loops, and the smallest smoke/reference workflow. Each numbered step is a self-contained snippet for the sim runtime after `uv run sim connect --solver comsol`. This workflow is incremental and inspect-after-each-step, so a live session is the right path for it. Once a model build is settled, the batch path is the better choice for re-running it — see the decision table above. Before running a new or complex workflow, read [`base/reference/runtime_introspection.md`](base/reference/runtime_introspection.md) and [`base/workflows/model_review_loop.md`](base/workflows/model_review_loop.md). For failed snippets, switch immediately to [`base/workflows/debug_failed_exec.md`](base/workflows/debug_failed_exec.md) instead of guessing another full script. ### `solver/<active_solver_layer>/` — release specifics Empty stubs by default; per-release deltas land here as discovered. - `solver/6.4/notes.md` — current - `solver/6.2/notes.md` - `solver/6.1/notes.md` - `solver/6.0/notes.md` ### `doc-search/` — local documentation lookup When a physics feature name, API method, or module capability is unknown, choose the cheapest evidence source that can answer the question. Local docs are often the right first probe for names, modules, examples, and API terms: ```bash uv run --project src/sim_plugin_comsol/_skills/comsol/doc-search sim-comsol-doc search "<term>" [--module <substring>] ``` For an already-loaded model or a failed live step, inspect the current model state: ```bash uv run sim inspect session.health uv run sim inspect last.result uv run sim inspect comsol.model.describe_text uv run sim inspect comsol.node.properties:<tag-or-dot-path> ``` The COMSOL driver may not expose every inspect target on older plugin builds. If an inspect target is unavailable, use the raw Java fallback patterns in [`base/reference/java_api_patterns.md`](base/reference/java_api_patterns.md). `doc-search` runs in pure CPython: no live COMSOL session, no sim runtime, and no JVM. It scans the installed COMSOL HTML help on disk. One-time setup on any host that has COMSOL installed: ```bash cd src/sim_plugin_comsol/_skills/comsol/doc-search && uv sync ``` (No index build step — each query scans the doc tree in parallel; typical latency is 1–3 s on a local SSD.) Tips for good queries: - Use **2–3 keywords**, not questions. COMSOL search is keyword-matched. - Filter by `--module battery` / `--heat` / `--cfd` / `--plasma` to bias toward a module's plugin folder (matched as a substring of the `com.comsol.help.*` name). - Progressive broadening: if `"C-rate battery"` returns nothing, try `"discharge rate"`, then `"battery performance"`. - For **API / coding** questions, filter `--module programming` or `--module api`. Plugin names follow `com.comsol.help.*` — inspect a few results and adjust. To read the full text of a hit: ```bash uv run sim-comsol-doc retrieve com.comsol.help.battery/battery_aging.03.01.html ``` See `doc-search/README.md` for discovery details and the install-root override (`--comsol-root`) if auto-detection fails. #### Application Gallery: local vs. web The local index also covers the **Application Gallery** content for every module the user has installed — those plugins are named `com.comsol.help.models.*` (e.g. `com.comsol.help.models.battery.li_battery_1d`). Filter with `--module models` to scope a search to example-model docs: ```bash uv run sim-comsol-doc search "thermal runaway" --module models.battery ``` For models that belong to **modules not installed** on the user's host (or for browsing by image/category), point the user at <https://www.comsol.com/models>. Don't scrape it from the skill — just link. --- ## MPH file introspection (stdlib path — no JVM) For "what's in this `.mph`?" queries — parameters, physics tags, nodeType, mesh/solution sizes — prefer the stdlib reader over a live JVM: ```python from sim_plugin_comsol.lib import inspect_mph summary = inspect_mph(path) # one-shot dict ``` `MphArchive` (context manager) and `mph_diff` (two-file delta) are also available. `MphFileProbe` is wired into the driver's default probe list, so any `.mph` produced by a `sim` run is auto-described in `uv run sim inspect last.result` — no extra call needed. See [`base/reference/mph_file_format.md`](base/reference/mph_file_format.md) for the archive layout, the `nodeType` variants, and the Global Parameter `T="33"` extraction contract. Use `.mph` archive inspection for saved artifacts and offline comparison. Use live runtime introspection for the current JPype session, especially before changing selections, physics features, studies, and result nodes. ## Optional offline postprocessing exports When the user wants Python-friendly postprocessing without keeping COMSOL open, export reusable data artifacts once from the live or headless COMSOL session, then process those files offline. Prefer full-domain VTU field data and CSV/TXT tables over screenshots or slices as the reusable source data. See [`base/reference/offline_postprocessing_exports.md`](base/reference/offline_postprocessing_exports.md) for the optional bundle layout and headless export snippets. --- ## Headless `comsolbatch -inputfile`: direct saved-model execution `comsolbatch.exe -inputfile in.mph -outputfile out.mph -batchlog log.txt` is COMSOL's canonical non-interactive entry point for running a saved model — it is a real capability you can invoke **today**, directly, with no `comsolmphserver` and no `sim serve`. Prefer it when a one-shot saved-model run is what you need: deterministic batch runs that do not need Desktop collaboration or live introspection, regression/CI runs, and fan-out over many `.mph` files. Call `comsolbatch.exe` directly for saved-model runs, and use `comsolcompile` + `comsolbatch` directly for one-shot `.java` recipes (see [`base/reference/java_batch_patterns.md`](base/reference/java_batch_patterns.md)). A sim-managed batch lifecycle wrapper is not implemented; `sim connect --solver comsol` goes through `comsolmphserver` + JPype. Use the sim runtime when you need live introspection, incremental building, plugin diagnostics, or shared-desktop collaboration. On Windows, COMSOL batch logs may be UTF-16. If a normal read path reports the log as binary, decode it explicitly before deciding the run has no useful output: ```powershell [System.Text.Encoding]::Unicode.GetString([System.IO.File]::ReadAllBytes($log)) ``` --- ## Long-running execution and recovery Keep bounded COMSOL work in the foreground when it fits the active tool-call budget. Move a settled solve to native batch or a background process only when it is expected to outlive that budget, must continue across agent turns, or the user explicitly asks for background execution. Keep live sessions for incremental inspection and mutation; prefer `comsolbatch` for a settled, repeatable long solve. For a long batch run, use absolute `-batchlog` and `-outputfile` paths so the agent can inspect progress and results later. Do not require a fixed directory tree, a job manifest, or sim-cli when the direct COMSOL command is sufficient. A shell or tool timeout ends that observation call; it does not prove COMSOL stopped. Before retrying or stopping, check the existing process, batch-log tail, and output-file timestamps. Confirm process ownership from the executable, full command line, start time, and batch-log/output targets. Never terminate every `comsol` process by name. Use *resume* only when a saved `.mph` or another COMSOL-native checkpoint contains state that can actually continue the solve. Without a usable checkpoint, describe the action as a restart rather than promising generic resume behavior. --- ## Path-scoped guardrails Use these guardrails in the path where they apply. They are meant to preserve agent exploration while avoiding known COMSOL failure modes. 1. **Runtime snippets with a provided `model` handle.** In a sim runtime or another already-connected JPype/Java API context, reuse the provided model/client. Starting a second `mph.start()` or `client.create()` can spawn a conflicting COMSOL JVM. In standalone Python `mph` scripts, creating a client may be the correct setup step. 2. **Batch Java through `comsolcompile`.** Use chain-style `model.X("tag").Y("tag2")...` calls. Typed COMSOL node declarations such as `Component comp = ...` fail at compile time; see [`base/reference/java_batch_patterns.md`](base/reference/java_batch_patterns.md). For heat-transfer smoke models, `HeatTransferInSolids` can be unavailable on some installs; if batch output says `Unknown physics interface`, try the installed docs or the more generic `HeatTransfer` interface before treating COMSOL itself as unavailable. 3. **Unfamiliar live properties or selections.** You do not need to query docs before every edit; familiar paths can use a fast write-run loop. If a COMSOL compile or batch run reports an unknown property, unknown feature, or non-editable/invalid node state, stop blind retries and confirm the exact node through local docs or live/local probes. Good probes include `uv run sim inspect comsol.node.properties:<target>`, the raw Java `properties()` pattern, `tags()`, and `selection().entities()`. 4. **Live exploratory builders.** For stateful model creation or debugging, work in coherent layers, inspect after meaningful changes, and save checkpoints. A settled standalone batch recipe may be a single `.java` class or saved-model batch run when it has enough output evidence. 5. **Visual artifacts.** Numeric probes and exported data are the acceptance evidence. PNG export has