@thi.ng/cellular 0.1.0

package/1d.d.ts

@@ -0,0 +1,196 @@
+import type { IClear, UIntArray } from "@thi.ng/api";
+import type { IRandom } from "@thi.ng/random";
+import type { CAConfig1D, CASpec1D, Kernel, Target } from "./api.js";
+/**
+ * Standard Wolfram automata 3-neighborhood (no history)
+ */
+export declare const WOLFRAM3: Kernel;
+/**
+ * Standard 5-neighborhood (no history)
+ */
+export declare const WOLFRAM5: Kernel;
+/**
+ * Standard 7-neighborhood (no history)
+ */
+export declare const WOLFRAM7: Kernel;
+/**
+ * Implementation of a 1D cellular automata environment with support for
+ * multiple automata, each with its own settings for replication rules,
+ * arbitrary neighborhood kernels (optionally with short term memory) and number
+ * of cell states, all selectable via a shared per-cell mask array. This generic
+ * setup enables many novel and unusual CA setups as well as coevolution of
+ * multiple CAs within a shared environment.
+ *
+ * @remarks
+ * ### Neighborhoods
+ *
+ * Cell neighborhoods are defined via an arbitrary number of 2D offset vectors
+ * `[x, y]`, where `x` coordinates are horizontal offsets and positive `y`
+ * coordinates are used to refer to previous generations (e.g. 0 = current gen,
+ * 1 = T-1, 2 = T-2 etc.) and thereby providing a form of short term memory for
+ * that specific automata. Negative `y` coords will lead to cells being ignored.
+ *
+ * ### Rule encoding
+ *
+ * Automata rules are encoded as JS `BigInt` values and are considered
+ * anisotropic by default. If isotropy is desired, it has to be explicitly
+ * pre-encoded [out of scope of this library]. There's also built-in optional
+ * support for position independent neighborhood encoding, only considering the
+ * number/count of non-zero cells. An encoded rule ID and its overall magnitude
+ * is directly related and dependent on the size and shape of its kernel config,
+ * e.g.:
+ *
+ * ```ts
+ * kernel = [[-2, 1], [-1, 0], [0, 0], [1, 0], [2, 1]]
+ * ```
+ *
+ * This example kernel defines a 5-cell neighborhood with a max. short term
+ * memory of one additional previous generation (i.e. the [-2,1] and [2,1]
+ * offsets)
+ *
+ * The rules related to this kernel have a 32 bit address space (4 billion
+ * possibilities), due to 2^5 = 32 and each kernel offset being assigned a
+ * distinct bit value by default, i.e. first kernel offset = 2^0, second kernel
+ * offset = 2^1, third = 2^2, fourth = 2^3, fifth = 2^4. Via the
+ * {@link CASpec1D.positional} config option, this behavior can be overridden
+ * per kernel, to achieve position-independent kernels (with much smaller rule
+ * spaces).
+ *
+ * Given the following example cell matrix with the center cell highlighted with
+ * caret (`^`):
+ *
+ * ```text
+ * T-1: 2 0 1 2 1
+ * T-0: 0 1 0 3 0
+ *          ^
+ * ```
+ *
+ * The above example kernel will select the following values and assign bit
+ * positions (for all non-zero cell states) to compute a summed ID:
+ *
+ * | k index | offset    | cell value | encoded |
+ * |--------:|-----------|-----------:|--------:|
+ * | 0       | `[-2, 1]` | 2          | 1       |
+ * | 1       | `[-1, 0]` | 1          | 2       |
+ * | 2       | `[0, 0]`  | 0          | 0       |
+ * | 3       | `[1, 0]`  | 3          | 8       |
+ * | 4       | `[2, 1]`  | 1          | 16      |
+ *
+ * Final encoded neighborhood sum: 1 + 2 + 8 + 16 = 27
+ *
+ * To determine if a the current cell should be active or not in the next
+ * generation, we now use that encoded sum as bit position to test a single bit
+ * of the automata's rule ID, i.e. here we're testing bit 27. If that
+ * corresponding bit is set in the rule ID, the cell's state will be increased
+ * by 1.
+ *
+ * ### Cell states
+ *
+ * Each automata config can define a max. number of possible cell states (aka
+ * age). Once a cell reaches the configured `numStates`, it automatically resets
+ * to zero. This is by default, but can be overridden via the
+ * {@link CASpec1D.reset} option. Conversely, if the corresponding bit is _not_
+ * set in the rule ID, the cell state will be zeroed too.
+ *
+ * ### Wraparound
+ *
+ * By default the environment is configured to be toroidal, i.e. both left/right
+ * sides of the env are connected. The behavior can be controlled via a ctor arg
+ * and/or at runtime via the {@link MultiCA1D.wrap} property.
+ *
+ * ### Masks
+ *
+ * The {@link MultiCA1D.mask} array can be used to select different CA
+ * configurations for each cell in the environment. Because this mask array is
+ * initialized to zero, only the first CA configuration will be used for all
+ * cells in the environment by default. It's the user's responsibility to manage
+ * the mask and select/enable other (if any) CA configs for individual cells
+ * (usually cell ranges). The values stored in this array correspond to the
+ * indices of the {@link MultiCA1D.config} array given at construction.
+ *
+ * ### Limits
+ *
+ * Due to using `Uint8Arrays` for storage, only up to 256 cell states are
+ * supported. The same limit applies to the number of CA configs given.
+ *
+ * @example
+ * ```ts
+ * // classic Wolfram Rule 110 automata
+ * const wolfram = new MultiCA1D(
+ *   [{
+ *     kernel: [[-1, 0], [0, 0], [1, 0]],
+ *     rule: 110,
+ *     states: 2,
+ *     reset: false
+ *   }],
+ *   256
+ * )
+ * ```
+ */
+export declare class MultiCA1D implements IClear {
+    width: number;
+    wrap: boolean;
+    configs: CAConfig1D[];
+    rows: number;
+    numStates: number;
+    mask: Uint8Array;
+    gens: Uint8Array[];
+    constructor(configs: CASpec1D[], width: number, wrap?: boolean);
+    get current(): Uint8Array;
+    get previous(): Uint8Array;
+    clear(): void;
+    clearCurrent(): void;
+    resize(width: number): void;
+    /**
+     * Sets a parametric pattern in the current generation or mask array.
+     *
+     * @param target - target buffer ID to apply pattern
+     * @param width - number of consecutive cells per segment
+     * @param stride -  number of cells between each pattern segment
+     * @param val - start cell value per segment
+     * @param inc - cell value increment
+     * @param offset - start cell offset
+     */
+    setPattern(target: Target, width: number, stride: number, val?: number, inc?: number, offset?: number): this;
+    /**
+     * Sets cells in current generation array to a random state using given
+     * `probability` and optional PRNG ({@link @thi.ng/random#IRandom} instance).
+     *
+     * @param target
+     * @param prob
+     * @param rnd
+     */
+    setNoise(target: Target, prob?: number, rnd?: IRandom): this;
+    /**
+     * Computes a single new generation using current cell states and mask. See
+     * {@link MultiCA1D.updateImage} for batch updates.
+     */
+    update(): void;
+    /**
+     * Batch version of {@link MultiCA1D.update} to compute an entire image of
+     * given `height` (and same width as this CA instance has been configured
+     * to). Fill given `pixels` array with consecutive generations. For each
+     * iteration there's `perturb` probability (default: 0%) to call
+     * {@link MultiCA1D.setNoise} with given `density` (default: 5%) and using
+     * optionally provided PRNG. This can be helpful to sporadically introduce
+     * noise into the sim and break otherwise constant patterns emerging.
+     *
+     * @param pixels
+     * @param height
+     * @param perturb
+     * @param density
+     * @param rnd
+     */
+    updateImage(pixels: UIntArray, height: number, perturb?: number, density?: number, rnd?: IRandom): void;
+    rotate(dir: number): void;
+    protected _getTarget(target: Target): [Uint8Array, number];
+}
+/**
+ * Creates a random rule ID for given `kernelSize` and using optionally provided
+ * `rnd` {@link @thi.ng/random#IRandom} instance.
+ *
+ * @param kernelSize
+ * @param rnd
+ */
+export declare const randomRule1D: (kernelSize: number, rnd?: IRandom) => bigint;
+//# sourceMappingURL=1d.d.ts.map

