Documentation Authoring Guide

This page demonstrates the authoring primitives available across all three MSF documentation sub-sites (MICROROBOTICA, MADDENING, MIME).

---

LaTeX Mathematics

Inline math uses $…$ delimiters — e.g. the magnetic torque is \(\tau = \mathbf{m} \times \mathbf{B}\).

Block equations use $$…$$:

\[ \mathbf{F}_{\text{drag}} = -6\pi\,\eta\,r\,\mathbf{v} \]

For multi-line aligned equations use the \begin{align} environment:

\[\begin{split} \begin{align} \dot{\mathbf{q}} &= f(\mathbf{q}, \mathbf{u}) \\ \mathbf{y} &= h(\mathbf{q}) \end{align} \end{split}\]

---

Mermaid Diagrams

Use fenced mermaid code blocks anywhere in a Markdown file. The diagram is rendered client-side by the Mermaid JS library.

Node-graph topology

The example below mirrors the dejongh_confined experiment exactly (graph.json + physics/setup.py) — a useful template when writing your own node-graph diagrams.

        flowchart LR
    subgraph MIME["MIME node graph (dejongh_confined)"]
        direction LR
        Field[ExternalMagneticFieldNode<br/>field] -->|field_vector<br/>field_gradient| MagResp[PermanentMagnetResponseNode<br/>magnet]
        Body[RigidBodyNode<br/>body] -->|orientation| MagResp
        MagResp -->|magnetic_force<br/>magnetic_torque| Body
        Gravity[GravityNode<br/>gravity] -->|gravity_force| Body
        Body -->|position / vel / ω| MLP[MLPResistanceNode<br/>mlp_drag]
        MLP -->|resistance_matrix| Lub[LubricationCorrectionNode<br/>lub]
        Body -->|position / vel / ω| Lub
        Lub -->|drag_force<br/>drag_torque| Body
    end
    U1["external: frequency_hz"] -.-> Field
    U2["external: field_strength_mt"] -.-> Field
    

Sequence diagram

        sequenceDiagram
    participant IDE as MICROROBOTICA IDE
    participant RT  as MADDENING Runtime
    participant Sim as MIME simulation

    IDE->>RT: load_experiment(path)
    RT->>Sim: build_graph(config)
    Sim-->>RT: compiled_graph
    loop every frame
        IDE->>RT: step(dt)
        RT->>Sim: forward_pass()
        Sim-->>RT: outputs
        RT-->>IDE: render_frame(outputs)
    end
    

---

Code Snippets

Fenced code blocks get a copy button (top-right corner of the block) automatically. Shell prompts ($) are excluded from the copied text.

Python

from maddening import GraphManager
from mime.nodes.environment.external_magnetic_field import ExternalMagneticFieldNode
from mime.nodes.robot.permanent_magnet_response import PermanentMagnetResponseNode
from mime.nodes.robot.rigid_body import RigidBodyNode

# Minimal rotating-field → dipole-on-body graph
gm = GraphManager()
gm.add_node(ExternalMagneticFieldNode(name="field", timestep=5e-4))
gm.add_node(PermanentMagnetResponseNode(name="magnet", timestep=5e-4))
gm.add_node(RigidBodyNode(name="body", timestep=5e-4))

gm.add_edge("field", "magnet", "field_vector", "field_vector")
gm.add_edge("magnet", "body", "magnetic_torque", "magnetic_torque")

gm.compile()
final, history = gm.run_scan_with_history(n_steps=1000)
print(history["body"]["orientation"].shape)  # (1000, 4)

Shell

$ cd MADDENING
$ pip install -e ".[dev]"
$ pytest tests/ -x -q

YAML configuration

This is the shape of experiment.yaml files MIME experiments expose to MICROROBOTICA’s runner (see MIME/experiments/dejongh_confined/ for the live version):

schema_version: "1.0"
mime_version_min: "0.2.0"

physics:
  setup: physics/setup.py
  params: physics/params.py

control:
  controller: control/controller.py

scene:
  world: scene/world.usda
  actors:
    body:
      prim_path: /World/Actors/UMR
      prim_type: Mesh
      state_fields: [position, orientation]

---

Admonitions

Use MyST admonitions for tips, notes, warnings, and danger notices:

Note

This is a note — background context or supplementary information.

Tip

This is a tip — a recommended practice or efficiency hint.

Warning

This is a warning — something that could cause unexpected behaviour.

Important

This is an important notice — must-know information before proceeding.

---

Cross-project references

Use intersphinx to link across sub-sites:

See the :doc:`MADDENING node-authoring guide <maddening:developer_guide/node_authoring>`.

Or in Markdown:

See the [node authoring guide](maddening:developer_guide/node_authoring).