Native blocks

Math blocks that run in the native core inside lambdas, .map and plots.

Contents:

• k.sin: Native math functions: k.sin, k.cos, k.tan, k.exp, k.log, k.sqrt and k.atan2(y, x).
• k.atan2: Native math functions: k.sin, k.cos, k.tan, k.exp, k.log, k.sqrt and k.atan2(y, x).
• k.cos: cos(x), native on signals.
• k.exp: exp(x), native on signals.
• k.log: ln(x), native on signals.
• k.sqrt: sqrt(x), native on signals.
• k.tan: tan(x), native on signals.
• k.floor: Native rounding down (k.floor) and up (k.ceil).
• k.ceil: ceil(x), native on signals.
• k.min: Native minimum and maximum of two or more values (k.min(a, b, c)).
• k.max: Native minimum and maximum of two or more values (k.min(a, b, c)).
• k.clamp: Clamps a value to the range [lo, hi], natively.
• k.where: The traceable if: a where cond holds, otherwise b.
• k.piecewise: Piecewise function: k.piecewise((cond1, v1), (cond2, v2), default=v); the first true condition wins.
• k.spline: Smooth table interpolation (natural cubic spline): k.spline(x, xs, ys).
• k.interp: Linear table interpolation: k.interp(x, xs, ys).
• k.mix: Linear mix a + (b - a) * t of numbers, vectors or colors (colors in OKLab, with no gray in the middle).
• k.smoothstep: Smooth transition from 0 to 1 as x goes from e0 to e1 (cubic Hermite).
• k.noise: Smooth, deterministic noise in [-1, 1] (seed= changes the sequence).
• k.vec: 2D vector from two values (numbers or signals).
• k.Vec: Vec(x, y)
• k.pi: Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.
• k.e: Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.
• k.tau: Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.

Back to the reference index.

k.sin (function)#

k.sin(x: Any) -> Any

Native math functions: k.sin, k.cos, k.tan, k.exp, k.log, k.sqrt and k.atan2(y, x). Use them instead of math.*, which is not traceable (error K0305/K0310). Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def oscillator(s: k.Scene):
    dot = k.Dot(r=0.2, x=k.cos(k.time * 2) * 3, y=k.sin(k.time * 2) * 2)
    s.add(dot)
    s.wait(4)

See also: k.pi, x.map, k.time.

k.atan2 (function)#

k.atan2(a: Any, b: Any) -> Any

Documented together with k.sin. Native math functions: k.sin, k.cos, k.tan, k.exp, k.log, k.sqrt and k.atan2(y, x). Use them instead of math.*, which is not traceable (error K0305/K0310). Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

k.cos (function)#

k.cos(x: Any) -> Any

cos(x), native on signals.

Documented together with k.sin.

Parameters:

k.exp (function)#

k.exp(x: Any) -> Any

exp(x), native on signals.

Documented together with k.sin.

Parameters:

k.log (function)#

k.log(x: Any) -> Any

ln(x), native on signals.

Documented together with k.sin.

Parameters:

k.sqrt (function)#

k.sqrt(x: Any) -> Any

sqrt(x), native on signals.

Documented together with k.sin.

Parameters:

k.tan (function)#

k.tan(x: Any) -> Any

tan(x), native on signals.

Documented together with k.sin.

Parameters:

k.floor (function)#

k.floor(x: Any) -> Any

Native rounding down (k.floor) and up (k.ceil). They replace int() and math.floor, which are not traceable. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def counter(s: k.Scene):
    hour = k.time * 2
    clock = k.Text(lambda: f"{k.floor(hour()):02.0f}:00", size=0.9).place(at="center")
    s.add(clock)
    s.wait(4)

See also: k.time, k.clamp.

k.ceil (function)#

k.ceil(x: Any) -> Any

ceil(x), native on signals.

Documented together with k.floor.

Parameters:

k.min (function)#

k.min(*args: float) -> float
k.min(*args: FloatExpr) -> Expr[float]
k.min(*args: ArrayT | float) -> ArrayT

