PFC - ITASCA Discrete Element Simulation

Browse Itasca Python SDK documentation by path (like glob + cat).

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.

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

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")

List tracked Itasca tasks with pagination.

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

Request graceful interruption of a running Itasca task.

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

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.

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