Node variants

A variant is a step that stands in for another node's identity without editing the original package. You point at the target with overrides="pkg.node" and choose how they relate with override_mode. Recall that a node's identity is f"{tool_name}.{fn_name}" — that string is what a variant targets.

Usage#

from lsdtools import Tool, Table

tool = Tool("fastmath")

@tool.shape(overrides="stats.normalize", override_mode="replace")
def normalize(t: Table, column: str) -> Table:
    """A faster drop-in for stats.normalize — same identity, my code."""
    ...
# → wherever "stats.normalize" is used, this provider now runs

replace vs coexist#

• replace (the default) — your step wins the identity by default. Anywhere the target node is used, your implementation runs. Use it for a straight upgrade or a bug-fixed drop-in.
• coexist — the original and your step both stay available for the identity. Neither wins automatically; the user picks the active provider (in the Package Manager, or via the engine). Use it when both implementations are legitimately useful for different projects.

A real case: openpit's pit_shell#

The mim-openpit package offers a pit-specific solid that stands in for the base mim.solid node, but the generic solid stays useful — so it coexists rather than replaces:

from lsdtools import Tool, Table

tool = Tool("openpit", label="Open Pit")

@tool.shape(overrides="mim.solid", override_mode="coexist")
def pit_shell(t: Table, ramp_width: float = 30.0) -> Table:
    """An open-pit shell that coexists with mim.solid.
    The user chooses which provider builds the node."""
    ...

Both mim.solid and this openpit.pit_shell are then offered for the mim.solid identity — a project that never mines open pits simply leaves the default provider selected.

Choosing the active provider#

For a coexist identity, the desktop Package Manager shows a variants section where you pick the active provider per project. From Python, use Engine.set_variant:

from lsdtools import Engine

eng = Engine("mine.lsd")
eng.set_variant("mim.solid", mode="coexist", provider="openpit.pit_shell")

The choice is project-scoped, so different projects on the same install can resolve the same identity to different providers.

Related#

Learn — The Tool object · Entity types · The Package Manager

API — Tool · Engine · Table

Examples — A node variant · A complete package