formform.emul — eu.formsandlines/formform 0.2.0

API for the emul module of formform.

Concepts

Cellular Automata

cellular automaton
→ system that iteratively produces the next generation

• automaton → model for the description of rule-based state changes
• iteration → reproduce the operation
• state → correspondence between time and value of the system

evolution
→ causal chain of generations

generation
→ state in an evolution
→ n-dimensional relation between cells

cell
→ system that indicates a calc/value

Specification

ini {sys-ini}
→ initial generation of the cellular automaton
→ configuration of cells by a pattern

• configuration → arrangement by a perspective
• arrangement → selection in space

umwelt
→ arrangement of cells observable from/by the cell
→ environment for rule application

rule {sys-next}
→ function to determine the next state of the cell
→ correspondence between umwelt / self (→Cell) and calc/value

!types clj/s

All registered ini/umwelt/rule types.

apply-rule clj/s

(apply-rule rule-spec umwelt cell)

Returns a cell value given a rule-spec (via make-rule), an umwelt (via observe-umwelt) and the current cell (a vector of the shape [[x ?y] value]).

ca-iterator clj/s

(ca-iterator ca-spec resolution)

(ca-iterator ca-spec resolution steps)

Returns a lazy seq that iteratively computes the next generation for the given a ca-spec (cellular automaton specification, via specify-ca, etc.) and a resolution vector. Optionally, the last argument can be a number to just get the first n steps in its evolution.

common-specimen clj/s

Map of common specimen to specify cellular automata. Contains all the SelFis introduced by Ralf Peyn in ‘uFORM iFORM’.

create-ca clj/s

(create-ca ca-spec resolution)

(create-ca ca-spec resolution history-cache-limit)

Returns a stateful CellularAutomaton object for the given ca-spec (cellular automaton specification, via specify-ca, etc.) and a resolution vector.

May take an optional history-cache-limit to manually set the limit for how many generations will be cached (otherwise an heuristic algorithm is used).

Callable methods are step, restart, get-resolution, get-current-generation, get-cached-history, get-system-time and get-history-cache-limit (see docs for further explanation).

defini clj/s macro

(defini type-k fields doc-string? & methods)

Defines a new type of ini pattern, to be specified with make-ini. Takes a keyword identifier (type-k), fields for data the user needs to provide, an optional doc-string? (to describe the fields and the pattern) and one or more implementations of:

• (make-gen [this opts w] …) for a 1D pattern
• (make-gen [this opts w h] …) for a 2D pattern
• opts is an options map that can have keys such as :seed.

defrule clj/s macro

(defrule type-k fields doc-string? & methods)

Defines a new type of rule pattern, to be specified with make-rule. Takes a keyword identifier (type-k), fields for data the user needs to provide, an optional doc-string? (to describe the fields and the pattern) and one or more implementations of:

• (apply-rule [this umwelt self-v] …)
• umwelt is an ‘umwelt’ as provided by observe-umwelt
• self-v is the value of the currently selected cell

defumwelt clj/s macro

(defumwelt type-k fields doc-string? & methods)

Defines a new type of umwelt pattern, to be specified with make-umwelt. Takes a keyword identifier (type-k), fields for data the user needs to provide, an optional doc-string? (to describe the fields and the pattern) and one or more implementations of:

• (observe-umwelt [this gen1d cell w] …) for a 1D pattern
• (observe-umwelt [this gen2d cell w h] …) for a 2D pattern
• gen1d/gen2d is a vector of the current generation (flat in 1D, nested in 2D)
• cell is a vector [[x …] v] of the current cell coordinates and value

get-cached-history clj/s

(get-cached-history ca-obj)

(get-cached-history ca-obj {:keys [optimized?] :or {optimized? false}})

Given a stateful ca-object (of type CellularAutomaton), returns its cached history/evolution, where all generations are either vectors or native arrays (if optimized? is true).

get-current-generation clj/s

(get-current-generation ca-obj)

(get-current-generation ca-obj {:keys [optimized?] :or {optimized? false}})

Given a stateful ca-object (of type CellularAutomaton), returns its current generation either as a vector or a native array (if optimized? is true).

get-history-cache-limit clj/s

(get-history-cache-limit ca-obj)

Given a stateful ca-object (of type CellularAutomaton), returns the max. number of generations it caches (stored in its history).

