Browse PFC 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:

• pfc_query_command: Search commands by keywords (when path unknown)

• pfc_browse_reference: Browse reference docs (e.g., "contact-models linear")

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

Browse PFC reference documentation (syntax elements, model properties).

References are language elements used within commands, not standalone commands.

Navigation levels:

• No topic: All reference categories

• Category (e.g., "contact-models"): List items in category

• Full path (e.g., "contact-models linear"): Full documentation

When to use:

• Need contact model property names (kn, ks, fric, pb_*)

• Need range filtering syntax (position, cylinder, group, id)

• Need plot item configuration (color-by, cut plane, transparency, legend)

• Setting up "contact cmat add model ... property ..." commands

• Using range filters in any PFC command

• Configuring "plot item create" commands

Related tools:

• pfc_browse_commands: Command syntax (e.g., "ball create")

• pfc_query_command: Search commands by keywords

Search PFC command documentation by keywords (like grep).

Returns matching command paths. Use pfc_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:

• pfc_browse_commands: Get full documentation for a known command path

• pfc_browse_reference: Browse reference docs (e.g., "contact-models linear")

• pfc_query_python_api: Search Python SDK by keywords

Search PFC Python SDK documentation by keywords (like grep).

Returns matching API paths with signatures. Use pfc_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:

• pfc_browse_python_api: Get full documentation for a known API path

• pfc_query_command: Search PFC commands by keywords

Submit a Python script file for asynchronous execution in PFC.

Returns a task_id immediately; the script runs in the background. Use the companion tools to manage the task lifecycle:

• pfc_check_task_status: poll output, progress, and final status

• pfc_interrupt_task: cancel a running task

• pfc_list_tasks: browse task history

While the task is cycling, you can call pfc_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 PFC'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 pfc_check_task_status.

Do NOT have the script invoke program call '<file>.p3dat' (or .p2dat / .dat). PFC's command-script interpreter blocks the bridge for the script's entire duration with no cycle-gap interleaving, leaving the bridge unreachable until PFC is stopped manually. If the user asks to run a .dat / .p3dat / .p2dat file, read the file and translate its commands into a sequence of itasca.command(...) calls in the Python script instead.

This is the async / background execution path: pollable via pfc_check_task_status, cancellable via pfc_interrupt_task. Submission does not lock parameters — start with reasonable values and refine live via pfc_execute_code as the task cycles. For synchronous, inline execution, use pfc_execute_code directly.

Check status and paginated output for a submitted PFC task.

Output combines Python prints and PFC 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 PFC tasks with pagination.

Request graceful interruption of a running PFC task.

Execute Python code synchronously in the running PFC process.

Returns stdout and an optional result variable immediately. Code runs in PFC'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 pfc_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: PFC's embedded Python interpreter. The version is bundled with PFC (PFC 6/7 → Python 3.6, PFC 9 → 3.10); the PFC version is encoded in sys.executable (e.g. PFC700, PFC900). When unsure, write code compatible with Python 3.6+.

Typical uses:

• Query model state: ball/wall/contact counts, current cycle

• Issue PFC 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

Do NOT invoke program call '<file>.p3dat' (or .p2dat / .dat) through this tool. PFC's command-script interpreter blocks the bridge for the script's entire duration with no cycle-gap interleaving, so any long model cycle inside the file leaves the bridge unreachable until PFC is stopped manually. If the user asks to run a .dat / .p3dat / .p2dat file, read the file and translate its commands into a sequence of itasca.command(...) calls in Python instead.

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 pfc_list_tasks and cannot be interrupted mid-execution. For cancellable, pollable, or background work, submit it via pfc_execute_task instead — and you can still call pfc_execute_code against the task while it cycles.