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:

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.

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/javabatchpatterns.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.

1. 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.

1. 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:

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:

"session.versions": {
  "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// 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 triage loop for a failed uv run sim exec: inspect last.result, inspect live model state, inspect suspicious node properties, then retry with the smallest patch. | | 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 (_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/runtimeintrospection.md) and [base/workflows/model_review_loop.md](base/workflows/modelreviewloop.md). For failed snippets, switch immediately to [base/workflows/debug_failed_exec.md](base/workflows/debugfailed_exec.md) instead of guessing another full script.

solver// — 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:

uv run --project src/sim_plugin_comsol/_skills/comsol/doc-search sim-comsol-doc search "" [--module ]

For an already-loaded model or a failed live step, inspect the current model state:

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:

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/javaapipatterns.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:

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:

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:

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 . 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:

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/mphfileformat.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/offlinepostprocessingexports.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/javabatchpatterns.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.

---

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.

1. 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/javabatchpatterns.md).

1. Unfamiliar live properties or selections.

Probe the live node or local docs before mutation. Good probes include uv run sim inspect comsol.node.properties:, the raw Java properties() pattern, tags(), and selection().entities().

1. 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.

1. Visual artifacts.

Numeric probes and exported data are the acceptance evidence. PNG export has been unreliable in known Windows setups; test visual export when figures are required, and keep screenshots as human review aids rather than the only proof.

---

Model identity, workdir, and checkpoints

For non-trivial COMSOL work, establish a durable model identity and working folder before building geometry, materials, physics, mesh, or studies. COMSOL permits untitled Model1 scratch models, but agents need a clear artifact to resume from after chat compaction, process restart, server reload, or human handoff.

Use this policy:

• For deliverable geometry, materials, physics, meshes, studies, sweeps, or

results, create or bind a durable project identity early. Set a visible title/label, set the working folder, and save an initial .mph checkpoint.

• If the user provided an .mph, load that exact file and bind the session t

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: svd-ai-lab
• Source: svd-ai-lab/sim-plugin-comsol
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.