Python API

Generated from source code. Public classes, methods, and functions are shown as a compact reference with signatures, parameters, returns, notes, and coverage.

ember.edu

class

Accumulation

class Accumulation(key: str, max_val: float = 100.0, label: str = 'Storage')

Generalises Storage, Tanks, Batteries, Population, Capital.

Parameters
key: str, max_val: float = 100.0, label: str = 'Storage'
Returns
Instance of Accumulation.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Accumulation.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a rectangular tank filled proportionally to key / max_val, coloured grey-to-blue with the fill level.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Balance

class Balance(left_key: str, right_key: str, labels: Tuple[str, str])

Generalises Equilibrium, Equations, Supply/Demand, Scales.

Parameters
left_key: str, right_key: str, labels: Tuple[str, str]
Returns
Instance of Balance.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Balance.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a tilting balance beam with red/green pans scaled by left_key and right_key state values.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

ConcentrationGrid

class ConcentrationGrid(width: int = 60, height: int = 40, model: str = 'diffusion', D: float = 0.18, kill: float = 0.06, feed: float = 0.04, label: str = 'Concentration', source_key: Optional[str] = None)

2D reaction-diffusion / heat field. The grid is updated in update().

Parameters
width: int = 60, height: int = 40, model: str = 'diffusion', D: float = 0.18, kill: float = 0.06, feed: float = 0.04, label: str = 'Concentration', source_key: Optional[str] = None
Returns
Instance of ConcentrationGrid.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ConcentrationGrid.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Renders the V (or U for pure diffusion) concentration field as a 24-level contour heatmap inside the panel.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ConcentrationGrid.update

update(self, dt: float, state: State)

Runs two steps of the diffusion or Gray-Scott reaction-diffusion PDE on the U/V concentration grids.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Concept

class Concept()

Abstract base for all visual simulation concepts shown inside a Lesson panel.

Parameters
No inputs.
Returns
Instance of Concept.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Concept.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws the rounded panel background that every concept sits inside.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Concept.update

update(self, dt: float, state: State)

No-op base implementation; subclasses override to advance internal animation state.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Diagram

class Diagram(nodes: Union[Sequence[Any], Callable[[State], Sequence[Any]]], links: Union[Sequence[Any], Callable[[State], Sequence[Any]]] = (), layout: str = 'auto', direction: str = 'lr', label: str = 'Diagram', flow: bool = True, time_key: str = '_time')

Coordinate-free node/link diagram.

Parameters
nodes: Union[Sequence[Any], Callable[[State], Sequence[Any]]], links: Union[Sequence[Any], Callable[[State], Sequence[Any]]] = (), layout: str = 'auto', direction: str = 'lr', label: str = 'Diagram', flow: bool = True, time_key: str = '_time'
Returns
Instance of Diagram.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Diagram.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a coordinate-free node/link diagram using ShapeCanvas.diagram with current nodes and links from state.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Diagram.update

update(self, dt: float, state: State)

Increments the local animation timer t by dt for flow animation on diagram links.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
class

EnergyDiagram

class EnergyDiagram(states: List[Dict[str, Any]], barriers: Optional[List[float]] = None, label: str = 'Energy Diagram', progress_key: Optional[str] = None)

Reaction-coordinate / potential-energy diagram.

Parameters
states: List[Dict[str, Any]], barriers: Optional[List[float]] = None, label: str = 'Energy Diagram', progress_key: Optional[str] = None
Returns
Instance of EnergyDiagram.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

EnergyDiagram.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws energy-level plateaus connected by Bezier activation-energy humps with an optional reaction-progress marker.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
class

Flow

class Flow(rate_key: str, label: str = 'Flow')

Generalises Current, Water, Traffic, Money, Information.

Parameters
rate_key: str, label: str = 'Flow'
Returns
Instance of Flow.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Flow.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a horizontal pipe with animated glowing particles whose speed reflects the rate_key value.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Flow.update

update(self, dt: float, state: State)

Advances the particle-phase offset t by the current flow rate, driving animation speed.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

GraphViz

class GraphViz(nodes_fn: Callable[[State], List[Any]], edges_fn: Callable[[State], List[Tuple[int, int]]], layout: str = 'force', label: str = 'Graph', highlight_fn: Optional[Callable[[State], List[int]]] = None)

Animated graph: search frontier, dependencies, social network.

Parameters
nodes_fn: Callable[[State], List[Any]], edges_fn: Callable[[State], List[Tuple[int, int]]], layout: str = 'force', label: str = 'Graph', highlight_fn: Optional[Callable[[State], List[int]]] = None
Returns
Instance of GraphViz.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

GraphViz.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws the graph from nodes_fn/edges_fn using draw_network, then adds a gold glow to any highlighted nodes.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

HeatMap

class HeatMap(rows: List[str], cols: List[str], value_fn: Callable[[int, int, State], float], label: str = 'Heat Map', focus_key: Optional[str] = None)

Generalises weighted matrices: attention, risk, similarity, demand.

Parameters
rows: List[str], cols: List[str], value_fn: Callable[[int, int, State], float], label: str = 'Heat Map', focus_key: Optional[str] = None
Returns
Instance of HeatMap.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

HeatMap.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a colour-coded grid of cells where each cell's hue maps the value_fn output to a teal-to-blue scale.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Interaction

class Interaction(items: List[str], weight_fn: Callable[[int, int, State], float], layout: str = 'line', label: str = 'Interactions', focus_key: str = '_focus')

Generalises Attention, Connectivity, Weighted Relationships.

Parameters
items: List[str], weight_fn: Callable[[int, int, State], float], layout: str = 'line', label: str = 'Interactions', focus_key: str = '_focus'
Returns
Instance of Interaction.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Interaction.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws items with weighted connection arcs; connections involving focus_key are highlighted with animated dots.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Interaction.update

update(self, dt: float, state: State)

Advances t to animate particles travelling along the highlighted connection arcs.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

Lesson

class Lesson(title: str, theme: str = 'midnight')

The Universal Orchestrator.

Parameters
title: str, theme: str = 'midnight'
Returns
Instance of Lesson.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.challenge

challenge(self, target: Dict[str, float], tolerance: float = 0.1, message: str = 'Goal Reached!') -> 'Lesson'

Add a goal.

Parameters
target: Dict[str, float], tolerance: float = 0.1, message: str = 'Goal Reached!'
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.clock

clock(self, name: str = '_time', speed: float = 1.0) -> 'Lesson'

Add a monotonically increasing time value for animation.

Parameters
name: str = '_time', speed: float = 1.0
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.explain

explain(self, fn: Union[str, Callable[[], str]]) -> 'Lesson'

Add a dynamic explanation.

Parameters
fn: Union[str, Callable[[], str]]
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.input

input(self, name: str, min: float, max: float, default: float, unit: str = '', keys: Tuple[str, str] = ('w', 's')) -> 'Lesson'

Define an interactive parameter.

Parameters
name: str, min: float, max: float, default: float, unit: str = '', keys: Tuple[str, str] = ('w', 's')
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.model

model(self, rules: Dict[str, Callable[[State], Any]] = {}, rates: Dict[str, Callable[[State], float]] = {}) -> 'Lesson'

Batch define rules and rates.

Parameters
rules: Dict[str, Callable[[State], Any]] = {}, rates: Dict[str, Callable[[State], float]] = {}
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.rate

rate(self, name: str, fn: Callable[[State], float]) -> 'Lesson'

Define a rate of change (Integration).

Parameters
name: str, fn: Callable[[State], float]
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.record

record(self, seconds: float, filename: str, fps: int = 20)

Headless export to animated GIF.

Parameters
seconds: float, filename: str, fps: int = 20
Returns
Not specified.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.rule

rule(self, name: str, fn: Callable[[State], Any]) -> 'Lesson'

Define a derived property.

Parameters
name: str, fn: Callable[[State], Any]
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.run

run(self)

Opens an interactive Tk window with a fixed-timestep loop driven by _update and _render.

Parameters
No inputs.
Returns
Not specified.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.show

show(self, concept: Concept) -> 'Lesson'

Add a visual concept.

Parameters
concept: Concept
Returns
'Lesson'
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Lesson.stage

stage(self, name: str, setup_fn: Optional[Callable] = None) -> Union['Lesson', Callable]

Define a narrative stage. Can be used as a decorator.