Native minimum and maximum of two or more values (k.min(a, b, c)). They replace the built-in min()/max(), which are not traceable. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def capped(s: k.Scene):
    hour = k.time.map(lambda t: k.min(t * 6, 24))
    label = k.Text(lambda: f"{hour():.0f} h", size=0.9).place(at="center")
    s.add(label)
    s.wait(5)

See also: k.clamp, k.where.

k.max (function)#

k.max(*args: float) -> float
k.max(*args: FloatExpr) -> Expr[float]
k.max(*args: ArrayT | float) -> ArrayT

Documented together with k.min. Native minimum and maximum of two or more values (k.min(a, b, c)). They replace the built-in min()/max(), which are not traceable. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

k.clamp (function)#

k.clamp(x: float, lo: float, hi: float) -> float
k.clamp(x: FloatExpr, lo: FloatExpr, hi: FloatExpr) -> Expr[float]
k.clamp(x: ArrayT, lo: float, hi: float) -> ArrayT

Clamps a value to the range [lo, hi], natively. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def limit(s: k.Scene):
    x = k.signal(-6.0)
    dot = k.Dot(r=0.2, x=k.clamp(x, -3, 3))
    s.add(dot)
    s.play(x.to(6), duration=3)

See also: k.min, k.smoothstep.

k.where (function)#

k.where(cond: bool, a: T, b: T) -> T
k.where(cond: bool | Expr[bool], a: T | Expr[T], b: T | Expr[T]) -> Expr[T]
k.where(cond: ArrayT, a: ArrayT | float, b: ArrayT | float) -> ArrayT

The traceable if: a where cond holds, otherwise b. Combine conditions with &, | and ~ (not with and/or). Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

def tariff(h: float) -> float:
    return k.where((h >= 18) & (h < 21), 1.8, 0.6)

@k.scene
def peak(s: k.Scene):
    hour = k.time * 6
    label = k.Text(lambda: f"{hour():.0f} h: $ {tariff(hour()):.2f}").place(at="center")
    s.add(label)
    s.wait(4)

See also: k.piecewise, k.when.

k.piecewise (function)#

k.piecewise(*cases: tuple[bool, T], default: T) -> T
k.piecewise(
    *cases: tuple[bool | Expr[bool], T | Expr[T]],
    default: T | Expr[T],
) -> Expr[T]
k.piecewise(*cases: tuple[bool | Expr[bool], float | Expr[float]]) -> Expr[float]

Piecewise function: k.piecewise((cond1, v1), (cond2, v2), default=v); the first true condition wins. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

def band(v: float) -> k.Color:
    return k.piecewise((v < 1, k.GREEN), (v < 2, k.YELLOW), default=k.RED)

@k.scene
def traffic_light(s: k.Scene):
    v = k.signal(0.0)
    lamp = k.Circle(r=1, fill=v.map(band), fill_opacity=1).place(at="center")
    s.add(lamp)
    s.play(v.to(3), duration=3)

See also: k.where.

k.spline (function)#

k.spline(x: float, xs: FloatColumn, ys: FloatColumn) -> float
k.spline(x: Expr[float], xs: FloatColumn, ys: FloatColumn) -> Expr[float]
k.spline(x: ArrayT, xs: FloatColumn, ys: FloatColumn) -> ArrayT

Smooth table interpolation (natural cubic spline): k.spline(x, xs, ys). Same inputs as k.interp; outside the range it holds the endpoint value. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def smooth(s: k.Scene):
    x = k.signal(0.0)
    height = k.spline(x, [0, 1, 2, 3], [0, 2, 1, 2])
    dot = k.Dot(r=0.15, x=x * 2 - 3, y=height - 1)
    s.add(dot)
    s.play(x.to(3), duration=2)

See also: k.interp, k.smoothstep.

k.interp (function)#

k.interp(x: float, xs: FloatColumn, ys: FloatColumn) -> float
k.interp(x: Expr[float], xs: FloatColumn, ys: FloatColumn) -> Expr[float]
k.interp(x: ArrayT, xs: FloatColumn, ys: FloatColumn) -> ArrayT