package/1d.js

@@ -0,0 +1,312 @@
+import { isBigInt } from "@thi.ng/checks/is-bigint";
+import { assert } from "@thi.ng/errors/assert";
+import { SYSTEM } from "@thi.ng/random/system";
+import { repeat } from "@thi.ng/transducers";
+import { map } from "@thi.ng/transducers/map";
+import { mapcat } from "@thi.ng/transducers/mapcat";
+import { max } from "@thi.ng/transducers/max";
+import { pluck } from "@thi.ng/transducers/pluck";
+import { repeatedly } from "@thi.ng/transducers/repeatedly";
+import { transduce } from "@thi.ng/transducers/transduce";
+const $0 = BigInt(0);
+const $1 = BigInt(1);
+const $32 = BigInt(32);
+/**
+ * Standard Wolfram automata 3-neighborhood (no history)
+ */
+export const WOLFRAM3 = [
+    [-1, 0],
+    [0, 0],
+    [1, 0],
+];
+/**
+ * Standard 5-neighborhood (no history)
+ */
+export const WOLFRAM5 = [[-2, 0], ...WOLFRAM3, [2, 0]];
+/**
+ * Standard 7-neighborhood (no history)
+ */
+export const WOLFRAM7 = [[-3, 0], ...WOLFRAM5, [3, 0]];
+/**
+ * Implementation of a 1D cellular automata environment with support for
+ * multiple automata, each with its own settings for replication rules,
+ * arbitrary neighborhood kernels (optionally with short term memory) and number
+ * of cell states, all selectable via a shared per-cell mask array. This generic
+ * setup enables many novel and unusual CA setups as well as coevolution of
+ * multiple CAs within a shared environment.
+ *
+ * @remarks
+ * ### Neighborhoods
+ *
+ * Cell neighborhoods are defined via an arbitrary number of 2D offset vectors
+ * `[x, y]`, where `x` coordinates are horizontal offsets and positive `y`
+ * coordinates are used to refer to previous generations (e.g. 0 = current gen,
+ * 1 = T-1, 2 = T-2 etc.) and thereby providing a form of short term memory for
+ * that specific automata. Negative `y` coords will lead to cells being ignored.
+ *
+ * ### Rule encoding
+ *
+ * Automata rules are encoded as JS `BigInt` values and are considered
+ * anisotropic by default. If isotropy is desired, it has to be explicitly
+ * pre-encoded [out of scope of this library]. There's also built-in optional
+ * support for position independent neighborhood encoding, only considering the
+ * number/count of non-zero cells. An encoded rule ID and its overall magnitude
+ * is directly related and dependent on the size and shape of its kernel config,
+ * e.g.:
+ *
+ * ```ts
+ * kernel = [[-2, 1], [-1, 0], [0, 0], [1, 0], [2, 1]]
+ * ```
+ *
+ * This example kernel defines a 5-cell neighborhood with a max. short term
+ * memory of one additional previous generation (i.e. the [-2,1] and [2,1]
+ * offsets)
+ *
+ * The rules related to this kernel have a 32 bit address space (4 billion
+ * possibilities), due to 2^5 = 32 and each kernel offset being assigned a
+ * distinct bit value by default, i.e. first kernel offset = 2^0, second kernel
+ * offset = 2^1, third = 2^2, fourth = 2^3, fifth = 2^4. Via the
+ * {@link CASpec1D.positional} config option, this behavior can be overridden
+ * per kernel, to achieve position-independent kernels (with much smaller rule
+ * spaces).
+ *
+ * Given the following example cell matrix with the center cell highlighted with
+ * caret (`^`):
+ *
+ * ```text
+ * T-1: 2 0 1 2 1
+ * T-0: 0 1 0 3 0
+ *          ^
+ * ```
+ *
+ * The above example kernel will select the following values and assign bit
+ * positions (for all non-zero cell states) to compute a summed ID:
+ *
+ * | k index | offset    | cell value | encoded |
+ * |--------:|-----------|-----------:|--------:|
+ * | 0       | `[-2, 1]` | 2          | 1       |
+ * | 1       | `[-1, 0]` | 1          | 2       |
+ * | 2       | `[0, 0]`  | 0          | 0       |
+ * | 3       | `[1, 0]`  | 3          | 8       |
+ * | 4       | `[2, 1]`  | 1          | 16      |
+ *
+ * Final encoded neighborhood sum: 1 + 2 + 8 + 16 = 27
+ *
+ * To determine if a the current cell should be active or not in the next
+ * generation, we now use that encoded sum as bit position to test a single bit
+ * of the automata's rule ID, i.e. here we're testing bit 27. If that
+ * corresponding bit is set in the rule ID, the cell's state will be increased
+ * by 1.
+ *
+ * ### Cell states
+ *
+ * Each automata config can define a max. number of possible cell states (aka
+ * age). Once a cell reaches the configured `numStates`, it automatically resets
+ * to zero. This is by default, but can be overridden via the
+ * {@link CASpec1D.reset} option. Conversely, if the corresponding bit is _not_
+ * set in the rule ID, the cell state will be zeroed too.
+ *
+ * ### Wraparound
+ *
+ * By default the environment is configured to be toroidal, i.e. both left/right
+ * sides of the env are connected. The behavior can be controlled via a ctor arg
+ * and/or at runtime via the {@link MultiCA1D.wrap} property.
+ *
+ * ### Masks
+ *
+ * The {@link MultiCA1D.mask} array can be used to select different CA
+ * configurations for each cell in the environment. Because this mask array is
+ * initialized to zero, only the first CA configuration will be used for all
+ * cells in the environment by default. It's the user's responsibility to manage
+ * the mask and select/enable other (if any) CA configs for individual cells
+ * (usually cell ranges). The values stored in this array correspond to the
+ * indices of the {@link MultiCA1D.config} array given at construction.
+ *
+ * ### Limits
+ *
+ * Due to using `Uint8Arrays` for storage, only up to 256 cell states are
+ * supported. The same limit applies to the number of CA configs given.
+ *
+ * @example
+ * ```ts
+ * // classic Wolfram Rule 110 automata
+ * const wolfram = new MultiCA1D(
+ *   [{
+ *     kernel: [[-1, 0], [0, 0], [1, 0]],
+ *     rule: 110,
+ *     states: 2,
+ *     reset: false
+ *   }],
+ *   256
+ * )
+ * ```
+ */
+export class MultiCA1D {
+    constructor(configs, width, wrap = true) {
+        this.width = width;
+        this.wrap = wrap;
+        this.configs = configs.map(__compileSpec);
+        this.rows =
+            transduce(mapcat((c) => map((k) => k[1], c.kernel)), max(), configs) + 1;
+        this.numStates = transduce(pluck("states"), max(), configs);
+        assert(this.numStates >= 2 && this.numStates <= 256, "num states must be in [2..256] range");
+        this.resize(width);
+    }
+    get current() {
+        return this.gens[1];
+    }
+    get previous() {
+        return this.gens[2 % this.gens.length];
+    }
+    clear() {
+        this.gens.forEach((g) => g.fill(0));
+    }
+    clearCurrent() {
+        this.current.fill(0);
+    }
+    resize(width) {
+        this.width = width;
+        this.mask = new Uint8Array(width);
+        this.gens = [...repeatedly(() => new Uint8Array(width), this.rows + 1)];
+    }
+    /**
+     * Sets a parametric pattern in the current generation or mask array.
+     *
+     * @param target - target buffer ID to apply pattern
+     * @param width - number of consecutive cells per segment
+     * @param stride -  number of cells between each pattern segment
+     * @param val - start cell value per segment
+     * @param inc - cell value increment
+     * @param offset - start cell offset
+     */
+    setPattern(target, width, stride, val = 1, inc = 0, offset = 0) {
+        const [dest, num] = this._getTarget(target);
+        for (let x = offset, w = this.width; x < w; x += stride) {
+            for (let k = 0, v = val; k < width; k++, v += inc) {
+                dest[x + k] = v % num;
+            }
+        }
+        return this;
+    }
+    /**
+     * Sets cells in current generation array to a random state using given
+     * `probability` and optional PRNG ({@link @thi.ng/random#IRandom} instance).
+     *
+     * @param target
+     * @param prob
+     * @param rnd
+     */
+    setNoise(target, prob = 0.5, rnd = SYSTEM) {
+        const [dest, num] = this._getTarget(target);
+        for (let x = 0, width = this.width; x < width; x++) {
+            if (rnd.float() < prob)
+                dest[x] = rnd.int() % num;
+        }
+        return this;
+    }
+    /**
+     * Computes a single new generation using current cell states and mask. See
+     * {@link MultiCA1D.updateImage} for batch updates.
+     */
+    update() {
+        const { width, gens, configs, mask, wrap } = this;
+        const [next, curr] = gens;
+        for (let x = 0; x < width; x++) {
+            const { rule, kernel, weights, fn } = configs[mask[x]];
+            let sum = $0;
+            for (let i = 0, n = kernel.length; i < n; i++) {
+                const k = kernel[i];
+                let xx = x + k[0];
+                if (wrap) {
+                    if (xx < 0)
+                        xx += width;
+                    else if (xx >= width)
+                        xx -= width;
+                }
+                else if (xx < 0 || xx >= width)
+                    continue;
+                const y = k[1];
+                if (y >= 0 && gens[1 + y][xx] !== 0)
+                    sum += weights[i];
+            }
+            next[x] = rule & ($1 << sum) ? fn(curr[x]) : 0;
+        }
+        gens.unshift(gens.pop());
+    }
+    /**
+     * Batch version of {@link MultiCA1D.update} to compute an entire image of
+     * given `height` (and same width as this CA instance has been configured
+     * to). Fill given `pixels` array with consecutive generations. For each
+     * iteration there's `perturb` probability (default: 0%) to call
+     * {@link MultiCA1D.setNoise} with given `density` (default: 5%) and using
+     * optionally provided PRNG. This can be helpful to sporadically introduce
+     * noise into the sim and break otherwise constant patterns emerging.
+     *
+     * @param pixels
+     * @param height
+     * @param perturb
+     * @param density
+     * @param rnd
+     */
+    updateImage(pixels, height, perturb = 0, density = 0.05, rnd = SYSTEM) {
+        for (let y = 0; y < height; y++) {
+            rnd.float() < perturb && this.setNoise("cells", density, rnd);
+            this.update();
+            pixels.set(this.current, y * this.width);
+        }
+    }
+    rotate(dir) {
+        __rotate(this.current, dir);
+        __rotate(this.mask, dir);
+    }
+    _getTarget(target) {
+        return target === "cells"
+            ? [this.current, this.numStates]
+            : [this.mask, this.configs.length];
+    }
+}
+const __compileSpec = ({ rule, kernel, positional, states, reset, }) => {
+    const max = states - 1;
+    return {
+        kernel,
+        states,
+        rule: isBigInt(rule) ? rule : BigInt(rule),
+        weights: positional !== false
+            ? kernel.map((_, i) => BigInt(2) ** BigInt(i))
+            : [...repeat($1, kernel.length)],
+        fn: reset !== false
+            ? (y) => (++y >= states ? 0 : y)
+            : (y) => (++y >= max ? max : y),
+    };
+};
+const __rotate = (buf, dir) => {
+    if (dir < 0) {
+        const tmp = buf.slice(0, -dir);
+        buf.copyWithin(0, -dir);
+        buf.set(tmp, buf.length + dir);
+    }
+    else if (dir > 0) {
+        const tmp = buf.slice(buf.length - dir);
+        buf.copyWithin(dir, 0);
+        buf.set(tmp, 0);
+    }
+};
+/**
+ * Creates a random rule ID for given `kernelSize` and using optionally provided
+ * `rnd` {@link @thi.ng/random#IRandom} instance.
+ *
+ * @param kernelSize
+ * @param rnd
+ */
+export const randomRule1D = (kernelSize, rnd = SYSTEM) => {
+    const n = BigInt(2 ** kernelSize);
+    let id = $0;
+    for (let i = $0; i < n; i += $32) {
+        id <<= $32;
+        let mask = n - i;
+        if (mask > $32)
+            mask = $32;
+        id |= BigInt(rnd.int()) & (($1 << mask) - $1);
+    }
+    return id;
+};

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Change Log
+
+- **Last updated**: 2022-06-09T16:14:01Z
+- **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org/) for commit guidelines.
+
+**Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
+and/or version bumps of transitive dependencies.
+
+## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/cellular@0.1.0) (2022-06-09)
+
+#### 🚀 Features
+
+- add kernel presets, simplify CASpec1D ([3ee4a25](https://github.com/thi-ng/umbrella/commit/3ee4a25))
+- update setPattern/setNoise() ([2ef2013](https://github.com/thi-ng/umbrella/commit/2ef2013))
+  - add support to operate on diff target buffers (cells/mask)
+- import as new pkg ([aaec2ed](https://github.com/thi-ng/umbrella/commit/aaec2ed))

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,310 @@
+<!-- This file is generated - DO NOT EDIT! -->
+
+# ![cellular](https://media.thi.ng/umbrella/banners/thing-cellular.svg?1a3e0e44)
+
+[![npm version](https://img.shields.io/npm/v/@thi.ng/cellular.svg)](https://www.npmjs.com/package/@thi.ng/cellular)
+![npm downloads](https://img.shields.io/npm/dm/@thi.ng/cellular.svg)
+[![Twitter Follow](https://img.shields.io/twitter/follow/thing_umbrella.svg?style=flat-square&label=twitter)](https://twitter.com/thing_umbrella)
+
+This project is part of the
+[@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
+
+- [About](#about)
+  - [Neighborhoods](#neighborhoods)
+  - [Rule encoding](#rule-encoding)
+  - [Cell states](#cell-states)
+  - [Wraparound](#wraparound)
+  - [Masks](#masks)
+  - [Limits](#limits)
+  - [Status](#status)
+  - [Related packages](#related-packages)
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [API](#api)
+- [Code examples](#code-examples)
+  - [Classic Wolfram](#classic-wolfram)
+  - [Custom kernels & multiple rules](#custom-kernels--multiple-rules)
+- [Authors](#authors)
+- [License](#license)
+
+## About
+
+![Custom cellular automata w/ 7-neighborhood & 128 states](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/cellular/hero.png)
+
+Highly customizable 1D cellular automata, shared env, multiple rules, arbitrary sized/shaped neighborhoods, short term memory, cell states etc..
+
+The generic implementation provided by this package enables many novel and
+unusual CA setups as well as coevolution of multiple CAs within a shared
+environment.
+
+This library also forms the core of **C-SCAPE**, a generative art project by the
+author. Visit the [project site](https://www.fxhash.xyz/generative/slug/c-scape)
+to get a better impression and overview of the multitude of possible results
+(still nothing more than a small glimpse only)...
+
+### Neighborhoods
+
+Cell neighborhoods are defined via an arbitrary number of 2D offset vectors `[x,
+y]`, where `x` coordinates are horizontal offsets and positive `y` coordinates
+are used to refer to previous generations (e.g. 0 = current gen, 1 = T-1, 2 =
+T-2 etc.) and thereby providing a form of short term memory for that specific
+automata. Negative `y` coords will lead to cells being ignored.
+
+### Rule encoding
+
+Automata rules are encoded as JS `BigInt` values and are considered anisotropic
+by default. If isotropy is desired, it has to be explicitly pre-encoded (out of
+scope of this library). There's also built-in optional support for position
+independent neighborhood encoding, only considering the number/count of non-zero
+cells. An encoded rule ID and its overall magnitude is directly related and
+dependent on the size and shape of its kernel config, e.g.:
+
+```ts
+kernel = [[-2, 1], [-1, 0], [0, 0], [1, 0], [2, 1]]
+```
+
+This example kernel defines a 5-cell neighborhood with a max. short term memory
+of one additional previous generation (i.e. the [-2,1] and [2,1] offsets)
+
+The rules related to this kernel have a 32 bit address space (4 billion
+possibilities), due to 2^5 = 32 and each kernel offset being assigned a distinct
+bit value by default, i.e. first kernel offset = 2^0, second kernel offset =
+2^1, third = 2^2, fourth = 2^3, fifth = 2^4. Via the `positional` config option,
+this behavior can be overridden per kernel, to achieve position-independent
+kernels (with much smaller rule spaces).
+
+Given the following example cell matrix with the center cell highlighted with
+caret (`^`):
+
+```text
+T-1: 2 0 1 2 1
+T-0: 0 1 0 3 0
+         ^
+```
+
+The above example kernel will select the following values and assign bit
+positions (for all non-zero cell states) to compute a summed ID:
+
+| k index | offset    | cell value |  encoded |
+|--------:|-----------|-----------:|---------:|
+|       0 | `[-2, 1]` |          2 |  2^0 = 1 |
+|       1 | `[-1, 0]` |          1 |  2^1 = 2 |
+|       2 | `[0, 0]`  |          0 |        0 |
+|       3 | `[1, 0]`  |          3 |  2^3 = 8 |
+|       4 | `[2, 1]`  |          1 | 2^4 = 16 |
+
+Final encoded neighborhood sum: 1 + 2 + 8 + 16 = 27
+
+To determine if a the current cell should be active or not in the next
+generation, we now use that encoded sum as bit position to test a single bit of
+the automata's rule ID, i.e. here we're testing bit 27. If that corresponding
+bit is set in the rule ID, the cell's state will be increased by 1.
+
+### Cell states
+
+Each automata config can define a max. number of possible cell states (aka age).
+Once a cell reaches the configured `numStates`, it automatically resets to zero.
+This is by default, but can be overridden via the `reset` option. Conversely, if
+the corresponding bit is _not_ set in the rule ID, the cell state will be zeroed
+too.
+
+### Wraparound
+
+By default the environment is configured to be toroidal, i.e. both left/right
+sides of the env are connected. The behavior can be controlled via a ctor arg
+and/or at runtime via the `wrap` property.
+
+### Masks
+
+The `mask` array can be used to select different CA configurations for each cell
+in the environment. Because this mask array is initialized to zero, only the
+first CA configuration will be used for all cells in the environment by default.
+It's the user's responsibility to manage the mask and select/enable other (if
+any) CA configs for individual cells (usually cell ranges). The values stored in
+this array correspond to the indices of the CA configurations given at
+construction.
+
+### Limits
+
+Due to using `Uint8Arrays` for storage, only up to 256 cell states are
+supported. The same limit applies to the number of CA configs given.
+
+### Status
+
+**STABLE** - used in production
+
+[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bcellular%5D+in%3Atitle)
+
+### Related packages
+
+- [@thi.ng/lsys](https://github.com/thi-ng/umbrella/tree/develop/packages/lsys) - Functional, extensible L-System architecture w/ support for probabilistic rules
+- [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel) - Typedarray integer & float pixel buffers w/ customizable formats, blitting, drawing, convolution
+
+## Installation
+
+```bash
+yarn add @thi.ng/cellular
+```
+
+ES module import:
+
+```html
+<script type="module" src="https://cdn.skypack.dev/@thi.ng/cellular"></script>
+```
+
+[Skypack documentation](https://docs.skypack.dev/)
+
+For Node.js REPL:
+
+```text
+# with flag only for < v16
+node --experimental-repl-await
+
+> const cellular = await import("@thi.ng/cellular");
+```
+
+Package sizes (gzipped, pre-treeshake): ESM: 1.24 KB
+
+## Dependencies
+
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random)
+- [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
+
+## API
+
+[Generated API docs](https://docs.thi.ng/umbrella/cellular/)
+
+## Code examples
+
+### Classic Wolfram
+
+```ts
+import { MultiCA1D } from "@thi.ng/cellular";
+import { defIndexed, intBuffer } from "@thi.ng/pixel";
+import { asPPM } from "@thi.ng/pixel-io-netpbm";
+import { writeFileSync } from "fs";
+
+const WIDTH = 512;
+const HEIGHT = 512;
+
+// define standard 1D Wolfram CA (3-neighborhood, 2 states)
+const ca = new MultiCA1D(
+    [
+        {
+            rule: 73,
+            // kernel can be imported as `WOLFRAM3`
+            kernel: [[-1, 0],[0, 0],[1, 0]],
+            states: 2,
+            reset: false,
+        },
+    ],
+    WIDTH
+);
+
+// seed a single cell in center
+ca.current[WIDTH/2] = 1;
+
+// create image with indexed color model (2 cell states => 2 colors)
+const img = intBuffer(WIDTH, HEIGHT, defIndexed([0xff000000, 0xffffffff]));
+
+// compute the CA for entire image
+ca.updateImage(img.data, HEIGHT);
+
+// write as PPM file
+writeFileSync("export/out.ppm", asPPM(img));
+```
+
+Result:
+
+![1D Wolfram CA, rule 73](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/cellular/wolfram-73.png)
+
+### Custom kernels & multiple rules
+
+```ts
+import { multiColorGradient, srgb } from "@thi.ng/color";
+
+// create CA with 2 rules/kernels (5-neighborhoods) and 64 states (max age)
+const ca = new MultiCA1D(
+    [
+        {
+            rule: 0x73ed2ac2,
+            // kernel can be imported as `WOLFRAM5`
+            kernel: [[-2, 0], [-1, 0], [0, 0], [1, 0], [2, 0]],
+            states: 64,
+        },
+        {
+            rule: 0xef14e4ca,
+            // kernel can be imported as `WOLFRAM5`
+            kernel: [[-2, 0], [-1, 0], [0, 0], [1, 0], [2, 0]],
+            states: 64,
+        }
+    ],
+    WIDTH
+);
+
+// seed cells with 10% noise
+ca.setNoise("cells", 0.1);
+
+// set mask to stripe pattern to select both CAs
+ca.setPattern("mask", WIDTH / 4, WIDTH / 2, 1, 0, WIDTH / 8);
+
+// alternatively apply noise to the mask to create
+// more uniformly hybrid/mixed results
+// ca.setNoise("mask", 0.5);
+
+// create color gradient to visualize the different cell states
+// and wrap as indexed color model for pixel buffer below...
+// references:
+// https://docs.thi.ng/umbrella/color/modules.html#multiColorGradient
+// https://docs.thi.ng/umbrella/pixel/modules.html#defIndexed
+const fmt = defIndexed(
+    multiColorGradient(
+        {
+            num: ca.numStates,
+            stops: [
+                [0, srgb(1, 0, 0.5)],
+                [0.02, srgb(0.8, 1, 1)],
+                [1, srgb(1, 0.5, 0)],
+            ],
+        },
+        false
+    )
+);
+
+// create image / pixel buffer using above indexed color model
+const img = intBuffer(WIDTH, HEIGHT, fmt);
+
+// compute CA for full image
+ca.updateImage(img.data, HEIGHT);
+
+// export as PPM image
+writeFileSync("export/out.ppm", asPPM(img));
+```
+
+| 1st CA only                                                                                       | 2nd CA only                                                                                     |
+|---------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/cellular/hybrid-a.png)       | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/cellular/hybrid-b.png)     |
+| Hybrid (stripe pattern)                                                                           | Hybrid (noise)                                                                                  |
+| ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/cellular/hybrid-pattern.png) | ![](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/cellular/hybrid-noise.png) |
+
+## Authors
+
+Karsten Schmidt
+
+If this project contributes to an academic publication, please cite it as:
+
+```bibtex
+@misc{thing-cellular,
+  title = "@thi.ng/cellular",
+  author = "Karsten Schmidt",
+  note = "https://thi.ng/cellular",
+  year = 2022
+}
+```
+
+## License
+
+&copy; 2022 Karsten Schmidt // Apache Software License 2.0

package/api.d.ts

@@ -0,0 +1,69 @@
+import type { FnN, NumericArray } from "@thi.ng/api";
+export declare type Target = "cells" | "mask";
+export declare type Kernel = NumericArray[];
+export interface CAConfig1D {
+    /**
+     * Same as {@link CASpec1D.kernel}.
+     */
+    kernel: Kernel;
+    /**
+     * Same as {@link CASpec1D.weights}.
+     */
+    weights: bigint[];
+    /**
+     * Same as {@link CASpec1D.rule}, but always a bigint.
+     */
+    rule: bigint;
+    /**
+     * Same as {@link CASpec1D.states}.
+     */
+    states: number;
+    /**
+     * Cell state update function/behavior. Takes a current cell state, returns
+     * new one.
+     */
+    fn: FnN;
+}
+export interface CASpec1D {
+    /**
+     * Array of 2D offset vectors `[x, y]` defining the automata's neighborhood.
+     * `x` coordinates are horizontal offsets and positive `y` coordinates are
+     * used to refer to previous generations (e.g. 0 = current gen, 1 = T-1, 2 =
+     * T-2 etc.) and thereby providing a form of short term memory for that
+     * specific automata. Negative `y` coords will lead to cells being ignored.
+     *
+     * Unless {@link CASpec1D.positional} is false (default: true), the order of
+     * offsets _is_ important: Whenever the offset relates to a non-zero cell in the
+     * neighborhood, it will contribute a specific bit value to encode the
+     * overall state of the neighborhood, i.e. 2^k, where `k` is the array index
+     * of the corresponding kernel offset.
+     */
+    kernel: Kernel;
+    /**
+     * If false (default: true), the order of kernel offsets is irrelevant and
+     * only the count of non-zero cells in the neighborhood is used to check a
+     * relevant bit in the `rule` ID. E.g. if count = 3, then the 3rd LSB will
+     * be checked.
+     */
+    positional?: boolean;
+    /**
+     * CA replication rules encoded as bigint. The overall magnitude of these
+     * rule IDs depends on the size of the neighborhood kernel and will be 2^n
+     * bits, where `n` is the kernel size. E.g. A 5-neighborhood will offer 2^32
+     * = 4 billion possibilities. A 7-neighborhood corresponds to a 2^7 = 128
+     * bit large rule space (~10^38 possibilities!).
+     */
+    rule: bigint | number | string;
+    /**
+     * Max number of cell states (aka cell age). Note: MUST be <= 256. For
+     * "standard" Wolfram automata, states = 2.
+     */
+    states: number;
+    /**
+     * If true (default), cells will reset to zero once their max. age has been
+     * reached. Should be set to `false` for "standard" 2-state Wolfram
+     * automata.
+     */
+    reset?: boolean;
+}
+//# sourceMappingURL=api.d.ts.map

package/api.js

@@ -0,0 +1 @@
+export {};

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./api.js";
+export * from "./1d.js";
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,2 @@
+export * from "./api.js";
+export * from "./1d.js";

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@thi.ng/cellular",
+  "version": "0.1.0",
+  "description": "Highly customizable 1D cellular automata, shared env, multiple rules, arbitrary sized/shaped neighborhoods, short term memory, cell states etc.",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://github.com/thi-ng/umbrella/tree/master/packages/cellular#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt <k+npm@thi.ng>",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn clean && tsc --declaration",
+    "clean": "rimraf '*.js' '*.d.ts' '*.map' doc",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "yarn doc:stats && tools:readme",
+    "doc:stats": "tools:module-stats",
+    "pub": "yarn npm publish --access public",
+    "test": "testament test"
+  },
+  "dependencies": {
+    "@thi.ng/api": "^8.3.7",
+    "@thi.ng/checks": "^3.2.0",
+    "@thi.ng/errors": "^2.1.7",
+    "@thi.ng/random": "^3.3.1",
+    "@thi.ng/transducers": "^8.3.4"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.25.0",
+    "@thi.ng/testament": "^0.2.8",
+    "rimraf": "^3.0.2",
+    "tools": "^0.0.1",
+    "typedoc": "^0.22.17",
+    "typescript": "^4.7.3"
+  },
+  "keywords": [
+    "1d",
+    "automata",
+    "bigint",
+    "cellular",
+    "generative",
+    "neighborhood",
+    "pixel",
+    "rulebased",
+    "simulation",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "*.js",
+    "*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./1d": {
+      "default": "./1d.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    }
+  },
+  "thi.ng": {
+    "related": [
+      "lsys",
+      "pixel"
+    ],
+    "year": 2022
+  },
+  "gitHead": "9e516d30a1a537e027a6b3d78bf9121bc5831d31\n"
+}