# Comsol Sim

> Use when the user asks Codex, Claude Code, ChatGPT-style coding agents, or another AI agent to build, inspect, run, debug, or revise COMSOL Multiphysics / COMSOL Desktop models. Choose the simplest real COMSOL control path for the task: saved `.mph` inspection, local COMSOL documentation, direct COMSOL executables (`comsolbatch`, `comsolcompile`, `comsolmphserver`, `comsol.exe mphclient`), or the…

- **Type:** Skill
- **Install:** `agentstack add skill-svd-ai-lab-sim-plugin-comsol-comsol`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [svd-ai-lab](https://agentstack.voostack.com/s/svd-ai-lab)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [svd-ai-lab](https://github.com/svd-ai-lab)
- **Source:** https://github.com/svd-ai-lab/sim-plugin-comsol/tree/main/src/sim_plugin_comsol/_skills/comsol

## Install

```sh
agentstack add skill-svd-ai-lab-sim-plugin-comsol-comsol
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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=
```

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:

```json
"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/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//` — 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 "" [--module ]
```

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

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

---

## 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).
3. **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()`.
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
   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](https://github.com/svd-ai-lab)
- **Source:** [svd-ai-lab/sim-plugin-comsol](https://github.com/svd-ai-lab/sim-plugin-comsol)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-svd-ai-lab-sim-plugin-comsol-comsol
- Seller: https://agentstack.voostack.com/s/svd-ai-lab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.