# lsdtools.kernels reference
URL: https://lsd.tools/docs/sdk-lsdtools-kernels
Updated: 2026-10-19

SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**.

Product source digest: `170db6f659e9f79609ddaaec494ffad41f1d659a96001371132843e0c17a7e27`.

Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions.

```text
The kernels service's public contract: typed row kernels a composition plays, lazily.

A package authors a kernels document (``KernelsDocument`` or its JSON form) with the IR nodes
here (``Kernel``, ``Column``, ``Ref``, ``Binary``, ...), validates it (``validate_document``)
and carries it on the ``kernels`` port (``document_table``); the kernels participant runs it on
the runtime engine in the editor and the compiler lowers the same IR to C++ for the exported
player. Resolving ``validate_document``, ``document_table`` or ``document_from_value`` imports
the participant, so an entity carrying the document is a member once the participant that
plays it is known. Importing this facade loads no engine and no view.
```


## `lsdtools.kernels.Assignment`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:274`.

Implementation alias: `lsd_kernels.ir.Assignment`.

### `lsdtools.kernels.Assignment.target`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:275`.

```python
target: str
```


### `lsdtools.kernels.Assignment.expression`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:276`.

```python
expression: Expr
```


## `lsdtools.kernels.Binary`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:204`.

Implementation alias: `lsd_kernels.ir.Binary`.

### `lsdtools.kernels.Binary.op`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:205`.

```python
op: str
```


### `lsdtools.kernels.Binary.left`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:206`.

```python
left: Expr
```


### `lsdtools.kernels.Binary.right`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:207`.

```python
right: Expr
```


## `lsdtools.kernels.Cast`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:253`.

Implementation alias: `lsd_kernels.ir.Cast`.

### `lsdtools.kernels.Cast.expression`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:254`.

```python
expression: Expr
```


### `lsdtools.kernels.Cast.dtype`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:255`.

```python
dtype: str
```


```python
dtype = 'float32'
```


## `lsdtools.kernels.Column`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:144`.

Source docstring:

```text
One bound array: a vector (``width`` 1) or one ``component`` of a ``(count, width)`` page.
```


Implementation alias: `lsd_kernels.ir.Column`.

### `lsdtools.kernels.Column.name`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:147`.

```python
name: str
```


### `lsdtools.kernels.Column.dtype`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:148`.

```python
dtype: str
```


```python
dtype = 'float32'
```


### `lsdtools.kernels.Column.access`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:149`.

```python
access: str
```


```python
access = 'read'
```


### `lsdtools.kernels.Column.width`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:150`.

```python
width: int
```


```python
width = 1
```


### `lsdtools.kernels.Column.component`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:151`.

```python
component: int | None
```


```python
component = None
```


### `lsdtools.kernels.Column.flag`

Kind: method. Source: `services/kernels/src/lsd_kernels/ir.py:171`.

```python
flag(self) -> bool
```


```python
self: (unannotated)
```


## `lsdtools.kernels.Compare`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:228`.

Implementation alias: `lsd_kernels.ir.Compare`.

### `lsdtools.kernels.Compare.op`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:229`.

```python
op: str
```


### `lsdtools.kernels.Compare.left`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:230`.

```python
left: Expr
```


### `lsdtools.kernels.Compare.right`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:231`.

```python
right: Expr
```


## `lsdtools.kernels.Constant`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:194`.

Implementation alias: `lsd_kernels.ir.Constant`.

### `lsdtools.kernels.Constant.value`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:195`.

```python
value: float | int
```


### `lsdtools.kernels.Constant.dtype`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:196`.

```python
dtype: str
```


```python
dtype = 'float32'
```


## `lsdtools.kernels.DOCUMENT_SCHEMA`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:37`.

```python
DOCUMENT_SCHEMA = 'lsd-kernels/1'
```


Implementation alias: `lsd_kernels.contracts.DOCUMENT_SCHEMA`.