Parameters
name: str, setup_fn: Optional[Callable] = None
Returns
Union['Lesson', Callable]
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
class

Mapping

class Mapping(x_label: str, y_label: str, fn: Callable[[float, State], float], x_range: Tuple[float, float] = (0, 10), y_range: Tuple[float, float] = (0, 10))

Generalises Graphs, Maps, Coordinate Systems.

Parameters
x_label: str, y_label: str, fn: Callable[[float, State], float], x_range: Tuple[float, float] = (0, 10), y_range: Tuple[float, float] = (0, 10)
Returns
Instance of Mapping.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Mapping.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Plots the function fn over x_range using a Plot with labelled axes for x_label and y_label.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

MoleculeViz

class MoleculeViz(formula_or_atoms, bonds: Optional[List[Tuple[int, int, int]]] = None, style: str = 'ball-stick', label: Optional[str] = None, speed: float = 30.0)

Ball-and-stick 3D molecule.

Parameters
formula_or_atoms, bonds: Optional[List[Tuple[int, int, int]]] = None, style: str = 'ball-stick', label: Optional[str] = None, speed: float = 30.0
Returns
Instance of MoleculeViz.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

MoleculeViz.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Builds a 3D ball-and-stick molecule from atoms and bonds and embeds it with an auto-rotating camera.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

MoleculeViz.update

update(self, dt: float, state: State)

Advances t to continuously spin the camera yaw around the molecule.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
class

Network

class Network(nodes: List[str], edges: List[Tuple[str, str]], label: str = 'System Network')

Generalises Graphs, Social Connections, Grids, Disease spread.

Parameters
nodes: List[str], edges: List[Tuple[str, str]], label: str = 'System Network'
Returns
Instance of Network.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Network.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws nodes arranged in a ring with circle sizes and colours proportional to each node's state value.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Orbit

class Orbit(mesh_fn: Callable, speed: float = 30.0, distance: float = 5.0, label: str = '3D')

Rotating 3D scene built from a user-supplied builder function.

Parameters
mesh_fn: Callable, speed: float = 30.0, distance: float = 5.0, label: str = '3D'
Returns
Instance of Orbit.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Orbit.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Calls mesh_fn to populate a Scene3D each frame, then embeds it under an auto-orbiting perspective camera.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Orbit.update

update(self, dt: float, state: State)

Advances t to drive the yaw rotation of the orbiting camera around the user-built 3D scene.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
class

PhasePlane

class PhasePlane(dx_fn: Callable, dy_fn: Callable, x_range: Tuple[float, float] = (-3, 3), y_range: Tuple[float, float] = (-3, 3), state_keys: Optional[Tuple[str, str]] = None, resolution: int = 12, label: str = 'Phase Plane')

Phase portrait of a 2D ODE: arrows of (dx/dt, dy/dt) + state trajectory.

Parameters
dx_fn: Callable, dy_fn: Callable, x_range: Tuple[float, float] = (-3, 3), y_range: Tuple[float, float] = (-3, 3), state_keys: Optional[Tuple[str, str]] = None, resolution: int = 12, label: str = 'Phase Plane'
Returns
Instance of PhasePlane.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

PhasePlane.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a vector field of (dx_fn, dy_fn) arrows on a grid with the accumulated state trajectory overlaid.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

PhasePlane.update

update(self, dt: float, state: State)

Appends the current (x_var, y_var) point from state to the trajectory trail, capped at 240 points.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

Pipeline

class Pipeline(stages: List[Union[str, Tuple[str, Sequence[int]]]], active_key: Optional[str] = None, label: str = 'Process Pipeline')

Generalises staged processes: workflows, model blocks, value chains.

Parameters
stages: List[Union[str, Tuple[str, Sequence[int]]]], active_key: Optional[str] = None, label: str = 'Process Pipeline'
Returns
Instance of Pipeline.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Pipeline.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a row of coloured stage boxes with an animated dot and glow highlighting the currently active stage.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Pipeline.update

update(self, dt: float, state: State)

Advances the internal timer t so the active-stage highlight travels through pipeline stages.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Scene

class Scene(draw_fn: Callable[[Schematic, State, int, int], None])

Direct bridge to the low-level Ember engine.

Parameters
draw_fn: Callable[[Schematic, State, int, int], None]
Returns
Instance of Scene.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Delegates drawing to the user-supplied draw_fn via a Schematic centred in the panel.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
class

SemanticScene

class SemanticScene(objects: Union[Sequence[Any], Callable[[State], Sequence[Any]]], relations: Union[Sequence[Any], Callable[[State], Sequence[Any]]] = (), layout: str = 'roles', direction: str = 'lr', label: str = 'Scene', time_key: str = '_time')

Role-based visual scene that owns geometry, paths, and glyph sizing.

Parameters
objects: Union[Sequence[Any], Callable[[State], Sequence[Any]]], relations: Union[Sequence[Any], Callable[[State], Sequence[Any]]] = (), layout: str = 'roles', direction: str = 'lr', label: str = 'Scene', time_key: str = '_time'
Returns
Instance of SemanticScene.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

SemanticScene.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws the role-based semantic scene by delegating to ShapeCanvas.scene with resolved objects and relations.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

SemanticScene.update

update(self, dt: float, state: State)

Increments the local timer t used to animate object motion and relation flow in the scene.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
class

ShapeCanvas

class ShapeCanvas(r: Premium2D, x: int, y: int, w: int, h: int)

Normalized drawing helper for lively diagrams and organic shapes.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int
Returns
Instance of ShapeCanvas.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

ShapeCanvas.arrow

arrow(self, *args, label: str = '', width: int = 2, alpha: int = 200) -> None

Directed arrow supporting tuple and coordinate call styles.

Parameters
args, label: str = '', width: int = 2, alpha: int = 200
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
method

ShapeCanvas.badge

badge(self, *args, size: float = 0.05, alpha: Optional[int] = None) -> None

Status badge supporting both historical call styles.

Parameters
args, size: float = 0.05, alpha: Optional[int] = None
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
method

ShapeCanvas.blob

blob(self, points: Sequence[Tuple[float, float]], color: Sequence[int], label: str = '', alpha: int = 220, pulse: float = 0.0, outline: Optional[Sequence[int]] = None) -> None

Draws a Catmull-Rom smoothed closed polygon with a glow halo, pulsed outward by the pulse factor.

Parameters
points: Sequence[Tuple[float, float]], color: Sequence[int], label: str = '', alpha: int = 220, pulse: float = 0.0, outline: Optional[Sequence[int]] = None
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.circle

circle(self, x: float, y: float, r: float = 0.12, color: Sequence[int] = (90, 120, 180), label: str = '', pulse: float = 0.0, alpha: int = 220) -> None

Uniform circle. Shorthand for oval(x, y, r, r, …).

Parameters
x: float, y: float, r: float = 0.12, color: Sequence[int] = (90, 120, 180), label: str = '', pulse: float = 0.0, alpha: int = 220
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.diagram

diagram(self, nodes: Sequence[Any], links: Sequence[Any] = (), t: float = 0.0, layout: str = 'auto', direction: str = 'lr', flow: bool = True, node_shape: str = 'rect', link_color: Sequence[int] = (90, 110, 140)) -> Dict[str, Point]

Draw a coordinate-free node/link diagram and return its positions.

Parameters
nodes: Sequence[Any], links: Sequence[Any] = (), t: float = 0.0, layout: str = 'auto', direction: str = 'lr', flow: bool = True, node_shape: str = 'rect', link_color: Sequence[int] = (90, 110, 140)
Returns
Dict[str, Point]
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

ShapeCanvas.flow

flow(self, points: Sequence[Tuple[float, float]], color: Sequence[int], t: float, count: int = 10, speed: float = 0.28, width: int = 8, alpha: int = 130) -> None

Draws a path with animated glowing dots marching along it at positions driven by t and speed.

Parameters
points: Sequence[Tuple[float, float]], color: Sequence[int], t: float, count: int = 10, speed: float = 0.28, width: int = 8, alpha: int = 130
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

ShapeCanvas.grid

grid(self, x: float, y: float, cols: int, rows: int, cells: Sequence[Tuple[Sequence[int], str]], w: float = 0.55, h: float = 0.18, label: str = '') -> None

Generic 2-D grid. cells = [(color, short_label), …].

