Debriefing vs Yade MCP

yade_browse_api

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.

yade_query_api

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

yade_execute_task

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.

yade_check_task_status

Check status and output for a submitted YADE task.

yade_list_tasks

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.

yade_interrupt_task

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.

yade_execute_code

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 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.