@thi.ng/cellular 0.1.0 → 0.2.0

package/1d.d.ts

@@ -1,6 +1,6 @@
-import type { IClear, UIntArray } from "@thi.ng/api";
+import type { IClear, TypedArray, UIntArray } from "@thi.ng/api";
 import type { IRandom } from "@thi.ng/random";
-import type { CAConfig1D, CASpec1D, Kernel, Target } from "./api.js";
+import type { CAConfig1D, CASpec1D, Kernel, Target, UpdateImageOpts1D } from "./api.js";
 /**
  * Standard Wolfram automata 3-neighborhood (no history)
  */
@@ -92,6 +92,13 @@ export declare const WOLFRAM7: Kernel;
  * {@link CASpec1D.reset} option. Conversely, if the corresponding bit is _not_
  * set in the rule ID, the cell state will be zeroed too.
  *
+ * ### Update probabilities
+ *
+ * Each cell has an optional update probability, which is initialized to 1.0 by
+ * default (i.e. to always be updated). Use
+ * {@link MultiCA1D.updateProbabilistic} or {@link MultiCA1D.updateImage} to
+ * take these probabilities into account.
+ *
  * ### Wraparound
  *
  * By default the environment is configured to be toroidal, i.e. both left/right
@@ -135,11 +142,12 @@ export declare class MultiCA1D implements IClear {
     numStates: number;
     mask: Uint8Array;
     gens: Uint8Array[];
+    prob: Float32Array;
     constructor(configs: CASpec1D[], width: number, wrap?: boolean);
     get current(): Uint8Array;
     get previous(): Uint8Array;
     clear(): void;
-    clearCurrent(): void;
+    clearTarget(target: Target): void;
     resize(width: number): void;
     /**
      * Sets a parametric pattern in the current generation or mask array.
@@ -162,28 +170,50 @@ export declare class MultiCA1D implements IClear {
      */
     setNoise(target: Target, prob?: number, rnd?: IRandom): this;
     /**
-     * Computes a single new generation using current cell states and mask. See
+     * Computes a single new generation using current cell states and mask only
+     * (no consideration for cell update probabilities, use
+     * {@link MultiCA1D.updateProbabilistic} for that instead). Als see
      * {@link MultiCA1D.updateImage} for batch updates.
      */
     update(): void;
+    /**
+     * Same as {@link MultiCA1D.update}, but also considering cell update
+     * probabilities stored in the {@link MultiCA1D.prob} array.
+     *
+     * @param rnd
+     */
+    updateProbabilistic(rnd?: IRandom): void;
+    /**
+     * Computes (but doesn't apply) the new state for a single cell.
+     *
+     * @param config - CA configuration
+     * @param x - cell index
+     * @param val - current cell value
+     */
+    computeCell({ rule, kernel, weights, fn }: CAConfig1D, x: number, val: number): number;
     /**
      * 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.
+     * given `height` (and assumed to be the same width as this CA instance has
+     * been configured to). Fills given `pixels` array with consecutive
+     * generations.
+     *
+     * @remarks
+     * Via the provided options object, per-generation & per-cell perturbance
+     * settings can be provided for cell states, mask and cell update
+     * probabilities. The latter are only considered if the
+     * {@link UpdateImageOpts1D.probabilistic} option is enabled. This can be
+     * helpful to sporadically introduce noise into the sim, break constant
+     * patterns and/or produce more varied/complex outputs.
+     *
+     * See {@link UpdateImageOpts1D} for further options.
      *
      * @param pixels
      * @param height
-     * @param perturb
-     * @param density
-     * @param rnd
+     * @param opts
      */
-    updateImage(pixels: UIntArray, height: number, perturb?: number, density?: number, rnd?: IRandom): void;
-    rotate(dir: number): void;
-    protected _getTarget(target: Target): [Uint8Array, number];
+    updateImage(pixels: UIntArray, height: number, opts?: Partial<UpdateImageOpts1D>): void;
+    rotate(target: Target | "all", dir: number): void;
+    protected _getTarget(target: Target): [TypedArray, number];
 }
 /**
  * Creates a random rule ID for given `kernelSize` and using optionally provided

package/1d.js

@@ -106,6 +106,13 @@ export const WOLFRAM7 = [[-3, 0], ...WOLFRAM5, [3, 0]];
  * {@link CASpec1D.reset} option. Conversely, if the corresponding bit is _not_
  * set in the rule ID, the cell state will be zeroed too.
  *
+ * ### Update probabilities
+ *
+ * Each cell has an optional update probability, which is initialized to 1.0 by
+ * default (i.e. to always be updated). Use
+ * {@link MultiCA1D.updateProbabilistic} or {@link MultiCA1D.updateImage} to
+ * take these probabilities into account.
+ *
  * ### Wraparound
  *
  * By default the environment is configured to be toroidal, i.e. both left/right
@@ -160,14 +167,17 @@ export class MultiCA1D {
     }
     clear() {
         this.gens.forEach((g) => g.fill(0));
+        this.mask.fill(0);
+        this.prob.fill(1);
     }
-    clearCurrent() {
-        this.current.fill(0);
+    clearTarget(target) {
+        this._getTarget(target)[0].fill(target === "prob" ? 1 : 0);
     }
     resize(width) {
         this.width = width;
         this.mask = new Uint8Array(width);
         this.gens = [...repeatedly(() => new Uint8Array(width), this.rows + 1)];
+        this.prob = new Float32Array(width).fill(1);
     }
     /**
      * Sets a parametric pattern in the current generation or mask array.
@@ -198,71 +208,129 @@ export class MultiCA1D {
      */
     setNoise(target, prob = 0.5, rnd = SYSTEM) {
         const [dest, num] = this._getTarget(target);
+        const fn = target === "prob" ? () => rnd.float() : () => rnd.int() % num;
         for (let x = 0, width = this.width; x < width; x++) {
             if (rnd.float() < prob)
-                dest[x] = rnd.int() % num;
+                dest[x] = fn();
         }
         return this;
     }
     /**
-     * Computes a single new generation using current cell states and mask. See
+     * Computes a single new generation using current cell states and mask only
+     * (no consideration for cell update probabilities, use
+     * {@link MultiCA1D.updateProbabilistic} for that instead). Als see
      * {@link MultiCA1D.updateImage} for batch updates.
      */
     update() {
-        const { width, gens, configs, mask, wrap } = this;
+        const { width, gens, configs, mask } = 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;
+            next[x] = this.computeCell(configs[mask[x]], x, curr[x]);
+        }
+        gens.unshift(gens.pop());
+    }
+    /**
+     * Same as {@link MultiCA1D.update}, but also considering cell update
+     * probabilities stored in the {@link MultiCA1D.prob} array.
+     *
+     * @param rnd
+     */
+    updateProbabilistic(rnd = SYSTEM) {
+        const { width, prob, gens, configs, mask } = this;
+        const [next, curr] = gens;
+        for (let x = 0; x < width; x++) {
+            next[x] =
+                rnd.float() < prob[x]
+                    ? this.computeCell(configs[mask[x]], x, curr[x])
+                    : curr[x];
         }
         gens.unshift(gens.pop());
     }
