pfc_execute_code

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.