Browse YADE's Python API as a YADE-native class tree.

The tree is rooted in YADE's real inheritance hierarchy: paths mirror the class's mro up to its category root. No shortcuts — always drill through parents.

Search YADE API documentation by keywords (like grep).

Returns matching class/function names with descriptions ranked by relevance. Use yade_browse_api for full documentation of a specific class.

When to use:

• You have keywords but don't know the exact class name

• Examples: "friction material", "gravity engine", "contact force", "triaxial stress", "sphere create", "hertz mindlin"

Related tools:

• yade_browse_api: Get full documentation for a known class path

Submit a Python script for asynchronous execution in YADE.

Returns a task_id immediately; the script is queued and runs in the background. Tasks run one at a time in submit order (they share the YADE process and its single simulation state), so a multi-stage pipeline can be submitted in one go — each stage starts when the previous one finishes. Use the companion tools to manage the task lifecycle:

• yade_check_task_status: poll output, progress, and final status

• yade_interrupt_task: stop a running task or cancel a queued one

• yade_list_tasks: browse task history (also shows queue order)

Use this for production simulation runs, long O.run() cycles, and any operation that may take minutes or longer. For quick queries and REPL-style testing, use yade_execute_code.

O.engines[0] holds a PyRunner that belongs to yade-mcp-bridge (its command mentions "mcp bridge"). The script does not need to keep it: assign O.engines as usual, the bridge re-adds the PyRunner before every O.run().

Check status and output for a submitted YADE task.

List tracked YADE tasks with pagination.

Tasks are listed newest first. Queued (pending) tasks run one at a time in submit order, so among the pending entries the one furthest down the list runs next.

Stop a running YADE task, or cancel one still waiting in the queue.

A task that has not started yet is simply removed from the queue and ends in status canceled (method reports canceled_while_queued). For a running task, two cancellation paths are applied together by the bridge:

• flag_only — sets an interrupt flag that YADE's PyRunner tick observes between simulation iterations (graceful path for O.run tasks).

• flag_and_async_exc — in addition, injects a TaskInterrupt exception into the script thread, so pure-Python deadloops with no O.run on the stack are terminated too.

The response method field reports which path ran. When async-exc is refused (e.g. target thread is a Dummy-N boost::python frame), async_exc_skipped_reason explains why.

Namespace after interrupt: the YADE __main__ namespace is shared between tasks and yade_execute_code calls. Any variables the interrupted script had already defined — including O state — are preserved. There's no need to re-run the whole script to continue work: inspect state with yade_execute_code or resume via a fresh yade_execute_task that only runs the remaining logic.

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.