pfc_execute_code
Execute Python code in the running PFC simulation to inspect and modify state in real time. Use it as a live REPL during tasks without pre-scripted prints.
Instructions
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Python code to execute in PFC user console | |
| timeout | No | Console execution timeout in seconds |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||