KDL to Python schematic migration

Convert an existing KDL schematic without silently changing its model or visual behavior. Establish parity before improving the generated Python.

Read the migration guide before making changes. Use examples/ball/schematic.py for basic builders and examples/display-kernels/schematic.py for expressions, schemas, and display kernels.

Rules

• Work from the repository root in nix develop.
• Use uv for every Python command.
• Run just install before testing so the CLI and Python extension match.
• Preserve the source KDL until the user explicitly approves deletion.
• Keep build() deterministic and side-effect-light.
• Preserve asset paths, ordering, names, queries, colors, and layout structure during the initial conversion.
• Do not redesign and migrate in the same step.
• Do not replace generated builders with embedded KDL or ui.from_kdl.
• Prefer --schematic; --kdl is deprecated.

Workflow

1. Inventory

Locate the root KDL, referenced KDL documents, relative assets, launch commands, and saved layout behavior. Record which database or simulation target can exercise representative live data.

Check whether the schematic contains display kernels or whether the migration is expected to introduce them. Kernel validation requires more than emitted KDL.

2. Generate

Keep the Python file beside the KDL initially:

elodin schematic to-python path/to/schematic.kdl \
  --output path/to/schematic.py

Inspect the generated module. It must import elodin.ui, define build() -> ui.Schematic, return ui.schematic(...), and retain its executable emit_kdl() block.

3. Validate the scaffold

Run the entry point:

uv run python path/to/schematic.py > /tmp/schematic.generated.kdl

Compare canonical models in Python:

from pathlib import Path

import elodin.ui as ui

from schematic import build


def canonical(schematic: ui.Schematic) -> ui.Schematic:
    return ui.from_kdl(schematic.emit_kdl())


source = ui.from_kdl(Path("schematic.kdl").read_text())
assert canonical(build()) == canonical(source)

When equality fails, isolate top-level sections in this order:

1. Root options.
2. Layout and tabs.
3. Views and their properties.
4. Scene objects.
5. Styling and colors.

Compare parsed models, not only raw KDL text.

4. Validate runtime behavior

Preload the schematic:

elodin editor <target> --schematic path/to/schematic.py

Then exercise live updates:

elodin ui watch path/to/schematic.py --db 127.0.0.1:2240

Capture the same representative state with the KDL and Python versions. Compare:

• Tabs, splits, active view, and panel sizing.
• Graph series, ranges, labels, and colors.
• Viewport objects, transforms, visibility, and assets.
• Lines, trails, arrows, coordinates, and world geometry.
• Runtime queries, warnings, and build diagnostics.
• Saved layout overlay behavior.

If the entry point imports sibling modules, verify imports and touch the watched entry point after changing a sibling if the watcher does not rebuild.

5. Refactor incrementally

Only after parity:

• Extract small helpers.
• Replace repeated builders with comprehensions or loops.
• Compose query strings with ui.Expr.
• Use ui.Schema when tensor shape and type matter.
• Add @ui.kernel only when a display transformation needs typed JAX math.

Re-run canonical and visual comparisons after each logical refactor. Keep intentional redesigns separate and document their expected differences.

6. Validate kernels and overlays

Plain emit_kdl() parity does not validate display-kernel sidecars. Test kernels through elodin ui watch or an explicit Python publish/write flow using the actual component shapes and primitive types.

The editor's Save Layout action writes an overlay KDL; it does not edit Python. Confirm that the watcher reapplies the active overlay. Copy desired default layout changes into Python manually.

7. Cut over

Update launch commands, examples, and documentation to use the Python path. Verify relative assets from the real launch environment. Retain the KDL as a rollback until all consumers have switched and the user approves removal.

Completion report

Report:

• Files converted and files intentionally retained.
• Canonical equality result and any intentional model differences.
• Runtime target and visual states tested.
• Asset, overlay, watcher, and kernel results.
• Refactors performed after parity.
• Commands run and remaining risks.