get-resolution clj/s

(get-resolution ca-obj)

Given a stateful ca-object (of type CellularAutomaton), returns its resolution.

get-system-time clj/s

(get-system-time ca-obj)

Given a stateful ca-object (of type CellularAutomaton), returns its generation index (aka “system-time”).

ini-patterns clj/s

A collection of predefined patterns for use with :figure inis.

make-decisionform clj/s

(make-decisionform dna initial-size)

(make-decisionform dna initial-size {:keys [overwrites ini-opts]})

Returns a 2D cellular automaton known as a “decisionFORM” given a dna for its rule function and an initial-size for its ini (type :rand-figure).

The last argument can be an options map with keys:

• :overwrites → a map to overwrite any part of the returned CA spec

make-ini clj/s

Creates an instance of a CA ini (initial conditions) specification of a given type (as a keyword) and with given parameters as required by the type.

• (make-ini :help) prints a list of all ini types and their parameters
• (make-ini :t :help) prints the parameters and docs for given type :t

make-lifeform clj/s

(make-lifeform dna)

(make-lifeform dna {:keys [overwrites ini-opts]})

Returns a 2D cellular automaton known as a “lifeFORM” given a dna for its rule function.

The last argument can be an options map with keys:

• :overwrites → a map to overwrite any part of the returned CA spec

make-mindform clj/s

(make-mindform dna ini-spec)

(make-mindform dna ini-spec {:keys [overwrites]})

Returns a 2D cellular automaton known as a “mindFORM” given a dna for its rule function and an ini-spec (via make-ini).

The last argument can be an options map with keys:

• :overwrites → a map to overwrite any part of the returned CA spec

make-rule clj/s

Creates an instance of a CA rule specification of a given type (as a keyword) and with given parameters as required by the type.

• (make-rule :help) prints a list of all rule types and their parameters
• (make-rule :t :help) prints the parameters and docs for given type :t

make-selfi clj/s

(make-selfi dna ini-spec)

(make-selfi dna ini-spec {:keys [overwrites]})

Returns a 1D cellular automaton known as a “SelFi” given a dna for its rule function and an ini-spec (via make-ini). Its ‘umwelt’ is of type :select-ltr.

The last argument can be an options map with keys:

• :overwrites → a map to overwrite any part of the returned CA spec

make-umwelt clj/s

Creates an instance of a CA umwelt (neighborhood) specification of a given type (as a keyword) and with given parameters as required by the type.

• (make-umwelt :help) prints a list of all umwelt types and their parameters
• (make-umwelt :t :help) prints the parameters and docs for given type :t

observe-umwelt clj/s

(observe-umwelt umwelt-spec generation cell)

Returns an ‘umwelt’ given a umwelt-spec (via make-umwelt), a generation and the current cell (a vector of the shape [[x ?y] value]).

restart clj/s

(restart ca-obj)

Given a stateful ca-object (of type CellularAutomaton), resets its evolution to the initial generation.

specify-ca clj/s

(specify-ca specs-map)

(specify-ca specs-map label)

Returns a CASpec record, given a specs-map (which is a map of specifications for a custom cellular automaton) and an optional label. The CASpec can be used with ca-iterator or create-ca. The input map needs to have all of the following entries:

• :rule-spec: a rule specification as per make-rule
• :umwelt-spec: an umwelt specification as per make-umwelt
• :ini-spec: an ini specification as per make-ini

Note that formform.emul has constructors for common ca specs via make-selfi, make-mindform, make-lifeform and make-decisionform. Furthermore, there are predefined ca specs in common-specimen.

step clj/s

(step ca-object)

Given a stateful ca-object (of type CellularAutomaton), computes its next generation and appends it to its evolution state.

sys-ini clj/s

(sys-ini ini-spec resolution)

(sys-ini ini-spec resolution opts)

Returns an (initial) generation given an ini-spec (via make-ini) and a resolution. resolution must be a vector [width] (1D) or [width height] (2D).

The last argument can be an options map with keys:

• :seed → an integer number to provide a seed for reproducable randomness

sys-next clj/s

(sys-next rule-spec umwelt-spec generation)

Computes and returns the next generation given a rule-spec (via make-rule), an umwelt-spec (via make-umwelt) and a generation.