All docs
Engine
Engine runs pipelines in Python — ephemeral, from a .lsd file, or a project dir. Reference for add, run, save, load, and the RunResult it returns.
Engine is the runtime that executes pipelines outside the desktop — in a script, a test, or CI —
on the exact engine the desktop uses. It owns the workspace, the event bus, and the entity
collection, and orchestrates runs in dependency order. Construct it three ways — ephemeral
(in-memory), from a .lsd file, or from a project directory — then wire steps and call
run; runs are cached, so resume=True reuses unchanged steps.
Usage#
from lsdtools import Engine
result = Engine().run(top(numbers(count=6), limit=3))
result.output.print()
# → the final Table, with each step cached
Three ways to anchor an engine to a project:
Engine() # ephemeral: in-memory, nothing persisted
Engine("survey.lsd") # a single-file project
Engine("project_dir") # a directory-backed project
Entities run, views show#
An Engine holds two kinds of thing, and add takes either: entities you run and views you
show. The two verbs mirror each other exactly — run_all() executes every entity, show() presents
every attached view:
from lsdtools import Engine, views
engine = Engine()
engine.add(drillholes(collar="collars.csv", survey="survey.csv")) # an entity → run
grid = views.table(title="Assays").watch("drillholes") # a view that follows it
engine.add(grid) # a view → show
engine.run_all() # entities run in dependency order; the view holds the output
engine.show() # present every attached view (a window, or console text when headless)
engine.add(entity)attaches a pipeline;engine.add(view)attaches aView. Attaching a view also subscribes itswatchlinks to the bus, so a watch declared before either was added resolves right then.engine.viewslists the attached views;engine.view(name)fetches one;engine.remove_view(v)detaches it.show(mode="auto", title=None, block=True)opens one window hosting all views when a front-end is loaded, else prints each view's titled text rendering.run_all()/save()/load()are documented on their own pages below.
A deliver step that returns a ViewerPayload is routed to whatever view
watches its entity — so a run can populate a viewer with no extra wiring.
Where to start#
Learn — Node variants · Tables & data flow
Examples — Your first tool · Multi-output mesh
Class methods
- ephemeral creates an in-memory engine backed by a temp workspace
- load opens a saved project and returns an engine
Methods
- add adds an entity to the project and returns the engine for chaining
- diff lists steps whose parameters changed since the last run
- get fetches a previously added entity by name
- plan previews which steps a run would execute without running them
- run runs a target and returns its result
- run_all runs every entity in dependency order
- save persists the whole project to a .lsd file
- set_variant chooses which provider serves a node identity that has variants
- show presents every attached view — the show-side partner of run_all