Browse Itasca command documentation by path (like glob + cat).
Navigation levels:
- No command: All command categories overview
- Category only (e.g., "ball"): List commands in category
- Full command (e.g., "ball create"): Full documentation
When to use:
- You know the command category or exact command
- You want to explore available commands
Related tools:
- itasca_query_command: Search commands by keywords (when path unknown)
- itasca_browse_reference: Browse reference docs (e.g., "contact-models linear")
Browse Itasca Python SDK documentation by path (like glob + cat).
Browse ITASCA reference documentation (syntax elements, model properties).
Works across engines via the required ``software`` selector (pfc/flac/3dec).
References are language elements used within commands, not standalone commands.
Navigation levels:
- No topic: All reference categories for the engine
- Category (e.g., "constitutive-models"): List items in category
- Full path (e.g., "constitutive-models mohr-coulomb"): Full documentation
- Sub-item path (e.g., "plot-items zone contour"): Sub-item details
When to use:
- Need material/contact/joint model property names (kn, ks, fric, cohesion, friction, ...)
- Need range filtering syntax (position, cylinder, group, id)
- Need plot item configuration (contour, label, color-by, cut, transparency, legend)
- Setting up model-assignment commands (e.g. "... cmodel assign ... property ...")
- Using range filters in any command
- Configuring "plot item create" commands
Related tools:
- itasca_browse_commands: Command syntax (e.g., "zone create")
- itasca_query_command: Search commands by keywords
Search Itasca command documentation by keywords (like grep).
Returns matching command paths. Use itasca_browse_commands for full documentation.
When to use:
- You have keywords but don't know exact command path
- Example: "ball create", "contact property", "model solve"
Related tools:
- itasca_browse_commands: Get full documentation for a known command path
- itasca_browse_reference: Browse reference docs (e.g., "contact-models linear")
- itasca_query_python_api: Search Python SDK by keywords
Search Itasca Python SDK documentation by keywords (like grep).
Returns matching API paths with signatures. Use itasca_browse_python_api for full documentation.
When to use:
- You have keywords but don't know exact API path
- Example: "ball velocity", "create", "contact force"
Related tools:
- itasca_browse_python_api: Get full documentation for a known API path
- itasca_query_command: Search Itasca commands by keywords
Submit a Python script file for asynchronous execution in the Itasca engine.
Returns a task_id immediately; the script runs in the background.
Use the companion tools to manage the task lifecycle:
- itasca_check_task_status: poll output, progress, and final status
- itasca_interrupt_task: cancel a running task
- itasca_list_tasks: browse task history
While the task is cycling, you can call itasca_execute_code at any
time to inspect or modify simulation state — including variables
the task depends on. This is the standard way to probe progress,
tune parameters mid-run, swap callbacks, or trigger early
termination via a sentinel variable. Both tools share the same
__main__ namespace in the engine's main thread.
Console output from itasca.command() inside the script —
table dumps, list output, command summaries — is captured
and interleaved with Python prints in the task log, visible
through itasca_check_task_status.
Multi-line itasca.command("""...""") batches are normalized to
one engine call per command, which keeps the bridge reachable
and the task interruptible while the batch runs — including
after a `model new`/`model restore`, which reset the engine's
cycle-callback registry mid-batch. The normalization applies
when itasca.command is reached through its import name
(`import itasca` / `import itasca as x` / `from itasca import
command`); rebinding through intermediate variables
(`_it = itasca`) bypasses it, and the task log then carries a
bridge warning.
FISH definition blocks (`fish define` / `fish operator` /
legacy bare `define` ... `end`) must arrive at the engine
whole: pass the complete block, header through its
terminating standalone `end`, in ONE itasca.command() string —
on its own or inside a multi-line batch (normalization keeps
definition blocks intact as a single engine call). Never feed
a definition line-by-line (e.g. looping with one
itasca.command(line) per line): the `fish define` header alone
drops the console into interactive FISH mode and that engine
call blocks waiting for body input that can never arrive over
the bridge, leaving the engine stuck until someone completes
the definition manually in the GUI console. Per-line loops
are fine for ordinary commands; only definition blocks must
stay in one string.
Having the script invoke `program call '<file>.p3dat'` (or
.p2dat / .dat) is engine-version-gated. On 6/7 the
command-script interpreter blocks the bridge for the
script's entire duration with no cycle-gap interleaving,
leaving the bridge unreachable until the engine is stopped
manually. Never emit it there, and treat unknown or
unverified versions (including 9.0-9.6) the same way.
On 9.7+ the bridge stays fully responsive during a
`program call` (verified on 9.7: status polling, cycle-gap
interleaving, and interrupt all work mid-call). Even where
it is safe, prefer reading the file and translating its
commands into a sequence of `itasca.command(...)` calls in
the Python script — that keeps per-command output, error
locality, and mid-script control that a single opaque
`program call` cannot give.
This is the async / background execution path: pollable via
itasca_check_task_status, cancellable via itasca_interrupt_task.
Submission does not lock parameters — start with reasonable
values and refine live via itasca_execute_code as the task
cycles. For synchronous, inline execution, use
itasca_execute_code directly.
Submission uses the bridge's `execute_task` protocol message. If
a submission times out, the connected bridge may predate it —
confirm its version with itasca_execute_code (`import
itasca_mcp_bridge; print(itasca_mcp_bridge.__version__)`). To
upgrade, fetch and follow the bootstrap guide, then resubmit:
https://raw.githubusercontent.com/yusong652/itasca-mcp/main/docs/agentic/itasca-mcp-bootstrap.md
Check status and paginated output for a submitted Itasca task.
Output combines Python prints and Itasca console output from
itasca.command() calls (table dumps, list output, command
summaries) interleaved in execution order. Use skip_newest /
limit to paginate, or filter to keep only matching lines.
List tracked Itasca tasks with pagination.
Request graceful interruption of a running Itasca task.
Execute Python code synchronously in the running Itasca engine process.
Returns stdout and an optional result variable immediately.
Code runs in the engine's main thread, sharing the same __main__
namespace as any running task — side effects persist and are
immediately visible to the task on its next cycle.
This tool remains responsive EVEN WHILE a simulation task is
running (submitted via itasca_execute_task), as long as the task
is actively cycling — execute_code interleaves at cycle gaps.
Use it as a live REPL to inspect simulation state in real
time — no need to pre-script print statements, and parameter
sweeps or sentinel-based control don't have to be baked into
the task script up front.
Environment: the Itasca engine's embedded Python interpreter.
The version is bundled with the engine (Itasca 6/7 → Python 3.6,
Itasca 9 → 3.10); the product+version is encoded in sys.executable
(e.g. PFC900, FLAC900). When unsure, write code compatible with
Python 3.6+.
Typical uses:
- Query model state: ball/wall/contact counts, current cycle
- Issue Itasca commands and read their console output:
itasca.command('ball list'), itasca.command('model list
information'). Table dumps, list output, and command
summaries are captured and interleaved with Python prints
in execution order — no need to re-implement queries via
the SDK just to see what a command would print
- Live inspection during a running task: check forces,
energy, coordination number, contact statistics
- Live tuning during a running task: modify parameters,
swap callbacks, or set sentinel variables that the task
reads each cycle (e.g. change a servo target, adjust
damping, signal early termination)
- Create and export plots: itasca.command('plot ...')
- Development and REPL-style testing
Multi-line itasca.command("""...""") batches are normalized to
one engine call per command, which keeps the bridge reachable
while the batch runs — including after a `model new`/
`model restore`, which reset the engine's cycle-callback
registry mid-batch. The normalization applies when
itasca.command is reached through its import name
(`import itasca` / `import itasca as x` / `from itasca import
command`); rebinding through intermediate variables
(`_it = itasca`) bypasses it, and the output then carries a
bridge warning.
FISH definition blocks (`fish define` / `fish operator` /
legacy bare `define` ... `end`) must arrive at the engine
whole: pass the complete block, header through its
terminating standalone `end`, in ONE itasca.command() string —
on its own or inside a multi-line batch (normalization keeps
definition blocks intact as a single engine call). Never feed
a definition line-by-line (e.g. looping with one
itasca.command(line) per line): the `fish define` header alone
drops the console into interactive FISH mode and that engine
call blocks waiting for body input that can never arrive over
the bridge, leaving the engine stuck until someone completes
the definition manually in the GUI console. Per-line loops
are fine for ordinary commands; only definition blocks must
stay in one string.
`program call '<file>.p3dat'` (or .p2dat / .dat) through this
tool is engine-version-gated. On 6/7 the command-script
interpreter blocks the bridge for the script's entire
duration with no cycle-gap interleaving — any long
`model cycle` inside the file leaves the bridge unreachable
until the engine is stopped manually. Never emit it there, and
treat unknown or unverified versions (including 9.0-9.6) the
same way. On 9.7+ the bridge stays fully
responsive during a `program call` (verified on 9.7: status
polling, cycle-gap interleaving, and interrupt all work
mid-call). Even where it is safe, prefer reading the file
and translating its commands into a sequence of
`itasca.command(...)` calls in Python — that keeps
per-command output, error locality, and mid-script control
that a single opaque `program call` cannot give.
This is a synchronous tool: the request blocks until the code
finishes or hits the timeout (default 10s, max 600s). Output
is returned in full; the call is NOT tracked by itasca_list_tasks
and cannot be interrupted mid-execution. For cancellable,
pollable, or background work, submit it via itasca_execute_task
instead — and you can still call itasca_execute_code against the
task while it cycles.