pfc_execute_code
Execute Python code in a running PFC simulation to inspect and modify state in real time, without interrupting the ongoing task.
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
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 | |||