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. Companion tools manage the lifecycle:

• itasca_check_task_status: poll output, progress, and final status

• itasca_interrupt_task: cancel a running task

• itasca_list_tasks: browse task history For synchronous, inline execution, use itasca_execute_code instead.

While the task is cycling, itasca_execute_code shares the same main namespace in the engine's main thread, so you can inspect or modify simulation state live — probe progress, tune parameters mid-run, swap callbacks, or trigger early termination via a sentinel variable. Submit with reasonable starting values and refine as the task runs.

Console output from itasca.command() inside the script (table dumps, list output, command summaries) is captured into the task log alongside Python prints, visible through itasca_check_task_status.

Script-writing rules:

• Multi-line itasca.command("""...""") batches are normalized to one engine call per command, keeping the task interruptible mid-batch. Normalization recognizes itasca.command through its import name; call it through that name directly — rebinding via intermediate variables (_it = itasca) bypasses it and logs a bridge warning.

• Pass each FISH definition block (fish define / fish operator / legacy bare define, through its terminating standalone end) whole, in ONE itasca.command() string; feeding one line-by-line leaves the engine blocked in interactive FISH mode until completed manually in the GUI console. Per-line loops are fine for ordinary commands.

• program call '<file>' (.p3dat / .p2dat / .dat / ...) is supported: the bridge runs the file inline, one command per engine call, so the bridge stays reachable, the task stays interruptible, and the file's output lands in the task log command by command.

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 tasks tracked by the bridge, newest first.

Read-only. Each entry carries task_id, status (pending / running / completed / failed / interrupted), description, entry_script, start_time, end_time and elapsed_time; total_count gives the size of the full history for paging via skip_newest + limit.

Task history is persisted in the engine working directory and survives GUI restarts. Use this to recover a task_id from an earlier session, to see what is running or recently finished, or as a cheap bridge-connectivity check. For a task's output and result use itasca_check_task_status; to submit a script use itasca_execute_task.

Request interruption of a pending or running Itasca task.

Returns as soon as the request is accepted; it does not wait for the task to stop. Confirm the stop and read the output produced so far with itasca_check_task_status. Only the script stops; the engine state is preserved, so you can inspect it with itasca_execute_code or continue from it with a new itasca_execute_task. Tasks already completed, failed or interrupted return an error. If the task_id is unknown, find it with itasca_list_tasks.

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.

The tool stays responsive while a task submitted via itasca_execute_task is cycling (calls interleave at cycle gaps), so use it as a live REPL — nothing has to be pre-scripted into the task up front. Typical uses:

• Query model state and read Itasca command output: itasca.command('ball list') etc. — table dumps, list output, and command summaries are captured and interleaved with Python prints in execution order

• Live inspection and tuning during a running task: check forces or contact statistics, modify parameters, swap callbacks, set sentinel variables the task reads each cycle

• Create and export plots: itasca.command('plot ...')

Environment: the engine's embedded Python interpreter (Itasca 9+ → Python 3.10, pre-9 → Python 3.6 or older; the product+version is encoded in sys.executable, e.g. PFC900). When unsure, check sys.version_info before relying on newer syntax.

Code-writing rules (shared with itasca_execute_task):

• Multi-line itasca.command("""...""") batches are normalized to one engine call per command, keeping the bridge reachable mid-batch. Normalization recognizes itasca.command through its import name; call it through that name directly — rebinding via intermediate variables (_it = itasca) bypasses it and the output carries a bridge warning.

• Pass each FISH definition block (fish define / fish operator / legacy bare define, through its terminating standalone end) whole, in ONE itasca.command() string; feeding one line-by-line leaves the engine blocked in interactive FISH mode until completed manually in the GUI console. Per-line loops are fine for ordinary commands.

• program call '<file>' (.p3dat / .p2dat / .dat / ...) is supported: the bridge runs the file inline, one command per engine call, so the bridge stays reachable, the run stays interruptible, and the file's output arrives command by command.

Synchronous semantics: the request blocks until the code finishes or hits the timeout (default 10s, max 20s), and 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 via itasca_execute_task instead.