sim

sim reads existing CAE files and turns them into structured text an agent can use — without launching the solver. It also detects local solver installs, validates scripts before you run them, and can hold a live solver session open when an agent needs to work one verified step at a time.

Python 3.10+ · Apache-2.0 · alpha

Scan existing simulation assets

Point sim scan at a folder of .mph / .inp / .cas.h5 / .aedt files and get back structured JSON an agent can reason over — model inventory, materials, boundary conditions, mesh counts, solve settings. No solver, no license, and no plugin needed:

uv init                  # only if this is not already a uv project
uv add sim-cli-core
uv run sim --json scan ./historical-cases

$ uv run sim --json scan ./cases/beam.inp --full
{
  "schema_version": "sim.scan/v1",
  "assets": [{
    "file_name": "beam.inp",
    "format": "abaqus-inp",
    "summary": {"data": {
      "title": "Cantilever beam thermal-stress",
      "node_count": 3,
      "element_count": 1,
      "materials": ["STEEL"],
      "sections": ["SOLID SECTION:STEEL"],
      "steps": ["STATIC"],
      "boundary_keywords": ["BOUNDARY"],
      "load_keywords": ["CLOAD"],
      "output_keywords": ["NODE PRINT"]
    }}
  }]
}

(abridged — the real envelope also carries ok, engine, request, and a roll-up summary block.)

The default view is bounded — lists come back as {total, sample, truncated} so a large scan cannot blow up an agent's context — and absolute paths are redacted unless --include-paths is set. Use --full for the complete parser result on a small input set, --limit and --no-recursive to bound a directory walk, and --format to force a format for an explicitly named file.

Example: what's in this folder?

Scan ./legacy-cases and tell me which models are package-level thermal
studies, which already have solved results, and what total power each one
assumes. Use `uv run sim --json scan`.

Find solvers and validate scripts

These need the solver's plugin installed — sim-cli-core ships with no drivers:

uv add sim-plugin-comsol
uv run sim plugin sync-skills --target .agents/skills --copy
uv run sim check comsol                    # detect local installs and versions
uv run sim plugin doctor comsol --deep     # plugin wiring + solver detection
uv run sim lint <script>                   # validate before running

Use .agents/skills for Codex and GitHub Copilot, .claude/skills for Claude Code. Two things are worth telling the agent explicitly: run through the project with uv run sim ... so it sees the project's installed plugins, and never guess solver API names — inspect the live model or the solver's local docs first.

No uv, or installing from a wheel, git, or a local checkout — and the sim.toml project manifest schema — are covered in docs/plugin-install.md.

Drive a live solver session

When an agent needs the solver held open across steps, sim connect starts a local runtime and keeps the session alive. A bounded step is one modeling, meshing, solving, or postprocessing action that can be inspected and verified before continuing: create a geometry feature, assign a material, generate a mesh, run one study, extract a probe value, export a result table.

Prefer this loop over one large generated script:

1. uv run sim check <solver>, then uv run sim connect --solver <solver>
2. uv run sim inspect session.versions before changing state — including after any human GUI edit, since an engineer can cut in through the solver GUI at any time and a previous script may no longer match the real session
3. uv run sim exec --file step.py --label <step> — one bounded step
4. uv run sim inspect last.result, verify with numeric evidence (mesh statistics, convergence, probes, conservation checks, tolerances), checkpoint
5. uv run sim disconnect, then uv run sim stop to free the local runtime

The bundled solver skill enforces the details, so give the agent the engineering goal in plain language rather than a list of sim sub-steps:

Simulate the natural-convection cooling of the attached `pcb.mph` and report the
maximum junction temperature. Use the installed COMSOL skill. If you need a
visible COMSOL Desktop session, connect with `--ui-mode gui`.

Running the solver on a different host — and the security constraints that come with it — is covered in docs/remote-solvers.md.

Solver plugins

Solver knowledge is not in the core CLI. It comes from plugins, each of which provides a driver, so sim can launch or talk to the solver, and a skill, so the agent knows that solver's workflow, pitfalls, and inspection rules.

For the curated full list, see sim-plugin-index.

Commands

Every command takes --json and returns a stable envelope with a closed error-code enum — see docs/agent-readability.md.

Run uv run sim --json describe for a machine-readable command manifest, or uv run sim <command> --help for exact options.

Solver ownership

sim-cli does not bundle or redistribute simulation solvers or vendor SDKs. Install and operate each underlying solver according to its vendor terms. See NOTICE for optional SDK dependency notes.

sim-cli is an independent open-source project and is not affiliated with, endorsed by, or sponsored by any solver vendor. Product, solver, and company names remain the property of their respective owners.

Docs

• docs/agent-readability.md — --json envelope, error-code enum, exit codes. Read this first if you are an agent.
• docs/DEVELOPMENT.md — project setup, layout, driver protocol, and architecture notes
• docs/plugin-install.md — plugin installation and sim.toml reference
• docs/remote-solvers.md — running the solver on another host, and the security constraints that apply
• docs/why-cli-first.md — why a CLI rather than MCP
• CONTRIBUTING.md — branch, test, and PR workflow

License

Apache-2.0 — see LICENSE.