Parameters
x: float, y: float, cols: int, rows: int, cells: Sequence[Tuple[Sequence[int], str]], w: float = 0.55, h: float = 0.18, label: str = ''
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
method

ShapeCanvas.layout

layout(self, nodes: Sequence[Any], links: Sequence[Any] = (), mode: str = 'auto', direction: str = 'lr') -> Dict[str, Point]

Return normalized positions for named nodes.

Parameters
nodes: Sequence[Any], links: Sequence[Any] = (), mode: str = 'auto', direction: str = 'lr'
Returns
Dict[str, Point]
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

ShapeCanvas.line

line(self, points: Sequence[Tuple[float, float]], color: Sequence[int], width: int = 3, alpha: int = 210, smooth: bool = True) -> None

Draws an open polyline through normalised points, optionally smoothed with Catmull-Rom interpolation.

Parameters
points: Sequence[Tuple[float, float]], color: Sequence[int], width: int = 3, alpha: int = 210, smooth: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.orbital

orbital(self, x: float, y: float, dx: float, dy: float, length: float, width: float, color: Sequence[int], label: str = '', alpha: int = 220, pulse: float = 0.0) -> None

Draws a teardrop-shaped orbital lobe extending in direction (dx, dy) from (x, y).

Parameters
x: float, y: float, dx: float, dy: float, length: float, width: float, color: Sequence[int], label: str = '', alpha: int = 220, pulse: float = 0.0
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.oval

oval(self, x: float, y: float, rx: float, ry: float, color: Sequence[int], label: str = '', alpha: int = 220, pulse: float = 0.0) -> None

Draws a glowing ellipse at normalised position (x, y) with semi-axes rx/ry scaled by pulse.

Parameters
x: float, y: float, rx: float, ry: float, color: Sequence[int], label: str = '', alpha: int = 220, pulse: float = 0.0
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.pt

pt(self, x: Union[float, Tuple[float, float]], y: Optional[float] = None) -> Point

Converts normalised canvas coordinates (−1..1) to absolute screen pixels.

Parameters
x: Union[float, Tuple[float, float]], y: Optional[float] = None
Returns
Point
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.rect

rect(self, x: float, y: float, w: float = 0.18, h: float = 0.12, color: Sequence[int] = (90, 120, 180), label: str = '', radius: float = 0.22, pulse: float = 0.0, alpha: int = 220) -> None

Rounded rectangle. Use for any discrete block: hardware component,

Parameters
x: float, y: float, w: float = 0.18, h: float = 0.12, color: Sequence[int] = (90, 120, 180), label: str = '', radius: float = 0.22, pulse: float = 0.0, alpha: int = 220
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

ShapeCanvas.route

route(self, positions: Dict[str, Point], start: str, end: str, direction: str = 'auto', pad: float = 0.14) -> List[Point]

Return a routed path between two node ids in a layout map.

Parameters
positions: Dict[str, Point], start: str, end: str, direction: str = 'auto', pad: float = 0.14
Returns
List[Point]
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

ShapeCanvas.scene

scene(self, objects: Sequence[Any], relations: Sequence[Any] = (), t: float = 0.0, layout: str = 'roles', direction: str = 'lr') -> Dict[str, Point]

Render a semantic scene from roles, glyphs, motion, and relations.

Parameters
objects: Sequence[Any], relations: Sequence[Any] = (), t: float = 0.0, layout: str = 'roles', direction: str = 'lr'
Returns
Dict[str, Point]
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

ShapeCanvas.text

text(self, text: str, x: float, y: float, color: Optional[Sequence[int]] = None, bold: bool = False, anchor: str = 'mm') -> None

Draws a text label at normalised canvas position (x, y) using the theme colour if none is given.

Parameters
text: str, x: float, y: float, color: Optional[Sequence[int]] = None, bold: bool = False, anchor: str = 'mm'
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
class

Sketch

class Sketch(draw_fn: Callable[[ShapeCanvas, State], None], label: str = '')

Canvas concept for shape-first simulations with compact drawing code.

Parameters
draw_fn: Callable[[ShapeCanvas, State], None], label: str = ''
Returns
Instance of Sketch.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Sketch.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Calls draw_fn with a fresh ShapeCanvas so user drawing code runs inside the allocated panel rect.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

SlotCanvas

class SlotCanvas(canvas: ShapeCanvas) -> None

ShapeCanvas wrapper with named-slot positioning.

Parameters
canvas: ShapeCanvas
Returns
Instance of SlotCanvas.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

SlotCanvas.arrow

arrow(self, src: str, dst: str, color: Sequence[int], **kwargs) -> None

Draw a directed arrow between two named slots.

Parameters
src: str, dst: str, color: Sequence[int], kwargs
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

SlotCanvas.badge_at

badge_at(self, name: str, text: str, color: Sequence[int], dy: float = -0.18, **kwargs) -> None

Draw a badge near a named slot.

Parameters
name: str, text: str, color: Sequence[int], dy: float = -0.18, kwargs
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

SlotCanvas.define

define(self, name: str, x: float, y: float) -> None

Register a custom slot at normalised position (x, y).

Parameters
name: str, x: float, y: float
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

SlotCanvas.flow

flow(self, path: str, color: Sequence[int], t: float, **kwargs) -> None

Animate marching dots along a path of named slots.

Parameters
path: str, color: Sequence[int], t: float, kwargs
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

SlotCanvas.grid

grid(self, n: int, direction: str = 'h') -> List[str]

Return n evenly spaced slot names and register their positions.

Parameters
n: int, direction: str = 'h'
Returns
List[str]
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

SlotCanvas.label

label(self, name: str, text: str, dy: float = -0.18, **kwargs) -> None

Draw a text annotation above/below a named slot.

Parameters
name: str, text: str, dy: float = -0.18, kwargs
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

SlotCanvas.line

line(self, path: str, color: Sequence[int], **kwargs) -> None

Draw a static line through named slots: ``c.line('top->bottom', color)``.

Parameters
path: str, color: Sequence[int], kwargs
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
method

SlotCanvas.slot

slot(self, name: str, kind: str = 'rect', **kwargs) -> None

Draw a primitive at the named slot position.

Parameters
name: str, kind: str = 'rect', kwargs
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
class

SlotSketch

class SlotSketch(draw_fn: Callable[['SlotCanvas', State], None], label: str = '') -> None

Sketch variant where draw_fn receives a SlotCanvas instead of ShapeCanvas.

Parameters
draw_fn: Callable[['SlotCanvas', State], None], label: str = ''
Returns
Instance of SlotSketch.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

SlotSketch.render

render(self, r: 'Premium2D', x: int, y: int, w: int, h: int, state: State) -> None

Calls draw_fn with a SlotCanvas so slot-based drawing runs inside the panel rect.

Parameters
r: 'Premium2D', x: int, y: int, w: int, h: int, state: State
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

State

class State(params: Dict[str, float] = <factory>, derived: Dict[str, Any] = <factory>) -> None

Reactive state container.

Parameters
params: Dict[str, float] = <factory>, derived: Dict[str, Any] = <factory>
Returns
Instance of State.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Surface3D

class Surface3D(fn: Callable, x_range: Tuple[float, float] = (-3, 3), z_range: Tuple[float, float] = (-3, 3), resolution: int = 16, label: str = 'Surface', colormap: Tuple[Sequence[int], Sequence[int]] = ((40, 60, 140), (255, 200, 60)), speed: float = 30.0)

Animated mathematical surface z = fn(x, y, t, state).

Parameters
fn: Callable, x_range: Tuple[float, float] = (-3, 3), z_range: Tuple[float, float] = (-3, 3), resolution: int = 16, label: str = 'Surface', colormap: Tuple[Sequence[int], Sequence[int]] = ((40, 60, 140), (255, 200, 60)), speed: float = 30.0
Returns
Instance of Surface3D.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Surface3D.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Builds a triangulated z = fn(x, y, t, state) mesh with colormap shading and embeds it via an auto-orbiting camera.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Surface3D.update

update(self, dt: float, state: State)

Advances t to continuously rotate the camera around the surface mesh.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
class

Table

class Table(keys: List[str], label: str = 'Data Overview')

Generalises Spreadsheets, Data views, Scoreboards.

Parameters
keys: List[str], label: str = 'Data Overview'
Returns
Instance of Table.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Table.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a horizontal bar chart where each row shows a key's current state value normalised to the row max.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

Timeline