Linear table interpolation: k.interp(x, xs, ys). xs/ys can be lists, numpy arrays or Arrow columns (polars, pandas, pyarrow), without copying. Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

HOURS = [0, 6, 12, 18, 24]
KW = [0.5, 0.8, 1.2, 2.5, 0.6]

@k.scene
def load(s: k.Scene):
    hour = k.time * 4
    label = k.Text(lambda: f"{k.interp(hour(), HOURS, KW):.2f} kW").place(at="center")
    s.add(label)
    s.wait(5)

See also: ax.plot, k.mix.

k.mix (function)#

k.mix(a: float, b: float, t: float) -> float
k.mix(a: FloatExpr, b: FloatExpr, t: FloatExpr) -> Expr[float]
k.mix(a: ColorExpr, b: ColorExpr, t: FloatExpr) -> Expr[Color]
k.mix(a: VecExpr, b: VecExpr, t: FloatExpr) -> Expr[Vec]

Linear mix a + (b - a) * t of numbers, vectors or colors (colors in OKLab, with no gray in the middle). Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def gradient(s: k.Scene):
    t = k.signal(0.0)
    box = k.Square(2, fill=k.mix(k.RED, k.GREEN, t), fill_opacity=1).place(at="center")
    s.add(box)
    s.play(t.to(1), duration=2)

See also: k.interp, k.smoothstep.

k.smoothstep (function)#

k.smoothstep(e0: float, e1: float, x: float) -> float
k.smoothstep(e0: FloatExpr, e1: FloatExpr, x: FloatExpr) -> Expr[float]

Smooth transition from 0 to 1 as x goes from e0 to e1 (cubic Hermite). Like every k function, it accepts floats, signals and numpy arrays: the same function works for ax.plot (floats) and for .map (traced, native).

Parameters:

Example:

@k.scene
def fade_glow(s: k.Scene):
    glow = k.smoothstep(1, 3, k.time)
    c = k.Circle(r=1.5, fill=k.YELLOW, fill_opacity=glow).place(at="center")
    s.add(c)
    s.wait(4)

See also: k.clamp, k.mix.

k.noise (function)#

k.noise(x: FloatExpr, seed: int = 0) -> Expr[float]

Smooth, deterministic noise in [-1, 1] (seed= changes the sequence). Good for jitter and organic motion.

Parameters:

Example:

@k.scene
def jitter(s: k.Scene):
    leaf = k.Ellipse(w=1.2, h=0.6, fill=k.GREEN, fill_opacity=1)
    leaf.set(x=k.noise(k.time, seed=1) * 2, y=k.noise(k.time, seed=2))
    s.add(leaf)
    s.wait(4)

See also: k.sin, k.time.

k.vec (function)#

k.vec(x: float, y: float) -> Vec
k.vec(x: FloatExpr, y: FloatExpr) -> Expr[Vec]

2D vector from two values (numbers or signals). With signals, the vector is reactive: use it in point props such as a line's start=/end=.

Parameters:

Example:

@k.scene
def clock_hand(s: k.Scene):
    angle = k.time * 2
    hand = k.Line(start=(0, 0), end=k.vec(k.cos(angle) * 2, k.sin(angle) * 2))
    s.add(hand)
    s.wait(4)

See also: k.sin, k.Line.

k.Vec (class)#

k.Vec(x: float, y: float)

Vec(x, y)

Documented together with k.vec.

Parameters:

Members:

• length: Euclidean length of the vector.

k.Vec.length (property)

vec.length: float  # read-only

Euclidean length of the vector.

k.pi (constant)#

k.pi: float = 3.14159

Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.

Example:

@k.scene
def orbit(s: k.Scene):
    angle = k.time * k.tau / 4
    dot = k.Dot(r=0.2, x=k.cos(angle) * 2, y=k.sin(angle) * 2)
    s.add(dot)
    s.wait(4)

See also: k.sin.

k.e (constant)#

k.e: float = 2.71828

Documented together with k.pi. Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.

k.tau (constant)#

k.tau: float = 6.28319

Documented together with k.pi. Constants k.pi, k.tau (2π) and k.e, for use inside traced functions.