svd-ai-lab/sim-plugin-comsol/comsol

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.

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=<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` 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. Require version_source: active_runtime before using release-specific notes; another COMSOL installation detected on the host is not evidence about this session:

"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

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` and `base/workflows/model_review_loop.md`. For failed snippets, switch immediately to `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:

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:

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

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

from sim_plugin_comsol.lib import inspect_mph
summary = inspect_mph(path)   # one-shot dict