class Timeline(events: List[Dict[str, Any]], label: str = 'Timeline', time_key: Optional[str] = None, t_range: Optional[Tuple[float, float]] = None)

Horizontal timeline. events: [{"t": float, "name": str, "color": (r,g,b)}].

Parameters
events: List[Dict[str, Any]], label: str = 'Timeline', time_key: Optional[str] = None, t_range: Optional[Tuple[float, float]] = None
Returns
Instance of Timeline.
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
method

Timeline.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a horizontal axis with labelled event markers and an optional gold scrubber from time_key.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Transform

class Transform(in_key: str, out_key: str, label: str = 'Process')

Generalises Conversion, Processing, Reactions, Metabolism.

Parameters
in_key: str, out_key: str, label: str = 'Process'
Returns
Instance of Transform.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Transform.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws a gear icon flanked by labelled input and output arrows representing the in_key → out_key conversion.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
class

TreeViz

class TreeViz(root_fn: Callable[[State], Dict[str, Any]], label: str = 'Tree', color: Sequence[int] = (110, 200, 255))

Animated tree: BST, DOM, parse tree, etc.

Parameters
root_fn: Callable[[State], Dict[str, Any]], label: str = 'Tree', color: Sequence[int] = (110, 200, 255)
Returns
Instance of TreeViz.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

TreeViz.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws the tree returned by root_fn as glowing ellipse nodes connected by edge lines, laid out top-down.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

VectorField3D

class VectorField3D(fn: Callable, extent: float = 3.0, resolution: int = 4, scale: float = 0.4, color: Sequence[int] = (90, 190, 255), label: str = 'Vector Field', speed: float = 24.0)

3D arrow grid sampled from fn(x,y,z, state) → (vx, vy, vz).

Parameters
fn: Callable, extent: float = 3.0, resolution: int = 4, scale: float = 0.4, color: Sequence[int] = (90, 190, 255), label: str = 'Vector Field', speed: float = 24.0
Returns
Instance of VectorField3D.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

VectorField3D.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Samples fn on a 3D lattice and draws scaled 3D arrows from each grid point, embedded in an orbiting camera.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

VectorField3D.update

update(self, dt: float, state: State)

Advances t to continuously orbit the camera around the 3D arrow grid.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
class

Waveform

class Waveform(waves: List[Dict[str, Any]], x_range: Tuple[float, float] = (0.0, 6.28), y_range: Tuple[float, float] = (-2.5, 2.5), label: str = 'Wave', show_components: bool = True)

Travelling / standing wave: superposition of sinusoids.

Parameters
waves: List[Dict[str, Any]], x_range: Tuple[float, float] = (0.0, 6.28), y_range: Tuple[float, float] = (-2.5, 2.5), label: str = 'Wave', show_components: bool = True
Returns
Instance of Waveform.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Waveform.render

render(self, r: Premium2D, x: int, y: int, w: int, h: int, state: State)

Draws individual sinusoidal components as faint coloured lines, then their bright teal superposition.

Parameters
r: Premium2D, x: int, y: int, w: int, h: int, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Waveform.update

update(self, dt: float, state: State)

Advances t so that wave components with a non-zero speed parameter appear to travel over time.

Parameters
dt: float, state: State
Returns
Not specified.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.

ember.sim

class

Scene3DBundle

class Scene3DBundle(title: str, builder: Callable[['object', float], None], theme: str = 'midnight', distance: float = 5.0, speed: float = 30.0, width: int = 960, height: int = 540) -> None

Light wrapper around a Scene3D with a Lesson-compatible run/record API.

Parameters
title: str, builder: Callable[['object', float], None], theme: str = 'midnight', distance: float = 5.0, speed: float = 30.0, width: int = 960, height: int = 540
Returns
Instance of Scene3DBundle.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3DBundle.record

record(self, seconds: float = 5.0, filename: str = 'scene3d.gif', fps: int = 20) -> str

Renders the scene headlessly for the given duration and saves an animated GIF, returning the filename.

Parameters
seconds: float = 5.0, filename: str = 'scene3d.gif', fps: int = 20
Returns
str
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3DBundle.run

run(self) -> None

Opens an interactive Tk window that continuously orbits the camera and calls builder each frame.

Parameters
No inputs.
Returns
None
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
function

SemanticScene3D

SemanticScene3D(title: str, objects: List[dict], relations: List[dict] = (), theme: str = 'midnight', distance: Optional[float] = None, speed: float = 20.0) -> Scene3DBundle

3D scene where positions are computed from roles, not coordinates.

Parameters
title: str, objects: List[dict], relations: List[dict] = (), theme: str = 'midnight', distance: Optional[float] = None, speed: float = 20.0
Returns
Scene3DBundle
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
function

circuit

circuit(title: str = 'DC circuit', elements: Optional[List[Tuple[str, float]]] = None) -> Lesson

Series of resistors / capacitors from element list.

Parameters
title: str = 'DC circuit', elements: Optional[List[Tuple[str, float]]] = None
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

crystal_3d

crystal_3d(structure: str = 'NaCl', repeats: Tuple[int, int, int] = (2, 2, 2), title: Optional[str] = None) -> Scene3DBundle

Ionic / metallic crystal lattice. structures: NaCl / FCC / BCC / diamond.

Parameters
structure: str = 'NaCl', repeats: Tuple[int, int, int] = (2, 2, 2), title: Optional[str] = None
Returns
Scene3DBundle
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
function

diffusion

diffusion(title: str = "Fick's law diffusion", particles: int = 200, D: float = 0.2) -> Lesson

Diffusion in a 2D grid with interactive diffusivity.

Parameters
title: str = "Fick's law diffusion", particles: int = 200, D: float = 0.2
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

ecology

ecology(title: str = 'Predator-prey', species: Optional[dict] = None, interactions: Optional[List[Tuple[str, str, float]]] = None) -> Lesson

Lotka-Volterra two-species ODE.

Parameters
title: str = 'Predator-prey', species: Optional[dict] = None, interactions: Optional[List[Tuple[str, str, float]]] = None
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

epidemic

epidemic(title: str = 'SIR epidemic', model: str = 'SIR', N: float = 1000.0, beta: float = 0.3, gamma: float = 0.1) -> Lesson

SIR or SEIR compartment model with R₀ slider.

Parameters
title: str = 'SIR epidemic', model: str = 'SIR', N: float = 1000.0, beta: float = 0.3, gamma: float = 0.1
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

loss_surface

loss_surface(fn: Optional[Callable] = None, title: str = 'Loss surface', x_range: Tuple[float, float] = (-3, 3), y_range: Tuple[float, float] = (-3, 3), start: Tuple[float, float] = (-2.5, 2.3), lr: float = 0.06) -> Scene3DBundle

3D loss landscape with animated gradient-descent trajectory.

Parameters
fn: Optional[Callable] = None, title: str = 'Loss surface', x_range: Tuple[float, float] = (-3, 3), y_range: Tuple[float, float] = (-3, 3), start: Tuple[float, float] = (-2.5, 2.3), lr: float = 0.06
Returns
Scene3DBundle
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
function

market

market(title: str = 'Supply / demand', demand_fn: Callable[[float], float] = <lambda>, supply_fn: Callable[[float], float] = <lambda>, tax: float = 0.0) -> Lesson

Linear (or custom) supply/demand with optional tax.

Parameters
title: str = 'Supply / demand', demand_fn: Callable[[float], float] = <lambda>, supply_fn: Callable[[float], float] = <lambda>, tax: float = 0.0
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

molecule_3d

molecule_3d(formula_or_atoms, bonds: Optional[List[Tuple[int, int, int]]] = None, style: str = 'ball-stick', title: Optional[str] = None) -> Scene3DBundle

Rotating ball-and-stick molecule. Pass IUPAC-style preset key or atoms list.

Parameters
formula_or_atoms, bonds: Optional[List[Tuple[int, int, int]]] = None, style: str = 'ball-stick', title: Optional[str] = None
Returns
Scene3DBundle
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
function

neural_layer

neural_layer(title: str = 'Neural layer', shape: Tuple[int, ...] = (4, 3, 2)) -> Lesson

Forward pass through a fixed MLP.

Parameters
title: str = 'Neural layer', shape: Tuple[int, ...] = (4, 3, 2)
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

orbital_3d

orbital_3d(orbital: str = '2pz', title: Optional[str] = None) -> Scene3DBundle