+    /**
+     * Computes (but doesn't apply) the new state for a single cell.
+     *
+     * @param config - CA configuration
+     * @param x - cell index
+     * @param val - current cell value
+     */
+    computeCell({ rule, kernel, weights, fn }, x, val) {
+        const { width, gens, wrap } = this;
+        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];
+        }
+        return rule & ($1 << sum) ? fn(val) : 0;
+    }
     /**
      * 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.
+     * given `height` (and assumed to be the same width as this CA instance has
+     * been configured to). Fills given `pixels` array with consecutive
+     * generations.
+     *
+     * @remarks
+     * Via the provided options object, per-generation & per-cell perturbance
+     * settings can be provided for cell states, mask and cell update
+     * probabilities. The latter are only considered if the
+     * {@link UpdateImageOpts1D.probabilistic} option is enabled. This can be
+     * helpful to sporadically introduce noise into the sim, break constant
+     * patterns and/or produce more varied/complex outputs.
+     *
+     * See {@link UpdateImageOpts1D} for further options.
      *
      * @param pixels
      * @param height
-     * @param perturb
-     * @param density
-     * @param rnd
+     * @param opts
      */
-    updateImage(pixels, height, perturb = 0, density = 0.05, rnd = SYSTEM) {
+    updateImage(pixels, height, opts = {}) {
+        assert(pixels.length >= this.width * height, "target pixel buffer too small");
+        const { cells, mask, prob, probabilistic, rnd, onupdate } = {
+            probabilistic: false,
+            rnd: SYSTEM,
+            ...opts,
+        };
+        const $ = (id, conf) => {
+            conf &&
+                conf.perturb &&
+                rnd.float() < conf.perturb &&
+                this.setNoise(id, conf.density || 0.05, rnd);
+        };
         for (let y = 0; y < height; y++) {
-            rnd.float() < perturb && this.setNoise("cells", density, rnd);
-            this.update();
+            $("cells", cells);
+            $("mask", mask);
+            $("prob", prob);
+            probabilistic ? this.updateProbabilistic(rnd) : this.update();
+            onupdate && onupdate(this, y);
             pixels.set(this.current, y * this.width);
         }
     }
-    rotate(dir) {
-        __rotate(this.current, dir);
-        __rotate(this.mask, dir);
+    rotate(target, dir) {
+        if (target === "all") {
+            __rotate(this.current, dir);
+            __rotate(this.mask, dir);
+            __rotate(this.prob, dir);
+        }
+        else {
+            __rotate(this._getTarget(target)[0], dir);
+        }
     }
     _getTarget(target) {
         return target === "cells"
             ? [this.current, this.numStates]
-            : [this.mask, this.configs.length];
+            : target === "mask"
+                ? [this.mask, this.configs.length]
+                : [this.prob, 1];
     }
 }
 const __compileSpec = ({ rule, kernel, positional, states, reset, }) => {

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-06-09T16:14:01Z
+- **Last updated**: 2022-06-11T14:24:35Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,17 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/cellular@0.2.0) (2022-06-11)
+
+#### 🚀 Features
+
+- add probabilities, update options ([97e6b4d](https://github.com/thi-ng/umbrella/commit/97e6b4d))
+  - add cell update probabilities
+  - add `updateProbabilistic()`
+  - extract `computeCell()`
+  - add `UpdateImageOpts1D`, update `updateImage()`
+  - replace `clearCurrent()` => `clearTarget()`
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/cellular@0.1.0) (2022-06-09)
 
 #### 🚀 Features

package/api.d.ts

@@ -1,5 +1,7 @@
-import type { FnN, NumericArray } from "@thi.ng/api";
-export declare type Target = "cells" | "mask";
+import type { Fn2, FnN, NumericArray } from "@thi.ng/api";
+import type { IRandom } from "@thi.ng/random";
+import type { MultiCA1D } from "./1d";
+export declare type Target = "cells" | "mask" | "prob";
 export declare type Kernel = NumericArray[];
 export interface CAConfig1D {
     /**
@@ -7,7 +9,10 @@ export interface CAConfig1D {
      */
     kernel: Kernel;
     /**
-     * Same as {@link CASpec1D.weights}.
+     * Weight factors for each kernel offset. If {@link CASpec1D.positional} is
+     * true, these weights will all be `1 << i` where `i` is the index of each
+     * kernel offset vector. If `positional` is false, all weights will be set
+     * to 1.
      */
     weights: bigint[];
     /**
@@ -66,4 +71,47 @@ export interface CASpec1D {
      */
     reset?: boolean;
 }
+export interface UpdateBufferOpts {
+    /**
+     * Per-generation perturbance probability. Default: 0%
+     */
+    perturb: number;
+    /**
+     * Per-cell perturbance probability. Default: 5% (only used if `perturb >
+     * 0`)
+     */
+    density: number;
+}
+export interface UpdateImageOpts1D {
+    /**
+     * Per-generation perturbance options for cell states array
+     */
+    cells: Partial<UpdateBufferOpts>;
+    /**
+     * Per-generation perturbance options for cell mask array
+     */
+    mask: Partial<UpdateBufferOpts>;
+    /**
+     * Per-generation perturbance options for cell update probability array.
+     * Only used if {@link UpdateImageOpts1D.probabilistic} is true.
+     */
+    prob: Partial<UpdateBufferOpts>;
+    /**
+     * If true, each new generation will be updated via
+     * {@link MultiCA1D.updateProbabilistic} instead of
+     * {@link MultiCA1D.update}.
+     */
+    probabilistic: boolean;
+    /**
+     * PRNG instance to use for perturbance. Default:
+     * {@link @thi.ng/random#SYSTEM} aka `Math.random`.
+     */
+    rnd: IRandom;
+    /**
+     * User handler function called immediatedly after each update (computation
+     * of a new generation). The arguments passed are the {@link MultiCA1D}
+     * instance and pixel row index.
+     */
+    onupdate: Fn2<MultiCA1D, number, void>;
+}
 //# sourceMappingURL=api.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/cellular",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -35,10 +35,10 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.3.7",
-    "@thi.ng/checks": "^3.2.0",
+    "@thi.ng/checks": "^3.2.1",
     "@thi.ng/errors": "^2.1.7",
-    "@thi.ng/random": "^3.3.1",
-    "@thi.ng/transducers": "^8.3.4"
+    "@thi.ng/random": "^3.3.2",
+    "@thi.ng/transducers": "^8.3.5"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.25.0",
@@ -92,5 +92,5 @@
     ],
     "year": 2022
   },
-  "gitHead": "9e516d30a1a537e027a6b3d78bf9121bc5831d31\n"
+  "gitHead": "ab0188234419f2d9f471de80871df930e5555bd6\n"
 }