Phase Tracking Node#

Module: mime.nodes.robot.phase_tracking Stability: experimental Algorithm ID: MIME-NODE-005 Version: 1.0.0 Verification Mode: Mode 2 (Independent)

Summary#

Observational node that computes the phase error between the robot’s magnetic moment direction and the external rotating field. Detects step-out when phase error exceeds pi/2.

Governing Equations#

Phase error: $$ \theta_{\text{err}} = \arccos(\hat{\mathbf{m}} \cdot \hat{\mathbf{B}}) $$

where $\hat{\mathbf{m}}$ is the robot’s body e1 axis rotated to the lab frame and $\hat{\mathbf{B}} = \mathbf{B}/|\mathbf{B}|$.

Step-out detection: $$ \text{stepped_out} = (\theta_{\text{err}} > \pi/2) $$

Discretization#

Analytical — instantaneous angle computation. No time integration.

Implementation Mapping#

Equation Term

Implementation

Notes

$\hat{\mathbf{m}} = R(\mathbf{q}) \hat{\mathbf{e}}_1$

mime.nodes.robot.phase_tracking.PhaseTrackingNode.update

rotate_vector(q, [1,0,0])

$\cos\theta = \hat{\mathbf{m}} \cdot \hat{\mathbf{B}}$

mime.nodes.robot.phase_tracking.PhaseTrackingNode.update

jnp.dot(m_hat, B_hat)

$\theta = \arccos(\cos\theta)$

mime.nodes.robot.phase_tracking.PhaseTrackingNode.update

jnp.arccos(jnp.clip(...))

Assumptions and Simplifications#

  1. Robot magnetic moment aligned with body e1 axis

  2. Step-out threshold is pi/2 (maximum torque angle)

  3. No phase error ODE — instantaneous detection only

Known Limitations and Failure Modes#

  1. No model of the asynchronous wobbling regime ($\omega > \omega_c$)

  2. arccos has poor gradient signal near 0 and pi — use cos_phase_error for optimization

  3. Zero field produces undefined phase error (clamped to safe value)

State Variables#

Field

Shape

Units

Description

phase_error

()

rad

Angle between m and B [0, pi]

cos_phase_error

()

-

cos(phase_error) — better for gradients

stepped_out

()

bool

True if phase_error > pi/2

Boundary Inputs#

Field

Shape

Default

Coupling Type

Description

orientation

(4,)

[1,0,0,0]

replacive

Quaternion from RigidBodyNode

field_vector

(3,)

zeros

replacive

B field from ExternalMagneticFieldNode

MIME-Specific Sections#

Clinical Relevance#

Step-out detection is critical for microrobot navigation safety. Loss of synchronisation means loss of directional control. The StepOutDetector feedback policy uses this node’s output to implement automatic frequency recovery.

References#

  • [@Abbott2009] Abbott, J.J. et al. (2009). How Should Microrobots Swim? — Step-out analysis and swimming strategy.

Verification Evidence#

  • Integration test: tests/nodes/test_integration.py (phase error tracking in coupled chain)

  • Unit tests: tests/nodes/test_phase_tracking.py (11 tests)

Changelog#

Version

Date

Change

1.0.0

2026-03-20

Initial implementation — phase error and step-out detection