Hydrogen-like orbital isosurface (1s / 2s / 2p / 3d_z2 ...).

Parameters
orbital: str = '2pz', title: Optional[str] = None
Returns
Scene3DBundle
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
function

pendulum

pendulum(title: str = 'Pendulum', kind: str = 'simple', n: int = 1) -> Lesson

Simple, double, or coupled pendulum.

Parameters
title: str = 'Pendulum', kind: str = 'simple', n: int = 1
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

protein_fold

protein_fold(sequence: str = 'MAVK') -> Scene3DBundle

Coarse-grained protein backbone visualised as a tube/ribbon.

Parameters
sequence: str = 'MAVK'
Returns
Scene3DBundle
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

reaction

reaction(title: str = 'Arrhenius reaction', reactants: str = 'A', products: str = 'B', Ea: float = 50.0, temp_range: Tuple[float, float] = (200.0, 1000.0)) -> Lesson

First-order reaction rate vs. temperature.

Parameters
title: str = 'Arrhenius reaction', reactants: str = 'A', products: str = 'B', Ea: float = 50.0, temp_range: Tuple[float, float] = (200.0, 1000.0)
Returns
Lesson
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
function

record_gif

record_gif(scene: Any, filename: str = 'out.gif', seconds: float = 5.0, fps: int = 20) -> str

Headless GIF export for any Lesson or Scene3DBundle.

Parameters
scene: Any, filename: str = 'out.gif', seconds: float = 5.0, fps: int = 20
Returns
str
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
function

side_by_side

side_by_side(*scenes: Any, title: str = 'Comparison') -> Lesson

Render two Lessons side by side. Each scene's first concept is reused.

Parameters
scenes: Any, title: str = 'Comparison'
Returns
Lesson
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
function

solar_system

solar_system(bodies: Optional[List[dict]] = None, dt: float = 518400, title: str = 'N-body gravity') -> Scene3DBundle

Newtonian N-body gravitational sim with simple Euler integration.

Parameters
bodies: Optional[List[dict]] = None, dt: float = 518400, title: str = 'N-body gravity'
Returns
Scene3DBundle
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

sorting

sorting(title: str = 'Sorting', algorithm: str = 'bubble', n: int = 14) -> Lesson

Step-by-step animated sort visualiser.

Parameters
title: str = 'Sorting', algorithm: str = 'bubble', n: int = 14
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

vector_field_3d

vector_field_3d(fn: Callable[[float, float, float], Tuple[float, float, float]], title: str = 'Vector field', extent: float = 3.0, resolution: int = 5) -> Scene3DBundle

3D quiver plot for any fn(x,y,z) → (vx,vy,vz).

Parameters
fn: Callable[[float, float, float], Tuple[float, float, float]], title: str = 'Vector field', extent: float = 3.0, resolution: int = 5
Returns
Scene3DBundle
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
function

wave_superposition

wave_superposition(title: str = 'Wave superposition', n_waves: int = 2) -> Lesson

Add n sinusoids with sliders on frequency + amplitude.

Parameters
title: str = 'Wave superposition', n_waves: int = 2
Returns
Lesson
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.

ember.graphics

class

Camera2D

class Camera2D(x: float = 0.0, y: float = 0.0, scale: float = 6.0, smoothing: float = 10.0) -> None

Smooth-following 2D camera. `scale` = screen pixels per world unit.

Parameters
x: float = 0.0, y: float = 0.0, scale: float = 6.0, smoothing: float = 10.0
Returns
Instance of Camera2D.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Camera2D.follow

follow(self, target_x: float, target_y: float, dt: float) -> None

Exponentially smooths the camera position toward (target_x, target_y) at the configured smoothing rate.

Parameters
target_x: float, target_y: float, dt: float
Returns
None
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
class

Ease

class Ease()

Easing functions. All map t∈[0,1]→[0,1] except pulse/ping_pong.

Parameters
No inputs.
Returns
Instance of Ease.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Ease.bounce

bounce(t: float) -> float

Simulates a bouncing ball that settles at t=1 with four progressively smaller rebounds.

Parameters
t: float
Returns
float
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Ease.in_cubic

in_cubic(t: float) -> float

Accelerates from zero using a cubic curve (sharper slow start than in_quad).

Parameters
t: float
Returns
float
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Ease.in_out

in_out(t: float) -> float

Accelerates then decelerates symmetrically using a piecewise quadratic.

Parameters
t: float
Returns
float
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Ease.in_quad

in_quad(t: float) -> float

Accelerates from zero using a quadratic curve (slow start).

Parameters
t: float
Returns
float
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Ease.linear

linear(t: float) -> float

Returns t clamped to [0, 1] — a constant-rate progression.

Parameters
t: float
Returns
float
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Ease.out_cubic

out_cubic(t: float) -> float

Decelerates to zero using a cubic curve (sharper slow end than out_quad).

Parameters
t: float
Returns
float
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Ease.out_quad

out_quad(t: float) -> float

Decelerates to zero using a quadratic curve (slow end).

Parameters
t: float
Returns
float
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Ease.ping_pong

ping_pong(t: float) -> float

Triangle wave: 0→1→0 with period 2.

Parameters
t: float
Returns
float
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Ease.pulse

pulse(t: float, period: float = 1.0) -> float

Smooth 0→1→0 oscillator; t is time in seconds.

Parameters
t: float, period: float = 1.0
Returns
float
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

InputState

class InputState(keys: set = <factory>) -> None

InputState(keys: 'set' = <factory>)

Parameters
keys: set = <factory>
Returns
Instance of InputState.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

InputState.down

down(self, *names: str) -> bool

Returns True if any of the given key names are currently held down.

Parameters
names: str
Returns
bool
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

Particles

class Particles(max_count: int = 300)

Lightweight CPU particle system.

Parameters
max_count: int = 300
Returns
Instance of Particles.
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Particles.clear

clear(self) -> None

Removes all live particles from the system immediately.

Parameters
No inputs.
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Particles.emit

emit(self, x: float, y: float, n: int = 8, *, color: Rgb = (255, 220, 80), speed: float = 40.0, spread: float = 3.141592653589793, lifetime: float = 1.0, direction: float = 0.0, size: float = 3.0) -> None

Spawn `n` particles from world position (x, y).

Parameters
x: float, y: float, n: int = 8, color: Rgb = (255, 220, 80), speed: float = 40.0, spread: float = 3.141592653589793, lifetime: float = 1.0, direction: float = 0.0, size: float = 3.0
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Particles.step

step(self, dt: float, gravity: float = 0.0) -> None

Advance physics and age particles; removes dead ones.

Parameters
dt: float, gravity: float = 0.0
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

Premium2D

class Premium2D(width: int = 960, height: int = 540, scale: float = 6.0, theme: str = 'midnight')

High-quality 2D drawing surface with world-space camera.

Parameters
width: int = 960, height: int = 540, scale: float = 6.0, theme: str = 'midnight'
Returns
Instance of Premium2D.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Premium2D.annotate

annotate(self, text: str, x: int, y: int, *, arrow_to: Optional[Tuple[int, int]] = None, color: Optional[Sequence[int]] = None, font_size: int = 12) -> None

Pixel-space label, optionally with an arrow pointing to another pixel.

Parameters
text: str, x: int, y: int, arrow_to: Optional[Tuple[int, int]] = None, color: Optional[Sequence[int]] = None, font_size: int = 12
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.arc

arc(self, x: float, y: float, radius: float, start: float, end: float, color: Sequence[int], width: int = 3, filled: bool = False, world: bool = True) -> None

Draw an arc or pie sector.

Parameters
x: float, y: float, radius: float, start: float, end: float, color: Sequence[int], width: int = 3, filled: bool = False, world: bool = True
Returns
None
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Premium2D.axes

axes(self, origin: Point, x_len: float, y_len: float, color: Sequence[int] = (120, 150, 180)) -> None

Draws horizontal and vertical axis arrows of length x_len/y_len from origin in world space.

Parameters
origin: Point, x_len: float, y_len: float, color: Sequence[int] = (120, 150, 180)
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.bar_chart

bar_chart(self, values: Sequence[float], labels: Optional[Sequence[str]] = None, x: int = 14, y: Optional[int] = None, bar_w: int = 160, row_h: int = 20, color: Sequence[int] = (80, 190, 255)) -> None

Horizontal bar chart panel. y defaults to bottom-left corner.