## `lsdtools.kernels.KERNELS_PARAMETERS_PORT`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:31`.

```python
KERNELS_PARAMETERS_PORT = 'kernel_parameters'
```


Implementation alias: `lsd_kernels.contracts.PARAMETERS_PORT`.

## `lsdtools.kernels.KERNELS_PARTICIPANT`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:29`.

```python
KERNELS_PARTICIPANT = 'kernels'
```


Implementation alias: `lsd_kernels.contracts.PARTICIPANT`.

## `lsdtools.kernels.KERNELS_PORT`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:30`.

```python
KERNELS_PORT = 'kernels'
```


Implementation alias: `lsd_kernels.contracts.KERNELS_PORT`.

## `lsdtools.kernels.KERNEL_PHASES`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:49`.

```python
KERNEL_PHASES = ('before', 'step', 'after')
```


Implementation alias: `lsd_kernels.contracts.KERNEL_PHASES`.

## `lsdtools.kernels.Kernel`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:284`.

Implementation alias: `lsd_kernels.ir.Kernel`.

### `lsdtools.kernels.Kernel.name`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:285`.

```python
name: str
```


### `lsdtools.kernels.Kernel.columns`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:286`.

```python
columns: tuple[Column, ...]
```


### `lsdtools.kernels.Kernel.assignments`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:287`.

```python
assignments: tuple[Assignment, ...]
```


### `lsdtools.kernels.Kernel.parameters`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:288`.

```python
parameters: tuple[Parameter, ...]
```


```python
parameters = ()
```


### `lsdtools.kernels.Kernel.column`

Kind: method. Source: `services/kernels/src/lsd_kernels/ir.py:388`.

```python
column(self) -> Mapping[str, Column]
```


```python
self: (unannotated)
```


## `lsdtools.kernels.KernelError`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:93`.

Source docstring:

```text
An IR or array binding violates the closed kernel contract.
```


Implementation alias: `lsd_kernels.ir.KernelError`.

Declared bases: `ValueError`.

## `lsdtools.kernels.KernelsDocument`

Kind: class. Source: `services/kernels/src/lsd_kernels/document.py:382`.

Implementation alias: `lsd_kernels.document.KernelsDocument`.

### `lsdtools.kernels.KernelsDocument.spaces`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:383`.

```python
spaces: tuple[Space, ...]
```


### `lsdtools.kernels.KernelsDocument.components`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:384`.

```python
components: tuple[ComponentSpec, ...]
```


### `lsdtools.kernels.KernelsDocument.parameters`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:385`.

```python
parameters: tuple[ParameterSpec, ...]
```


### `lsdtools.kernels.KernelsDocument.uniforms`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:386`.

```python
uniforms: tuple[Uniform, ...]
```


### `lsdtools.kernels.KernelsDocument.kernels`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:387`.

```python
kernels: tuple[KernelSpec, ...]
```


### `lsdtools.kernels.KernelsDocument.reductions`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:388`.

```python
reductions: tuple[Reduction, ...]
```


### `lsdtools.kernels.KernelsDocument.models`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:389`.

```python
models: tuple[ModelBinding, ...]
```


```python
models = ()
```


### `lsdtools.kernels.KernelsDocument.spawns`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:390`.

```python
spawns: tuple[SpawnRule, ...]
```


```python
spawns = ()
```


### `lsdtools.kernels.KernelsDocument.weights`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:391`.

```python
weights: tuple[WeightBinding, ...]
```


```python
weights = ()
```


### `lsdtools.kernels.KernelsDocument.schema`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/document.py:392`.

```python
schema: str
```


```python
schema = field(default=DOCUMENT_SCHEMA)
```


### `lsdtools.kernels.KernelsDocument.to_dict`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:394`.

```python
to_dict(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


### `lsdtools.kernels.KernelsDocument.digest`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:409`.

```python
digest(self) -> str
```


```python
self: (unannotated)
```


### `lsdtools.kernels.KernelsDocument.space`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:414`.

