yade_execute_code
Run Python code synchronously inside the running YADE process to query or modify simulation state in real time, including during active simulations.
Instructions
Execute Python code synchronously in the running YADE process.
Returns stdout immediately. Code runs in the YADE Python environment where yade modules are already imported; side effects persist.
This tool remains responsive EVEN WHILE a simulation task is running (submitted via yade_execute_task). Use it as a live REPL to inspect simulation state in real time — no need to pre-script print statements.
Typical uses:
Query simulation state: O.bodies count, current iteration
Create/modify bodies, engines, interactions
Read or set material properties
Live inspection during a running simulation (e.g. check stress tensor, coordination number, energy balance, or capture viewport screenshots when GUI is available)
Development and REPL-style testing
O.engines[0] holds a PyRunner that belongs to yade-mcp-bridge (its command mentions "mcp bridge"). Ignore it: assign O.engines as usual, the bridge re-adds the PyRunner before every O.run().
Unlike yade_execute_task, this tool is fire-and-return: the response contains the full output. It is NOT tracked by yade_list_tasks and cannot be interrupted or polled.
Timeout behaviour: on timeout the bridge attempts to abort the
running code. The response is an error envelope (ok=false)
whose error.code is one of:
interrupted— the code was running a simulation cycle (O.run) and was paused cleanly at an iteration boundary. For long simulations or solving to equilibrium, switch to yade_execute_task — it tracks progress and stops cleanly via yade_interrupt_task.terminated— a non-cycle abort succeeded (async exception injection); the pump thread is free, but YADE state may be partially modified by the code that ran before the abort fired. Inspect state before retrying.timeout— abort failed (code stuck in a C extension, or nested inside a running task's PyRunner tick); the bridge may still be blocked. Restart if unresponsive.
WARNING: For anything expected to take more than a few seconds,
use yade_execute_task instead — it has proper cancellation via
yade_interrupt_task and does not leave state drift on timeout.
Also, do NOT write except BaseException: in your code; it
defeats bridge-initiated cancellation.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Python code to execute in YADE process | |
| timeout | No | Seconds before the bridge aborts the snippet; longer work belongs in yade_execute_task. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||