Parameters
values: Sequence[float], labels: Optional[Sequence[str]] = None, x: int = 14, y: Optional[int] = None, bar_w: int = 160, row_h: int = 20, color: Sequence[int] = (80, 190, 255)
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.begin

begin(self, camera: Optional[Camera2D] = None, background: Optional[Rgb] = None) -> Image.Image

Clear the canvas and (optionally) update the active camera.

Parameters
camera: Optional[Camera2D] = None, background: Optional[Rgb] = None
Returns
Image.Image
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Premium2D.bezier

bezier(self, p1: Point, cp: Point, p2: Point, color: Sequence[int], width: int = 2, segments: int = 20, world: bool = True) -> None

Draw a quadratic Bezier curve.

Parameters
p1: Point, cp: Point, p2: Point, color: Sequence[int], width: int = 2, segments: int = 20, world: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.buildings

buildings(self, city: Any, height_shading: bool = True) -> None

Draws all city building footprints with drop shadow, optional height cap shading, and window dot patterns.

Parameters
city: Any, height_shading: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.capsule

capsule(self, x1: float, y1: float, x2: float, y2: float, radius: float, color: Sequence[int], world: bool = True) -> None

Draw a stadium/capsule – a line segment with round end-caps.

Parameters
x1: float, y1: float, x2: float, y2: float, radius: float, color: Sequence[int], world: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.car

car(self, car_state: Any, braking: bool = False, body: Sequence[int] = (215, 55, 45)) -> None

Draws a top-down car sprite with heading-oriented body, roof, wheels, headlights, and braking tail-lights.

Parameters
car_state: Any, braking: bool = False, body: Sequence[int] = (215, 55, 45)
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.circle

circle(self, x: float, y: float, radius: float, color: Sequence[int], world: bool = True, glow: bool = True) -> None

Draws a drop-shadowed circle with a highlighted outline and an optional radial glow halo.

Parameters
x: float, y: float, radius: float, color: Sequence[int], world: bool = True, glow: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.dot_grid

dot_grid(self, spacing: int = 40) -> None

Draw a subtle background dot grid that scrolls with the camera.

Parameters
spacing: int = 40
Returns
None
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Premium2D.draw_arrow

draw_arrow(self, x1: float, y1: float, x2: float, y2: float, *, color: Sequence[int] = (200, 220, 240), width: int = 2, head_size: int = 10, world: bool = False) -> None

Pixel-space arrow with a sized arrowhead (more controllable than vector()).

Parameters
x1: float, y1: float, x2: float, y2: float, color: Sequence[int] = (200, 220, 240), width: int = 2, head_size: int = 10, world: bool = False
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.draw_axis

draw_axis(self, x0: int, y0: int, x1: int, y1: int, *, label: str = '', ticks: int = 5, range: Tuple[float, float] = (0.0, 1.0), color: Optional[Sequence[int]] = None) -> None

Pixel-space axis with tick marks and numeric labels.

Parameters
x0: int, y0: int, x1: int, y1: int, label: str = '', ticks: int = 5, range: Tuple[float, float] = (0.0, 1.0), color: Optional[Sequence[int]] = None
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.draw_contour

draw_contour(self, field: Any, x: int, y: int, w: int, h: int, *, levels: int = 10, colormap: Sequence[Sequence[int]] = ((18, 28, 52), (0, 240, 210)), alpha: int = 230) -> None

Heat-style display of a 2D scalar field (numpy array or list-of-lists).

Parameters
field: Any, x: int, y: int, w: int, h: int, levels: int = 10, colormap: Sequence[Sequence[int]] = ((18, 28, 52), (0, 240, 210)), alpha: int = 230
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.draw_grid

draw_grid(self, x: int, y: int, w: int, h: int, *, spacing: int = 20, color: Optional[Sequence[int]] = None, alpha: int = 50) -> None

Pixel-space line grid inside the rect (x,y,w,h).

Parameters
x: int, y: int, w: int, h: int, spacing: int = 20, color: Optional[Sequence[int]] = None, alpha: int = 50
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.draw_lattice

draw_lattice(self, unit_cell: Sequence[Tuple[str, float, float]], repeats: Tuple[int, int], cx: int, cy: int, *, spacing: float = 24.0) -> None

Tile a 2D unit cell (atoms in 0..1) over a `repeats` grid centred at (cx,cy).

Parameters
unit_cell: Sequence[Tuple[str, float, float]], repeats: Tuple[int, int], cx: int, cy: int, spacing: float = 24.0
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.draw_molecule

draw_molecule(self, atoms: Sequence[Tuple[str, float, float]], bonds: Sequence[Tuple[int, int, int]], cx: int, cy: int, *, scale: float = 30.0) -> None

Draw a 2D ball-and-stick molecule.

Parameters
atoms: Sequence[Tuple[str, float, float]], bonds: Sequence[Tuple[int, int, int]], cx: int, cy: int, scale: float = 30.0
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.draw_network

draw_network(self, nodes: Sequence[Any], edges: Sequence[Tuple[int, int]], x: int, y: int, w: int, h: int, *, layout: str = 'ring', node_size: int = 12, node_color: Sequence[int] = (90, 160, 255), edge_color: Sequence[int] = (120, 140, 170), labels: bool = True) -> None

Generic graph renderer. nodes: list of names; edges: list of (i, j) indices.

Parameters
nodes: Sequence[Any], edges: Sequence[Tuple[int, int]], x: int, y: int, w: int, h: int, layout: str = 'ring', node_size: int = 12, node_color: Sequence[int] = (90, 160, 255), edge_color: Sequence[int] = (120, 140, 170), labels: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.entities

entities(self, objs: Iterable[Any], **kwargs) -> None

Render an iterable of duck-typed entities (see entity()).

Parameters
objs: Iterable[Any], kwargs
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.entity

entity(self, obj: Any, *, draw_label: bool = True, glow: bool = True, override_color: Optional[Sequence[int]] = None) -> None

Render one duck-typed entity.

Parameters
obj: Any, draw_label: bool = True, glow: bool = True, override_color: Optional[Sequence[int]] = None
Returns
None
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
method

Premium2D.gauge

gauge(self, value: float, lo: float, hi: float, x: int, y: int, radius: int = 45, color: Sequence[int] = (80, 190, 255), label: str = '', world: bool = False) -> None

Circular arc gauge at screen position (x, y).

Parameters
value: float, lo: float, hi: float, x: int, y: int, radius: int = 45, color: Sequence[int] = (80, 190, 255), label: str = '', world: bool = False
Returns
None
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

Premium2D.glow

glow(self, x: int, y: int, color: Sequence[int], radius: int = 28, alpha: int = 90) -> None

Paste a cached radial glow at screen position (x, y).

Parameters
x: int, y: int, color: Sequence[int], radius: int = 28, alpha: int = 90
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.hud

hud(self, lines: Sequence, pos: Any = 'tl', width: int = 292) -> None

Overlay info panel.

Parameters
lines: Sequence, pos: Any = 'tl', width: int = 292
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.label

label(self, text: str, x: float, y: float, color: Optional[Sequence[int]] = None, world: bool = True) -> None

Draws a centred text label with a 1-pixel dark drop-shadow for legibility over any background.

Parameters
text: str, x: float, y: float, color: Optional[Sequence[int]] = None, world: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.line

line(self, a: Point, b: Point, color: Sequence[int], width: int = 2, world: bool = True) -> None

Draws a straight line segment between two points, projecting from world space unless world=False.

Parameters
a: Point, b: Point, color: Sequence[int], width: int = 2, world: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.minimap

minimap(self, city: Any, car_state: Any, x: Optional[int] = None, y: int = 14, size: int = 132) -> None

Draws a corner overview panel with a street grid and a red dot marking the car's current position.

Parameters
city: Any, car_state: Any, x: Optional[int] = None, y: int = 14, size: int = 132
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Premium2D.particles

particles(self, system: Particles, radius: float = 3.0, world: bool = True) -> None

Draw all live particles, fading out as they age.

Parameters
system: Particles, radius: float = 3.0, world: bool = True
Returns
None
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Premium2D.plot

plot(self, fn: Callable[[float], float], x_min: float, x_max: float, samples: int = 240, color: Sequence[int] = (80, 190, 255), width: int = 3) -> None

Plot a function y=fn(x) over [x_min, x_max] in world space.

