life.d.ts

1export { default, initSync } from "./pkg/life/mrlyjs_life.js";23/** An rgba color as four bytes. */4export type Color = [number, number, number, number];5/** A tensor: its shape and its flat data as a typed array of its dtype. */6export interface Tensor {7    shape: number[];8    data: Uint8Array | Uint16Array | Uint32Array | Int32Array;9}10/** A cell: the shape, the type bytes, and the flat rgba colors and the tags when present. */11export interface Cell {12    shape: number[];13    types: Uint8Array | Uint16Array | Uint32Array | Int32Array;14    colors?: Uint8Array;15    tags?: Uint8Array | Uint16Array | Uint32Array | Int32Array;16}17/** A hex cell: a flat cell with its projection, orientation and start row. */18export interface Cell6d {19    cell: Cell;20    projection: "Iso" | "Pro" | "Cut";21    orientation: "Horizontal" | "Vertical";22    start: number;23}24/** A color inside plain data, serde's form. */25export interface ColorData {26    r: number;27    g: number;28    b: number;29    a: number;30}31/** A tensor inside plain data, serde's form. */32export interface TensorData {33    shape: number[];34    data: { U8: number[] } | { U16: number[] } | { U32: number[] } | { I32: number[] };35}36/** A cell inside plain data, serde's form. */37export interface CellData {38    types: TensorData;39    colors?: number[][];40    tags?: TensorData;41}42/** A hex cell inside plain data, serde's form. */43export interface Cell6dData {44    cell: { cell: CellData };45    projection: "Iso" | "Pro" | "Cut";46    orientation: "Horizontal" | "Vertical";47    start: number;48}49/** A seeded random stream, opened from a number or a bigint seed. */50export class Rng {51    constructor(seed: number | bigint | string);52    free(): void;53    /** Draws a float at or above zero and below one. */54    unit(): number;55    /** Draws an integer below n, or zero when n is zero. */56    below(n: number): number;57    /** Draws an integer between lo and hi inclusive, or lo when hi is not above lo. */58    range(lo: number, hi: number): number;59    /** Draws a fair coin flip. */60    boolean(): boolean;61    /** Returns true with probability p. */62    chance(p: number): boolean;63    /** Draws amount distinct indices below length, or every index when amount is larger. */64    sample_indices(length: number, amount: number): Uint32Array;65    /** Draws one item of the array, the same draw as Rust's choice. */66    choice<T>(items: ArrayLike<T>): T;67    /** Shuffles the array in place, the same permutation as Rust's shuffle. */68    shuffle<T>(items: T[]): void;69}70/** Returns whether a rule is affine, its algebraic degree at most one. */71export function affine(rule: number): boolean;72/** Runs a seed under a config until it fixes, loops or times out, recording every generation. */73export function animate(seed: Cell, config: Config): Life;74/** Returns the mean fraction of sites changed between consecutive grids. */75export function churn(grids: Cell[]): number;76/** Returns the eight output bits of a rule, corner `i` at index `i = 4 x0 + 2 x1 + x2`. */77export function corner_bits(rule: number): Uint8Array;78/** Returns the sequence up to max_neighbors, keeping zeros and ones only on request. */79export function counts(seq: Source, max_neighbors: number, include_zeros: boolean, include_ones: boolean): Uint32Array;80/** Crops a frame sequence to the centred square bounding every cell ever alive. */81export function crop(grids: Cell[]): Cell[];82/** Returns the rules a rule reaches under the signed axis permutations of the cube, in ascending order. */83export function cube_orbit(rule: number): Uint8Array;84/** Builds the base-2 design mask a code names at an odd side grown to the given Kronecker */85export function design_mask(dimension: number, code: string | number | bigint, number: number, level: number): Tensor;86/** Returns the grid's binary Shannon entropy in millibits. */87export function entropy(grid: Cell): bigint;88/** Renders grids to white-on-black PNG bytes at a pixel scale. */89export function frames(grids: Cell[], scale: number): Uint8Array[];90/** Returns the base-2 plane design a rule's single seed draws, or None when it draws none. */91export function gasket(rule: number): string | undefined;92/** Returns the genus of a rule's cube class: `iso` when it meets a level set, `axis` when it meets an axis-pinned block, else `comp`. */93export function genus(rule: number): string;94/** Renders a whole run's cumulative-visit heatmap frames with the heat ramp. */95export function heatmap(grids: Cell[], scale: number): Uint8Array[];96/** Returns the space-time diagram of a seed row, row 0 the seed and then one row per generation. */97export function history(row: ArrayLike<number>, rule: number, steps: number, wrap: boolean): Tensor;98/** Returns Langton's lambda, the popcount over eight. */99export function lambda(rule: number): number;100/** Returns the index of the lattice the mask offsets generate together with the centre, zero when they do not span the dimension. */101export function lattice_index(mask: Tensor): number;102/** Returns the offsets a mask's filled sites take from its centre, the centre itself dropped. */103export function mask_offsets(mask: Tensor): BigInt64Array[];104/** Builds the 3 by 3 Moore mask, every site on but the center. */105export function moore(): Cell;106/** Renders grids into one looping black-on-white gif, the delay in hundredths of a second. */107export function movie(grids: Cell[], scale: number, delay: number): Uint8Array;108/** Advances a grid one generation under birth and survive counts, a neighbor mask and a boundary. */109export function next_grid(cell: Cell, birth: ArrayLike<number>, survive: ArrayLike<number>, mask: Tensor, boundary: Boundary): Cell;110/** Returns the rules a rule reaches under the cube group together with the output complement, its NPN class, in ascending order. */111export function npn_class(rule: number): Uint8Array;112/** Returns the birth and survive counts of a rule read outer-totalistically on its two outer cells, or None when it does not read them by count alone. */113export function outer_totalistic(rule: number): [Uint32Array, Uint32Array] | undefined;114/** Returns the count of neighbourhoods a rule sends to one. */115export function popcount(rule: number): number;116/** Returns whether a rule is reversible, by the pair graph on the de Bruijn nodes pruned to its bi-infinite core. */117export function reversible(rule: number): boolean;118/** Returns the GF(2) algebraic degree of a rule, minus one for the zero rule. */119export function rule_degree(rule: number): number;120/** Returns the design name a rule carries, `bang dim 3, code <rule>`. */121export function rule_name(rule: number): string;122/** Returns the single-seed diagram: one live cell run the given generations on a line padded by `steps` cells beyond the `2 steps + 1` window on each side, cropped back to that window. */123export function single_seed(rule: number, steps: number): Tensor;124/** Advances one row one generation, a constant-0 boundary unless the edges wrap. */125export function step(row: ArrayLike<number>, rule: number, wrap: boolean): Uint8Array;126/** Returns whether a rule is surjective on bi-infinite lines, by the de Bruijn subset walk from the full node set. */127export function surjective(rule: number): boolean;128/** Tiles every frame n by n to reach at least min_canvas a side, unchanged when already there. */129export function tessellate(grids: Cell[], min_canvas: number): Cell[];130/** Returns the rules a rule reaches under left-right reflection and conjugation, Wolfram's equivalence, in ascending order. */131export function wolfram_class(rule: number): Uint8Array;132/** The edge policy of a life grid. */133export type Boundary = "Constant" | "Wrap";134export const Boundary: {135    /** Returns every Boundary in canonical order. */136    all(): Boundary[];137    /** Returns whether the edges wrap. */138    wrap(boundary: Boundary): boolean;139};140export interface ConfigData {141    /** The neighborhood mask. */142    mask: { cell: CellData };143    /** The neighbor counts that create a cell. */144    birth: CountsData;145    /** The neighbor counts that keep a cell. */146    survive: CountsData;147    /** The edge policy. */148    boundary: Boundary;149    /** The generation cap. */150    max_generations: number;151    /** The tiling factor applied to the seed. */152    grid_size: number;153    /** The dead border added around the seed. */154    padding: number;155}156/** The rulebook of a life run. */157export class Config {158    /** Builds a config with a constant boundary, a 64-generation cap, no tiling and no padding. */159    constructor(mask: Cell, birth: Counts, survive: Counts);160    free(): void;161    /** Reads the Config from its plain data. */162    static from(data: ConfigData): Config;163    /** Writes the Config as plain data. */164    toJSON(): ConfigData;165    /** The neighborhood mask. */166    get mask(): Cell;167    set mask(value: Cell);168    /** The neighbor counts that create a cell. */169    get birth(): Counts;170    set birth(value: Counts);171    /** The neighbor counts that keep a cell. */172    get survive(): Counts;173    set survive(value: Counts);174    /** The edge policy. */175    get boundary(): Boundary;176    set boundary(value: Boundary);177    /** The generation cap. */178    get max_generations(): number;179    set max_generations(value: number);180    /** The tiling factor applied to the seed. */181    get grid_size(): number;182    set grid_size(value: number);183    /** The dead border added around the seed. */184    get padding(): number;185    set padding(value: number);186    /** Returns the largest neighbor count the mask can reach. */187    budget(): number;188    /** Resolves the birth and survive counts against the mask's budget. */189    counts(): [Uint32Array, Uint32Array];190}191export type CountsData = { List: number[] } | { Drawn: { seq: SourceData; zeros: boolean; ones: boolean } };192/** The neighbor counts one side of a rule fires on. */193export class Counts {194    private constructor();195    free(): void;196    /** Reads the Counts from its plain data. */197    static from(data: CountsData): Counts;198    /** Writes the Counts as plain data. */199    toJSON(): CountsData;200    /** Builds the counts a sequence lays down, keeping zeros and ones on request. */201    static drawn(seq: Source, zeros: boolean, ones: boolean): Counts;202    /** Spells the counts outright. */203    static list(counts: ArrayLike<number>): Counts;204    /** Returns the counts, a drawn side resolved against the mask's neighbor budget. */205    values(budget: number): Uint32Array;206}207/** The ending of a life run. */208export type Fate = "Dead" | "Alive" | "Loop" | "Timeout";209export const Fate: {210    /** Returns every Fate in canonical order. */211    all(): Fate[];212};213export interface LifeData {214    /** Every generation in order. */215    grids: { cell: CellData }[];216    /** The run's ending. */217    fate: Fate;218    /** The number of recorded generations. */219    count: number;220    /** The cycle length when the fate is a loop, else zero. */221    loop_length: number;222}223/** The recorded run of one seed. */224export class Life {225    private constructor();226    free(): void;227    /** Reads the Life from its plain data. */228    static from(data: LifeData): Life;229    /** Writes the Life as plain data. */230    toJSON(): LifeData;231    /** Every generation in order. */232    get grids(): Cell[];233    set grids(value: Cell[]);234    /** The run's ending. */235    get fate(): Fate;236    set fate(value: Fate);237    /** The number of recorded generations. */238    get count(): number;239    set count(value: number);240    /** The cycle length when the fate is a loop, else zero. */241    get loop_length(): number;242    set loop_length(value: number);243    /** Returns the final grid, or None when the run is empty. */244    last(): Cell | undefined;245}246export interface RuleData {247    /** The kind word. */248    kind: string;249    /** The neighbor counts that create a cell, listed or drawn from a sequence. */250    birth: CountsData;251    /** The neighbor counts that keep a cell, listed or drawn from a sequence. */252    survive: CountsData;253    /** Whether the edge wraps, false unless said. */254    wrap: boolean;255}256/** A life rule: the birth and survival counts and whether the edge wraps. */257export class Rule {258    /** Builds a rule from its counts and edge policy, listed counts folded to a sorted set. */259    constructor(birth: Counts, survive: Counts, wrap: boolean);260    free(): void;261    /** Reads the Rule from its plain data. */262    static from(data: RuleData): Rule;263    /** Writes the Rule as plain data. */264    toJSON(): RuleData;265    /** The neighbor counts that create a cell, listed or drawn from a sequence. */266    get birth(): Counts;267    set birth(value: Counts);268    /** The neighbor counts that keep a cell, listed or drawn from a sequence. */269    get survive(): Counts;270    set survive(value: Counts);271    /** Whether the edge wraps, false unless said. */272    get wrap(): boolean;273    set wrap(value: boolean);274    /** Returns the edge policy the rule runs under. */275    boundary(): Boundary;276    /** Folds a decoded value to its canonical form, or an error for one outside the kind. */277    checked(): Rule;278    /** Builds a life config running this rule over a neighborhood mask. */279    config(mask: Cell): Config;280    /** Reads a filename back into the value, or an error. */281    static from_file(text: string): Rule;282    /** Reads a JSON object into its canonical value, or an error naming the broken key. */283    static from_json(text: string): Rule;284    /** Reads a path and query string back into the value, or an error. */285    static from_url(text: string): Rule;286    /** Reads the rule out of a life config. */287    static of(config: Config): Rule;288    /** Prints the kind and the `key=value` pairs joined by underscores, lists in brackets, or an error when the name does not read back. */289    to_file(): string;290    /** Prints the first eight hex digits of the sha256 of the canonical JSON. */291    to_id(): string;292    /** Prints the canonical JSON object. */293    to_json(): string;294    /** Prints the kind and the keys as a line of prose for pages, or an error when the name does not read back. */295    to_mrly(): string;296    /** Prints the kind as a path and the keys as a query string, lists comma-joined, or an error when the name does not read back. */297    to_url(): string;298}299export type SourceData = "Evens" | "Odds" | { Random: number } | "Primes" | "Binary" | "Fibonacci" | "GridSquares" | "CarpetFills" | "CarpetVoids" | "NetFills" | "NetVoids" | "TreeFills" | "TreeVoids" | "VoidFills" | "VoidVoids" | "PointFills" | "PointVoids" | "DustFills" | "DustVoids" | "LineFills" | "LineVoids" | "StarFills" | "StarVoids" | { CodeFills: bigint } | { CodeVoids: bigint };300/** A named source of neighbor-count values. */301export class Source {302    private constructor();303    free(): void;304    /** Reads the Source from its plain data. */305    static from(data: SourceData): Source;306    /** Writes the Source as plain data. */307    toJSON(): SourceData;308    /** Returns every fixed sequence, the seeded and coded families excluded. */309    static all(): Source[];310    /** Returns the seventeen mrly design families: the grid, the four classics and their antis. */311    static designs(): Source[];312    /** Returns whether the sequence is a seeded random draw. */313    is_random(): boolean;314    /** Returns the sequence's parseable name, the one string that regenerates it. */315    name(): string;316    /** Returns the six number sequences, the random one listed under seed zero. */317    static numbers(): Source[];318    /** Returns the sequence's OEIS id, or None off the encyclopedia. */319    oeis(): string | undefined;320    /** Parses a sequence name back to its source. */321    static parse(name: string): Source;322    /** Reads a canonical name off the front of the text, returning the tail left over. */323    static read(text: string): [Source, string] | undefined;324}325export declare namespace elementary {326    /** Returns the bit a rule sends the neighbourhood to, reading bit `4l + 2c + r` in Wolfram's numbering off the low bit of each cell. */327    export function output(rule: number, l: number, c: number, r: number): number;328}329export declare namespace render {330    /** Renders one grid to white-on-black PNG bytes at a pixel scale. */331    export function frame(grid: Cell, scale: number): Uint8Array;332}333export declare namespace source {334    /** Generates the sequence's values up to the limit. */335    export function sequence(seq: Source, limit: number): Uint32Array;336}