```python
space(self, space_id: str) -> Space
```


```python
self: (unannotated)
space_id: str
```


### `lsdtools.kernels.KernelsDocument.components_of`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:420`.

```python
components_of(self, space_id: str) -> tuple[ComponentSpec, ...]
```


```python
self: (unannotated)
space_id: str
```


### `lsdtools.kernels.KernelsDocument.component`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:423`.

```python
component(self, space_id: str, name: str) -> ComponentSpec
```


```python
name: str
self: (unannotated)
space_id: str
```


### `lsdtools.kernels.KernelsDocument.uniform`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:429`.

```python
uniform(self, name: str) -> Uniform
```


```python
name: str
self: (unannotated)
```


### `lsdtools.kernels.KernelsDocument.parameter`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:435`.

```python
parameter(self, name: str) -> ParameterSpec
```


```python
name: str
self: (unannotated)
```


### `lsdtools.kernels.KernelsDocument.own_spaces`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:442`.

```python
own_spaces(self) -> tuple[Space, ...]
```


```python
self: (unannotated)
```


### `lsdtools.kernels.KernelsDocument.from_value`

Kind: method. Source: `services/kernels/src/lsd_kernels/document.py:446`.

```python
from_value(cls, value: Any) -> KernelsDocument
```


```python
cls: (unannotated)
value: Any
```


## `lsdtools.kernels.KernelsDocumentError`

Kind: class. Source: `services/kernels/src/lsd_kernels/errors.py:10`.

Source docstring:

```text
A kernels document violates its schema or names something the composition lacks.
```


Implementation alias: `lsd_kernels.errors.KernelsDocumentError`.

Declared bases: `ValueError`.

## `lsdtools.kernels.Parameter`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:176`.

Implementation alias: `lsd_kernels.ir.Parameter`.

### `lsdtools.kernels.Parameter.name`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:177`.

```python
name: str
```


### `lsdtools.kernels.Parameter.dtype`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:178`.

```python
dtype: str
```


```python
dtype = 'float32'
```


## `lsdtools.kernels.REDUCTIONS`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:50`.

```python
REDUCTIONS = ('sum', 'min', 'max', 'count_nonzero')
```


Implementation alias: `lsd_kernels.contracts.REDUCTIONS`.

## `lsdtools.kernels.Ref`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:186`.

Implementation alias: `lsd_kernels.ir.Ref`.

### `lsdtools.kernels.Ref.name`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:187`.

```python
name: str
```


## `lsdtools.kernels.SPACE_KINDS`

Kind: value. Source: `services/kernels/src/lsd_kernels/contracts.py:46`.

```python
SPACE_KINDS = ('scene', 'physics', OWN_SPACE)
```


Implementation alias: `lsd_kernels.contracts.SPACE_KINDS`.

## `lsdtools.kernels.Select`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:241`.

Implementation alias: `lsd_kernels.ir.Select`.

### `lsdtools.kernels.Select.condition`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:242`.

```python
condition: Expr
```


### `lsdtools.kernels.Select.a`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:243`.

```python
a: Expr
```


### `lsdtools.kernels.Select.b`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:244`.

```python
b: Expr
```


## `lsdtools.kernels.Unary`

Kind: class. Source: `services/kernels/src/lsd_kernels/ir.py:217`.

Implementation alias: `lsd_kernels.ir.Unary`.

### `lsdtools.kernels.Unary.op`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:218`.

```python
op: str
```


### `lsdtools.kernels.Unary.operand`

Kind: attribute. Source: `services/kernels/src/lsd_kernels/ir.py:219`.

```python
operand: Expr
```


## `lsdtools.kernels.document_from_table`

Kind: function. Source: `services/kernels/src/lsd_kernels/document.py:1085`.

```python
document_from_table(table: pa.Table) -> KernelsDocument
```


```python
table: pa.Table
```


Implementation alias: `lsd_kernels.document.document_from_table`.

## `lsdtools.kernels.document_from_value`