Parameters
fn: Callable[[float], float], x_min: float, x_max: float, samples: int = 240, color: Sequence[int] = (80, 190, 255), width: int = 3
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.poly

poly(self, points: Iterable[Point], color: Sequence[int], outline: Optional[Sequence[int]] = None, world: bool = True) -> None

Draws a filled polygon from a sequence of points with an optional 1-pixel outline.

Parameters
points: Iterable[Point], color: Sequence[int], outline: Optional[Sequence[int]] = None, world: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.progress_bar

progress_bar(self, value: float, lo: float, hi: float, x: int, y: int, w: int = 120, h: int = 10, color: Sequence[int] = (80, 190, 255), label: str = '', world: bool = False) -> None

Horizontal progress bar at screen (x, y).

Parameters
value: float, lo: float, hi: float, x: int, y: int, w: int = 120, h: int = 10, color: Sequence[int] = (80, 190, 255), label: str = '', world: bool = False
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.rect

rect(self, x: float, y: float, w: float, h: float, color: Sequence[int], world: bool = True, outline: bool = True) -> None

Draws a drop-shadowed rounded rectangle centred at (x, y) with an optional brightened outline.

Parameters
x: float, y: float, w: float, h: float, color: Sequence[int], world: bool = True, outline: bool = True
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.roads

roads(self, block: float = 72.0, road_width: float = 22.0, radius: int = 7) -> None

Draws a grid of tiled road strips with edge lines and dashed centre lanes, scrolling with the camera.

Parameters
block: float = 72.0, road_width: float = 22.0, radius: int = 7
Returns
None
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Premium2D.scene

scene(self, snapshot: Any) -> None

Render a SimSnapshot returned by Simulation.snapshot().

Parameters
snapshot: Any
Returns
None
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Premium2D.screen_to_world

screen_to_world(self, x: float, y: float) -> Point

Converts screen-pixel coordinates back to world-space floats using the current camera.

Parameters
x: float, y: float
Returns
Point
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
method

Premium2D.status_bar

status_bar(self, text: str, color: Optional[Sequence[int]] = None) -> None

Thin status bar pinned to the bottom of the screen.

Parameters
text: str, color: Optional[Sequence[int]] = None
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.trail

trail(self, trail: Trail, color: Sequence[int] = (32, 40, 52), width: int = 2) -> None

Draws all stored world-space segments in the Trail ring buffer as a continuous path.

Parameters
trail: Trail, color: Sequence[int] = (32, 40, 52), width: int = 2
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.vector

vector(self, x: float, y: float, dx: float, dy: float, color: Sequence[int], world: bool = True, width: int = 3) -> None

Draw an annotated arrow from (x,y) in direction (dx,dy).

Parameters
x: float, y: float, dx: float, dy: float, color: Sequence[int], world: bool = True, width: int = 3
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Premium2D.world_to_screen

world_to_screen(self, x: float, y: float) -> Tuple[int, int]

Converts world-space coordinates to integer screen pixels using the current camera.

Parameters
x: float, y: float
Returns
Tuple[int, int]
When to use
Useful when something visibly travels between states or objects.
Covers
Current, data, blood, money, signals, fluids.
class

TkApp

class TkApp(title: str, renderer: Premium2D, target_fps: int = 30)

Minimal real-time app wrapper: fixed-timestep loop + keyboard input.

Parameters
title: str, renderer: Premium2D, target_fps: int = 30
Returns
Instance of TkApp.
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.
method

TkApp.run

run(self, update: Callable, render: Callable) -> None

Starts the fixed-timestep Tk mainloop, calling update(dt, keys) then render() each frame.

Parameters
update: Callable, render: Callable
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

TkApp.stop

stop(self) -> None

Signals the event loop to exit and destroys the Tk window.

Parameters
No inputs.
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
class

Trail

class Trail(max_segments: int = 700, segments: list = <factory>) -> None

Fixed-capacity ring of world-space line segments.

Parameters
max_segments: int = 700, segments: list = <factory>
Returns
Instance of Trail.
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Trail.add

add(self, x1: float, y1: float, x2: float, y2: float) -> None

Appends a world-space line segment, evicting the oldest entries when the ring is full.

Parameters
x1: float, y1: float, x2: float, y2: float
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
method

Trail.clear

clear(self) -> None

Removes all stored segments from the ring buffer.

Parameters
No inputs.
Returns
None
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

brighten

brighten(color: Sequence[int], amount: int) -> Rgb

Adds amount to each RGB channel, clamped to [0, 255]; pass a negative value to darken.

Parameters
color: Sequence[int], amount: int
Returns
Rgb
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

clamp

clamp(value: float, lo: float, hi: float) -> float

Returns value clamped to the closed interval [lo, hi].

Parameters
value: float, lo: float, hi: float
Returns
float
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

hex_color

hex_color(s: str) -> Rgb

Parse '#rrggbb' or '#rgb' to (r, g, b).

Parameters
s: str
Returns
Rgb
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
function

hsv_color

hsv_color(h: float, s: float, v: float) -> Rgb

HSV → RGB. h in [0, 360], s and v in [0, 1].

Parameters
h: float, s: float, v: float
Returns
Rgb
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
function

lerp_color

lerp_color(a: Sequence[int], b: Sequence[int], t: float) -> Rgb

Linearly interpolate between two RGB colors.

Parameters
a: Sequence[int], b: Sequence[int], t: float
Returns
Rgb
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
function

rgba

rgba(color: Sequence[int], alpha: Optional[int] = None) -> Rgba

Returns a 4-tuple (r, g, b, a); uses the existing alpha channel or the supplied alpha override.

Parameters
color: Sequence[int], alpha: Optional[int] = None
Returns
Rgba
When to use
Useful for consistent styling without hand-tuned CSS or colors.
Covers
Themes, palettes, opacity, visual emphasis.
function

with_alpha

with_alpha(color: Sequence[int], alpha: int) -> Rgba

Constructs an RGBA tuple from an RGB color and a separate alpha value.

Parameters
color: Sequence[int], alpha: int
Returns
Rgba
When to use
Useful for building an interactive simulation around state and time.
Covers
Controls, derived values, integration, animation clocks.

ember.graphics3d

class

Camera3D

class Camera3D(pos: Any = <factory>, target: Any = <factory>, up: Any = <factory>, fov: float = 55.0, near: float = 0.05) -> None

Perspective camera. pos and target are in world units (floats or lists).

Parameters
pos: Any = <factory>, target: Any = <factory>, up: Any = <factory>, fov: float = 55.0, near: float = 0.05
Returns
Instance of Camera3D.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Camera3D.orbit

orbit(self, yaw_deg: float, pitch_deg: float) -> None

Rotate camera around target while maintaining distance.

Parameters
yaw_deg: float, pitch_deg: float
Returns
None
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
method

Camera3D.zoom

zoom(self, factor: float) -> None

Scale distance from target.

Parameters
factor: float
Returns
None
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
class

Light3D

class Light3D(direction: Any = <factory>, ambient: float = 0.22) -> None

Light3D(direction: 'Any' = <factory>, ambient: 'float' = 0.22)

Parameters
direction: Any = <factory>, ambient: float = 0.22
Returns
Instance of Light3D.
When to use
Useful for spatial or volumetric subjects.
Covers
3D scenes, molecules, circuits, anatomy, vector fields.
class

Scene3D

class Scene3D(renderer: Premium2D, camera: Camera3D, light: Optional[Light3D] = None) -> None

Collects 3D geometry and renders it in one painter's-algorithm pass.

Parameters
renderer: Premium2D, camera: Camera3D, light: Optional[Light3D] = None
Returns
Instance of Scene3D.
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.axes3d

axes3d(self, origin = (0.0, 0.0, 0.0), size: float = 1.0) -> 'Scene3D'

Draw X (red), Y (green), Z (blue) axes.

Parameters
origin = (0.0, 0.0, 0.0), size: float = 1.0
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.box

box(self, center, size = (1.0, 1.0, 1.0), color: Sequence[int] = (200, 100, 60), *, rotation: Optional[np.ndarray] = None, lit: bool = True) -> 'Scene3D'

Adds an axis-aligned (or rotated) rectangular box mesh centred at center with the given (sx, sy, sz) size.

Parameters
center, size = (1.0, 1.0, 1.0), color: Sequence[int] = (200, 100, 60), rotation: Optional[np.ndarray] = None, lit: bool = True
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.circuit_row

