MIME 0.3.0.dev1

MIME 0.3.0.dev1 is the first development release of MIME 0.3: a rewrite of MIME, the simulator for field-actuated medical
microrobots, built on top of MADDENING 0.4. It is a pre-release, so its API, its saved form and its results may change before 0.3.0.

pip install --pre mime-engine

A plain pip install mime-engine still installs 0.2.0. The examples and tutorials need a source checkout of this tag.

Why a rewrite

MIME 0.2 grew experiment by experiment. Each one was a script that wired MADDENING's nodes together by hand, so the physics of a run lived in the code that assembled it. Changing a drag model, adding a magnet or moving a vessel meant rewiring a graph. A result could not say which models produced it, under which assumptions, or whether it would come out the same on another machine. Those properties cannot be added to an existing codebase one at a time, so 0.3 starts again from what an experiment is. MADDENING 0.4 gives it the modular graph it needs underneath.

What it is built for

• Writable by an experimentalist. An experiment reads like a description of the bench: the bodies, the medium, the
  structures and the apparatus, the laws that act between them, and what you measure. You do not wire a graph.
  • Quantities carry units, and they are checked: a frequency in Hz is never taken for an angular velocity in rad/s.
  • A refusal names the line to change, often ready to paste, and has a page of its own.
• Truly modular. Every dynamics, interaction, field, observation and controller is a registered entry with a version.
  • Laws attach between parts, so swapping a drag model for another changes one line.
  • A lab adds its own entries through an entry point, as a plugin, without forking MIME.
• Reproducible. A saved experiment carries a lock that pins every entry, asset and environment by hash.
  • mime verify reruns its reference steps, bit for bit in the environment that saved it and within the lock's tolerances
    elsewhere.
  • mime pack, mime pull and mime push --to zenodo share an experiment as one bundle that others can check.
• Honest about its limits. Every entry declares the range it is valid over, and a run flags the steps that leave it.
  • Every value is either declared with its reason or taken from a stated default, and the build report says which.
  • Two profiles: exploratory asks for no paperwork; research asks for a reason for every value.
  • The scope page says what MIME claims and what it does not, and the known anomalies are public.

What's in it

• Physics. These are the entries in this release:
  • the rigid inertial body, gravity and buoyancy, and a contact that keeps a body inside its vessel;
  • magnetic torque and gradient force, a uniform rotating field, and a point-dipole magnet;
  • drag by the method of regularised Stokeslets, in free space and in a tube, with a surrogate rung beside it;
  • geometry from the sphere to the screw.
• Apparatus. Robot arms and motors as chains read from a URDF, with mounted magnets, and controllers in the loop, called back from Python or compiled into the step.
• Scenes and materials. The scene is a USD stage, and materials are read from OpenMaterica's records at the
  experiment's conditions.
• Results. Each observation's outputs come with their units, flags and post-run checks, and export to CSV, NPZ and
  MATLAB.
• Seeing a run:
  • live sessions over mime serve for viewers such as MICROROBOTICA;
  • recordings as USD layers;
  • a recording in the browser (mime visuals web <folder>, or mime.viz.display(folder) in a notebook), which zooms toward
    the pointer;
  • in a notebook, run and run_to show the live progress display.
• Assets by hash, with their licences. A file whose terms forbid hosting it is fetched from its owner, and never
  shipped.
• One command: mime (run, serve, verify, pack, pull, push, assets, visuals, docs, env check and
  more).
• Generated documentation: a page for every entry and every refusal, and tutorials that the tests run.

Before you start

• Development releases load no folder saved by another release, so keep the script that built a saved experiment.
• Saving a run (run_to, built.save) costs about ten seconds on a laptop and up to about two minutes on a Colab GPU,
  whatever the run's length. A cheaper save is planned.
• The MRS rung's tube experiments read a 209 MB table: fetch it once with mime assets fetch unit_tube_R0.997.
• A 0.2 script does not run unchanged. The migration table gives each 0.2 name its 0.3 entry.

The changelog has the whole
entry, including how to upgrade a 0.2 script. The documentation goes up at https://microrobotica.org/mime/0.3.0/ shortly
after this release.