annotate-modelica-graphics

Annotate Modelica Graphics

This skill adds graphical annotations to a text-only Modelica .mo file so it renders as a clean schematic in Wolfram System Modeler. It is a self-contained source transform — it parses the .mo, classifies each class, and splices annotations back into the source:

• Category classes (packages, runnable examples, records, functions) get the idiomatic extends Modelica.Icons.*; base — the same icons the Modelica Standard Library uses.
• Leaf components / sub-circuit building blocks get a custom Icon(graphics=…) with their connectors anchored on the icon boundary. This works for any domain — connector detection spans every Modelica Standard Library domain (electrical, mechanical, rotational/translational, MultiBody, control signals, thermal/heat, fluid, magnetic, digital, …) plus any connector class defined in the file itself. Recognized component kinds get a hand-drawn glyph (transistor, amplifier, tank, pump, valve, pipe, heat capacitor); anything else gets a generic block placeholder that you are expected to replace with an icon you draw from the component's name and description (see step 3b — this is a normal part of the workflow, not an edge case).
• Connectors get their own domain-colored square icon. When the domain is recognized the color is automatic; when it isn't, you author the symbol the same way as for components.
• Composite models get an auto-laid-out Diagram: each component instance gets a Placement, and every connect(…) gets an orthogonal, domain-colored connection Line. A reference component shared by several components — one Ground that four parts connect to, one Fixed housing, one FixedTemperature ambient — is first given one instance per connection, so the diagram loses its star of long ground lines and each reference sits beside the component it anchors.

It is idempotent: re-running only fills in what is missing (use --force to regenerate). By default it prints a dry-run diff; nothing is written until you pass --write.

--force is destructive — ask the user first. It strips every Placement, connection Line, Icon(...), Diagram(...), and extends Modelica.Icons.* in scope and regenerates them from scratch. The tool leaves no marker, so it matches by shape, not provenance: hand-written and hand-tuned annotations are deleted too (custom placements, manual line routing, bespoke icon graphics). Do not pass --force on a model that may carry hand-authored graphics without first confirming with the user that discarding it is intended. Review the dry-run diff (no --write) to see exactly what would be removed before applying.

The engine is pure Python (standard library only) — no third-party packages or WSMKernelX are needed to generate the annotations. WSMKernelX is used only afterwards, as a safety gate, to confirm the edited file still flattens.