Kind: function. Source: `services/kernels/src/lsd_kernels/document.py:1019`.

```python
document_from_value(value: Any) -> KernelsDocument
```


```python
value: Any
```


Source docstring:

```text
The validated document of one JSON value (a dict or its text).
```


Implementation alias: `lsd_kernels.document.document_from_value`.

## `lsdtools.kernels.document_table`

Kind: function. Source: `services/kernels/src/lsd_kernels/document.py:1078`.

```python
document_table(document: KernelsDocument | Mapping[str, Any]) -> pa.Table
```


```python
document: KernelsDocument | Mapping[str, Any]
```


Source docstring:

```text
The one-row table a kernels entity's ``kernels`` port carries.
```


Implementation alias: `lsd_kernels.document.document_table`.

## `lsdtools.kernels.evaluate`

Kind: function. Source: `services/kernels/src/lsd_kernels/ir.py:524`.

```python
evaluate(kernel: Kernel, arrays: Mapping[str, np.ndarray], parameters: Mapping[str, float] | None=None) -> None
```


```python
arrays: Mapping[str, np.ndarray]
kernel: Kernel
parameters: Mapping[str, float] | None
```


Source docstring:

```text
Reference evaluator: validate every binding before mutating declared output arrays.

This numpy oracle allocates expression temporaries. The native fused kernel does not.
Binding dtypes are exact, native endian and contiguous; a width-1 column binds a
one-dimensional vector, a wider column a ``(count, width)`` page; no array cast, copy,
resize, or broadcasting is inferred.
```


Implementation alias: `lsd_kernels.ir.evaluate`.

## `lsdtools.kernels.expression_from_json`

Kind: function. Source: `services/kernels/src/lsd_kernels/ir.py:426`.

```python
expression_from_json(value: Any, *, depth: int=0) -> Expr
```


```python
depth: int
value: Any
```


Source docstring:

```text
The IR node of one JSON expression (the inverse of ``expression_to_json``).
```


Implementation alias: `lsd_kernels.ir.expression_from_json`.

## `lsdtools.kernels.expression_to_json`

Kind: function. Source: `services/kernels/src/lsd_kernels/ir.py:395`.

```python
expression_to_json(node: Expr) -> dict[str, Any]
```


```python
node: Expr
```


Implementation alias: `lsd_kernels.ir.expression_to_json`.

## `lsdtools.kernels.kernels_timeline_spec`

Kind: function. Source: `services/kernels/src/lsd_kernels/timeline.py:66`.

```python
kernels_timeline_spec()
```


Source docstring:

```text
The declaration the games package contributes; inspecting it loads no engine.
```


Implementation alias: `lsd_kernels.timeline.kernels_timeline_spec`.

## `lsdtools.kernels.parameter_target`

Kind: function. Source: `services/kernels/src/lsd_kernels/timeline.py:42`.

```python
parameter_target(name: str) -> str
```


```python
name: str
```


Source docstring:

```text
The Timeline target id of one kernels parameter: ``kernels:<name>``.
```


Implementation alias: `lsd_kernels.timeline.parameter_target`.

## `lsdtools.kernels.parameters_table`

Kind: function. Source: `services/kernels/src/lsd_kernels/timeline.py:47`.

```python
parameters_table(value: Any) -> pa.Table
```


```python
value: Any
```


Source docstring:

```text
The ``kernel_parameters`` table of one document: its ``timeline: true`` parameters as
authored Timeline targets (``target``, ``name``, ``value``).
```


Implementation alias: `lsd_kernels.timeline.parameters_table`.

## `lsdtools.kernels.validate_document`

Kind: function. Source: `services/kernels/src/lsd_kernels/document.py:1068`.

```python
validate_document(value: Any) -> str | None
```


```python
value: Any
```


Source docstring:

```text
Why ``value`` is not a kernels document (None when it is): what a step's parameter
validator returns.
```


Implementation alias: `lsd_kernels.document.validate_document`.