circuit_row(self, elements: list, *, z: float = 0.0, top: float = 1.0, bot: float = -1.0, x_start: float = -7.0) -> 'Scene3D'

Auto-layout a circuit row from a description list — no coordinates needed.

Parameters
elements: list, z: float = 0.0, top: float = 1.0, bot: float = -1.0, x_start: float = -7.0
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.clear

clear(self) -> 'Scene3D'

Remove all collected geometry (reuse the scene each frame).

Parameters
No inputs.
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.cone

cone(self, apex, base_center, radius: float = 0.5, color: Sequence[int] = (220, 180, 40), *, segs: int = 14, lit: bool = True) -> 'Scene3D'

Adds a cone mesh with its tip at apex pointing toward base_center with the given base radius.

Parameters
apex, base_center, radius: float = 0.5, color: Sequence[int] = (220, 180, 40), segs: int = 14, lit: bool = True
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.crystal_lattice

crystal_lattice(self, unit_cell, repeats = (3, 3, 3), radius: float = 0.3) -> 'Scene3D'

Tile an atomic basis over an integer lattice.

Parameters
unit_cell, repeats = (3, 3, 3), radius: float = 0.3
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.cylinder

cylinder(self, p1, p2, radius: float = 0.5, color: Sequence[int] = (60, 200, 120), *, segs: int = 14, lit: bool = True) -> 'Scene3D'

Adds a capped cylinder mesh spanning from 3D point p1 to p2 with the given radius.

Parameters
p1, p2, radius: float = 0.5, color: Sequence[int] = (60, 200, 120), segs: int = 14, lit: bool = True
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.field_lines_3d

field_lines_3d(self, source_fn, seed_pts: list, steps: int = 60, step_size: float = 0.1, color: Sequence[int] = (80, 160, 255), width: int = 1) -> 'Scene3D'

Integrate and draw 3D vector field streamlines.

Parameters
source_fn, seed_pts: list, steps: int = 60, step_size: float = 0.1, color: Sequence[int] = (80, 160, 255), width: int = 1
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.grid3d

grid3d(self, y: float = 0.0, extent: float = 5.0, step: float = 1.0, color: Sequence[int] = (40, 55, 70)) -> 'Scene3D'

Draw a horizontal grid on the XZ plane at height y.

Parameters
y: float = 0.0, extent: float = 5.0, step: float = 1.0, color: Sequence[int] = (40, 55, 70)
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.heart3d

heart3d(self, phase: float = 0.0, bpm: int = 72, *, labels: bool = True, blood_flow: bool = True, vessels: bool = True) -> 'Scene3D'

Render a 4-chamber anatomical heart at a given beat phase (0–1).

Parameters
phase: float = 0.0, bpm: int = 72, labels: bool = True, blood_flow: bool = True, vessels: bool = True
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.label3d

label3d(self, pos, text: str, color: Optional[Sequence[int]] = None) -> 'Scene3D'

Draw a text label at a 3D world position (always on top).

Parameters
pos, text: str, color: Optional[Sequence[int]] = None
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.line3d

line3d(self, a, b, color: Sequence[int] = (200, 200, 80), width: int = 2) -> 'Scene3D'

Adds a depth-sorted line segment from 3D point a to b, drawn after all opaque faces.

Parameters
a, b, color: Sequence[int] = (200, 200, 80), width: int = 2
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.mesh

mesh(self, vertices, faces: list, color: Sequence[int] = (150, 160, 180), *, lit: bool = True) -> 'Scene3D'

Add arbitrary triangle mesh. vertices: Nx3, faces: list of 3-tuples.

Parameters
vertices, faces: list, color: Sequence[int] = (150, 160, 180), lit: bool = True
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.point3d

point3d(self, pos, color: Sequence[int] = (255, 200, 60), size: int = 8) -> 'Scene3D'

Draw a screen-space dot at a world position.

Parameters
pos, color: Sequence[int] = (255, 200, 60), size: int = 8
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.point_cloud

point_cloud(self, points, colors: Optional[Sequence[Sequence[int]]] = None, size: float = 0.05) -> 'Scene3D'

Add many small spheres as a point cloud.

Parameters
points, colors: Optional[Sequence[Sequence[int]]] = None, size: float = 0.05
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.render

render(self) -> None

Project, depth-sort, and draw everything collected so far.

Parameters
No inputs.
Returns
None
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.sphere

sphere(self, center, radius: float = 1.0, color: Sequence[int] = (80, 150, 255), *, rings: int = 10, segs: int = 18, lit: bool = True) -> 'Scene3D'

Adds a UV sphere mesh centred at center with the given radius, ring count, and segment count.

Parameters
center, radius: float = 1.0, color: Sequence[int] = (80, 150, 255), rings: int = 10, segs: int = 18, lit: bool = True
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.surface

surface(self, fn, x_range = (-3.0, 3.0), z_range = (-3.0, 3.0), resolution: int = 24, colormap: Tuple[Sequence[int], Sequence[int]] = ((40, 60, 140), (255, 200, 60))) -> 'Scene3D'

Sample y = fn(x, z) on a grid and add a coloured triangle mesh.

Parameters
fn, x_range = (-3.0, 3.0), z_range = (-3.0, 3.0), resolution: int = 24, colormap: Tuple[Sequence[int], Sequence[int]] = ((40, 60, 140), (255, 200, 60))
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.tube

tube(self, points, radius: float = 0.05, color: Sequence[int] = (180, 200, 255), segs: int = 8) -> 'Scene3D'

Path tube: sequence of cylinders between consecutive points.

Parameters
points, radius: float = 0.05, color: Sequence[int] = (180, 200, 255), segs: int = 8
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.vector3d

vector3d(self, origin, direction, color: Sequence[int] = (255, 200, 60), scale: float = 1.0, width: int = 2) -> 'Scene3D'

Draw an annotated arrow from origin in direction*scale.

Parameters
origin, direction, color: Sequence[int] = (255, 200, 60), scale: float = 1.0, width: int = 2
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
method

Scene3D.vector_field_3d

vector_field_3d(self, fn, extent: float = 3.0, resolution: int = 5, color: Sequence[int] = (90, 190, 255)) -> 'Scene3D'

3D arrow grid for fn(x,y,z) → (vx,vy,vz).

Parameters
fn, extent: float = 3.0, resolution: int = 5, color: Sequence[int] = (90, 190, 255)
Returns
'Scene3D'
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.
function

path_lerp

path_lerp(pts: list, frac: float) -> tuple

Return a 3-D point at normalized arc-length *frac* (0–1) along a polyline.

Parameters
pts: list, frac: float
Returns
tuple
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.

ember.layout

function

node_id

node_id(node: Any) -> str

Return a stable node id for strings, dicts, or light objects.

Parameters
node: Any
Returns
str
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

normalize_links

normalize_links(links: Iterable[Any] = ()) -> List[Dict[str, Any]]

Normalize link specs into dicts with ``from`` and ``to`` keys.

Parameters
links: Iterable[Any] = ()
Returns
List[Dict[str, Any]]
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

normalize_node_ids

normalize_node_ids(nodes: Iterable[Any], links: Iterable[Any] = ()) -> List[str]

Return ordered node ids, adding ids referenced by links if needed.

Parameters
nodes: Iterable[Any], links: Iterable[Any] = ()
Returns
List[str]
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

route_link

route_link(a: Point, b: Point, direction: str = 'auto', pad: float = 0.14) -> List[Point]

Return a short routed path between two normalized node positions.

Parameters
a: Point, b: Point, direction: str = 'auto', pad: float = 0.14
Returns
List[Point]
When to use
Useful as a general Ember building block.
Covers
Educational simulation authoring.
function

semantic_layout

semantic_layout(nodes: Iterable[Any], links: Iterable[Any] = (), layout: str = 'auto', direction: str = 'lr', x_extent: float = 0.72, y_extent: float = 0.52) -> Dict[str, Point]

Compute normalized coordinates for a semantic diagram.

Parameters
nodes: Iterable[Any], links: Iterable[Any] = (), layout: str = 'auto', direction: str = 'lr', x_extent: float = 0.72, y_extent: float = 0.52
Returns
Dict[str, Point]
When to use
Useful for keeping coordinate and routing math out of generated examples.
Covers
Placement, routing, node/link scenes, semantic sketches.