flocc 0.5.18 → 0.5.21

package/dist/agents/Agent.d.ts

@@ -8,41 +8,105 @@ declare interface RuleObj {
     args: Array<any>;
 }
 /**
+ * This class puts the `Agent` in 'agent-based modeling.' More specifically,
+ * an `Agent` represents an individual unit of data and its associated
+ * behaviors.
  * @since 0.0.5
  */
 declare class Agent implements DataObj {
     /**
-     * @member {Environment|null} environment
-     * @member {RuleObj[]} rules
-     * @member {RuleObj[]} queue
-     * @member {Object} data
+     * An `Agent` can only belong to a single {@linkcode Environment}. When
+     * `environment.addAgent(agent);` is called, this is value is updated
+     * to point to that `Environment`.
+     *
+     * ```js
+     * const environment = new Environment();
+     * const agent = new Agent();
+     * agent.environment; // returns `null`
+     *
+     * environment.addAgent(agent);
+     * agent.environment === environment; // returns `true`
      */
     environment: Environment;
+    /** @hidden */
     rules: Array<RuleObj>;
+    /** @hidden */
     queue: Array<RuleObj>;
+    /** @hidden */
     data: Data;
+    /**
+     * `Agent`s are automatically assigned a unique ID when they are created.
+     * This can be useful when you need to refer to a specific `Agent`, and
+     * they can be retrieved using their ID from their `Environment` by calling
+     * {@link Environment.getAgentById | `environment.getAgentById(id);`}
+     * ```js
+     * const agent = new Agent();
+     * const id = agent.id; // returns "59B4F928-46C8-..." (for example)
+     * ```
+     */
     id: string;
+    /**
+     * This is used as a temporary store for data that
+     * gets returned from rules. When enqueued rules are executed,
+     * even if there aren't any enqueued rules, .set gets called
+     * on any data that was placed here.
+     * @hidden
+     */
     __newData: Data;
+    /** When agent.get('key') is called, this pseudo-private member is set to 'key'.
+     * Once it is retrieved, it is reset to null. If agent.get('key') is called before
+     * this has been reset, that means that there is an infinite loop, and the call
+     * will throw an error.
+     * @hidden
+     */
     __retrievingData: string;
+    /** @hidden */
     __subtree: KDTree;
+    /**
+     * `Agent`s can be instantiated with or without data. Instantiating
+     * with data is equivalent to creating an `Agent` and immediately
+     * calling {@linkcode Agent.set} to add data.
+     *
+     * ```js
+     * // instantiates an Agent without data
+     * const a = new Agent();
+     *
+     * // instantiates an Agent with data
+     * const b = new Agent({
+     *   x: 50,
+     *   y: 100
+     * });
+     * ```
+     * @param data
+     */
     constructor(data?: Data);
     /**
      * Set a function value. `tick` and `queue` are not automatically called,
      * but any other named value will automatically be called when referenced.
-     * @param {string} name
-     * @param {Function} fn
+     * @hidden
      */
     _setFunctionValue(name: string, fn: Function): void;
     /**
-     * Retrieve an arbitrary piece of data associated
-     * with this agent by name.
-     * @param {string} name
+     * Retrieve an arbitrary piece of data associated by name.
+     * If the data has not been {@linkcode set}, returns `null`.
      * @since 0.0.5
      */
     get(name: string): any;
     /**
-     * Retrieve all the data associated with this agent
-     * (useful for destructuring properties).
+     * Retrieve all the data associated with this `Agent` at once.
+     *
+     * ```js
+     * agent.set('x', 3);
+     * agent.set('color', 'blue');
+     * agent.set('active', false);
+     *
+     * agent.getData();
+     * // returns {
+     * //   x: 3,
+     * //   color: 'blue',
+     * //   active: false
+     * // }
+     * ```
      * @since 0.1.0
      */
     getData(): Data;
@@ -60,60 +124,133 @@ declare class Agent implements DataObj {
     /**
      * Helper function to set key-value pair depending on whether value
      * is a function (callable) or not
+     * @hidden
      */
     _setKeyValue(key: string, value: any): void;
     /**
-     * Increment a numeric (assume integer) piece of data
-     * associated with this agent. If `n` is included, increments by
-     * `n`. If the value has not yet been set, initializes it to 1.
-     * @param {string} name
-     * @param {number} n
+     * increment a numeric piece of data associated with this `Agent`
+     * (increasing its value by 1). This method is *synchronous* &mdash;
+     * it immediately increases the value (to *asynchronously* increase it,
+     * the rule function should instead return a new value.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.increment('x');
+     * agent.get('x'); // returns 51
+     * ```
+     *
+     * If the second parameter `n` is included, decrements by that amount.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.increment('x', 10);
+     * agent.get('x'); // returns 60
+     * ```
+     *
+     * If the value has not yet been set, calling this method sets it to `1`
+     * (or to `n`).
      * @since 0.0.8
      */
     increment(name: string, n?: number): void;
     /**
-     * Decrement a numeric (assume integer) piece of data
-     * associated with this agent. If `n` is included, decrements by
-     * `n`. If the value has not yet been set,
-     * initializes it to -1.
-     * @param {string} name
+     * Decrement a numeric piece of data associated with this `Agent`
+     * (decreasing its value by 1). This method is *synchronous* &mdash;
+     * it immediately decreases the value (to *asynchronously* decrease it,
+     * the rule function should instead return a new value.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.decrement('x');
+     * agent.get('x'); // returns 49
+     * ```
+     *
+     * If the second parameter `n` is included, decrements by that amount.
+     *
+     * ```js
+     * agent.set('x', 50);
+     * agent.decrement('x', 10);
+     * agent.get('x'); // returns 40
+     * ```
+     *
+     * If the value has not yet been set, calling this method sets it to `-1`
+     * (or to `-n`).
      * @since 0.0.8
      */
     decrement(name: string, n?: number): void;
     /**
-     * Add a rule to be executed during the agent's
-     * environment's tick cycle. When executed, the
-     * @param {Function | Rule} rule
+     * Until v0.5.14, this was the preferred way to add behavior to `Agent`s.
+     * Now, the preferred method is by setting the `Agent`'s `"tick"` value (i.e. `agent.set({ tick: function(agt) { ... }})`).
+     * This method will still be allowed until v0.7.0.
+     *
+     * Adds a rule (a function taking an `Agent` as a callback or a {@linkcode Rule} object) that may be run with every {@linkcode Environment.tick}.
+     * It is possible to add *more than one rule* to an `Agent`, although it
+     * is generally easier to write a longer function or to break it apart
+     * into multiple functions.
+     *
+     * ```js
+     * // adds a rule that *synchronously* increments the Agent's "x" value
+     * agent.addRule(function(agt) {
+     *   agent.increment('x');
+     * });
+     *
+     * // adds a rule that *asynchronously* increments the Agent's "x" value
+     * agent.addRule(function(agt) {
+     *   return {
+     *     x: agt.get('x') + 1
+     *   };
+     * });
+     * ```
+     *
      * @deprecated since version 0.5.14
      * @since 0.0.5
      */
     addRule(rule: Function | Rule, ...args: Array<any>): void;
     /**
-     * Enqueue a function to be executed at the end of
-     * the agent's environment's tick cycle (for example,
-     * if agents in an environment should perform their
-     * calculations and updates separately). Additional/external
-     * data passed in as arguments to the enqueued function will
+     * Like {@linkcode Agent.addRule}, this method is deprecated and the
+     * recommended way is to now call
+     * `agent.set('queue', function(agt) { ... });`
+     *
+     * Calling this method enqueues a function to be executed
+     * *asynchronously* (at the end of the {@linkcode Environment}'s tick cycle).
+     * This is useful if a 'cleanup pass' should be performed between
+     * time steps to adjust `Agent` data.
+     *
+     * Below, the `Agent` sets its `"x"` value to `30` whenever it is
+     * activated during the `Environment`'s tick cycle. After all of that
+     * cycle's `Agent`s have been activated, this `Agent` sets its `"x"`
+     * value to `20`. So if any other `Agent` references its `"x"` value
+     * during a tick cycle after it has been activated, it will return `30`,
+     * but in between tick cycles it will return `20`.
+     *
+     * ```js
+     * agent.addRule(agt => {
+     *   agt.set("x", 30);
+     *   agt.enqueue(a => {
+     *     a.set("x", 20);
+     *   });
+     * });
+     * ```
+     *
+     * Any additional parameters passed to the enqueued function will
      * be remembered and passed through when the function is executed.
      *
-     * The `queue` array is cleared at the very end of
-     * the environment's tick cycle.
-     * @param {Function} enqueuedRule
      * @deprecated since version 0.5.14
      * @since 0.0.5
      */
     enqueue(rule: Function, ...args: Array<any>): void;
     /**
      * From a RuleObj, execute a single rule (function or structured Rule).
-     * @param {RuleObj} ruleObj
+     * @hidden
      */
     executeRule(ruleObj: RuleObj): Data;
     /**
      * Execute all rules.
+     * @hidden
      */
     executeRules(): void;
     /**
      * Execute all enqueued rules.
+     * @hidden
      */
     executeEnqueuedRules(): void;
 }

package/dist/environments/Environment.d.ts

@@ -13,6 +13,7 @@ interface Helpers {
 }
 export interface TickOptions {
     activation?: "uniform" | "random";
+    activationCount?: number;
     count?: number;
     randomizeOrder?: boolean;
 }
@@ -23,33 +24,80 @@ interface MemoValue {
     time: number;
 }
 /**
- * An environment provides the space and time in which agents interact.
- * Environments, like agents, can store data in key-value pairs
- * that can be updated over time.
+ * An environment provides the space and time in which Agents interact.
+ * Environments are themselves Agents, and can store data in key-value
+ * pairs that can be manipulated just like Agent data.
  * @since 0.0.5
  */
 declare class Environment extends Agent {
-    /** @member {Agent[]} */
+    /** @hidden */
     agents: Array<Agent>;
+    /** @hidden */
     agentsById: Map<string, Agent>;
+    /** @hidden */
+    environment: Environment;
+    /** @hidden */
     cache: Map<string, MemoValue>;
+    /** @hidden */
     helpers: Helpers;
-    /** @member {AbstractRenderer[]} */
+    /** @hidden */
+    id: string;
+    /**
+     * An array of the renderers associated with this `Environment`.
+     * An `Environment` can have multiple renderers, usually one to render
+     * the {@linkcode Agent}s spatially and others for data visualization,
+     * such as a {@linkcode LineChartRenderer}, {@linkcode Histogram}, etc.
+     */
     renderers: AbstractRenderer[];
+    /** @hidden */
     opts: EnvironmentOptions;
     width: number;
     height: number;
-    /** @since 0.1.4 */
+    /**
+     * This property will always equal the number of tick cycles that
+     * have passed since the `Environment` was created. If you call
+     * {@linkcode tick} so that it goes forward multiple time steps, it will
+     * increase the `time` by that value (not by just `1`, even though
+     * you only called `tick` once).
+     *
+     * ```js
+     * const environment = new Environment();
+     * environment.time; // returns 0
+     *
+     * environment.tick();
+     * environment.time; // returns 1
+     *
+     * environment.tick(3);
+     * environment.time; // returns 4
+     * ```
+     *
+     * @since 0.1.4
+     * */
     time: number;
+    /**
+     * Although `Environment`s inherit {@linkcode Agent} methods
+     * like {@linkcode Agent.set}, {@linkcode Agent.get}, etc. they have
+     * a different `constructor` signature.
+     *
+     * Pass in predefined `Environment` options for:
+     * - `torus` &mdash; Whether the `Environment` should wrap around in 2d space (with `Agent`s that move off the right reappearing on the left, off the top reappearing on the bottom, etc.)
+     * - `width` &mdash; The width of the `Environment` (used when `torus = true`)
+     * - `height` &mdash; The height of the `Environment` (used when `torus = true`)
+     * @override
+     */
     constructor(opts?: EnvironmentOptions);
     /**
-     * Add an agent to the environment. Automatically sets the
-     * agent's environment to be this environment.
-     * @param {Agent} agent
-     * @param {boolean} rebalance - Whether to rebalance if there is a KDTree (defaults to true)
+     * Add an {@linkcode Agent} to this `Environment`. Once this is called,
+     * the `Agent`'s {@link Agent.environment | `environment`} property
+     * will automatically be set to this `Environment`.
+     * @param rebalance - Whether to rebalance if there is a `KDTree` (defaults to true)
      * @since 0.0.5
      */
     addAgent(agent: Agent, rebalance?: boolean): void;
+    /** @hidden */
+    addRule: null;
+    /** @hidden */
+    enqueue: null;
     /**
      * Remove an agent from the environment.
      * @param {Agent} agent
@@ -77,57 +125,105 @@ declare class Environment extends Agent {
      */
     getAgentById(id: string): Agent | null;
     /**
-     * Removes all agents from the environment.
+     * Remove all agents from the environment.
      * @since 0.1.3
      */
     clear(): void;
     /**
-     * From the parameter passed to .tick, get a structured TickOptions object.
-     * @param {number | TickOptions} opts
+     * From the parameter passed to {@linkcode Environment.tick}, get a structured TickOptions object.
+     * @hidden
      */
     _getTickOptions(opts?: number | TickOptions): TickOptions;
     /**
-     * Execute all agent rules.
-     * @param { boolean } randomizeOrder
+     * For all agents passed, execute agent rules
+     * @hidden
      */
-    _executeAgentRules(randomizeOrder: boolean): void;
+    _executeAgentRules(agents: Agent[]): void;
     /**
-     * Execute all enqueued agent rules.
-     * @param { boolean } randomizeOrder
+     * For all agents passed, execute enqueued agent rules
+     * @hidden
      */
-    _executeEnqueuedAgentRules(randomizeOrder: boolean): void;
-    /**
-     * Moves the environment forward in time,
-     * executing all agent's rules sequentially, followed by
-     * any enqueued rules (which are removed with every tick).
-     * Can take either a number or a configuration object as a parameter.
-     * If a number, the environment will tick forward that many times.
-     * @param {number | TickOptions} opts
+    _executeEnqueuedAgentRules(agents: Agent[]): void;
+    /**
+     * Runs the `Environment`s tick cycle. Depending on the parameters, one,
+     * some, or all of the {@linkcode Agent}s in the `Environment`
+     * might be activated, and all renderers associated with the
+     * `Environment` will update. After the tick cycle finishes, any rules that were enqueued will be run and the `Environment`'s {@linkcode time} property will have incremented.
+     *
+     * ```js
+     * environment.tick(); // ticks once
+     *
+     * // To run multiple tick cycles, you can pass a number
+     * environment.tick(5); // ticks 5 times
+     * ```
+     *
+     * Passing a configuration object (instead of a number) allows
+     * you to have finer control over the tick cycle. The object can
+     * have the following keys:
+     * - `activation`: Either `"uniform"` or `"random"` (defaults to `"uniform"`).
+     *   - `activation = "uniform"` &mdash; All `Agent`s in the `Environment` are activated with every tick cycle.
+     *   - `activation = "random"` &mdash; One or more `Agent`s are randomly selected to be activated every tick cycle (see `activationCount` below).
+     * - `activationCount`: For `"random"` activation, this many `Agent`s will be activated with each tick cycle. Defaults to `1`. If `activationCount` is greater than the number of `Agent`s in the `Environment`, then all the `Agent`s will be activated exactly once in random order.
+     * - `count`: The number of tick cycles to run.
+     * - `randomizeOrder`: When `activation = "uniform"`, if `randomizeOrder = true`, `Agent`s will be activated in random order, otherwise in the order they were added to the `Environment`. **This currently defaults to `false` but will default to `true` in v0.6.0.**
+     *
+     * ```js
+     * // Ticks three times, activating 10 random agents with each tick cycle.
+     * environment.tick({
+     *   activation: "random",
+     *   activationCount: 10,
+     *   count: 3
+     * });
+     * ```
+     *
      * @since 0.0.5
      */
     tick(opts?: number | TickOptions): void;
     /**
-     * Use a helper with this environment.
-     * @param {EnvironmentHelper} e
+     * Use a helper with this environment. A helper can be one of:
+     * - {@linkcode KDTree}
+     * - {@linkcode Network}
+     * - {@linkcode Terrain}
      * @since 0.1.3
      */
-    use(e: EnvironmentHelper): void;
+    use(helper: EnvironmentHelper): void;
     /**
      * Get an array of data associated with agents in the environment by key.
-     * Equivalent to calling `environment.getAgents().map(agent => agent.get(key));`
-     * Defaults to calculating and storing the result within the same environment tick.
-     * If the 2nd parameter is set to `false`, will recalculate and return the result every time.
-     * @param {string} key - The key for which to retrieve data.
-     * @param {boolean} useCache - Whether or not to cache the result (defaults to true).
-     * @return {any[]} Array of data associated with `agent.get(key)` across all agents.
+     * Calling `environment.stat('name')` is equivalent to calling
+     * `environment.getAgents().map(agent => agent.get('name'));`
+     *
+     * By default, calling this will calculate the result at most once
+     * per time cycle, and return the cached value on subsequent calls (until
+     * the next time cycle, when it will recalculate).
+     *
+     * @param key - The key for which to retrieve data.
+     * @param useCache - Whether or not to cache the result.
+     * @returns Array of data associated with `agent.get(key)` across all agents.
+     *
+     * ```js
+     * environment.addAgent(new Agent({ name: "Alice" }));
+     * environment.addAgent(new Agent({ name: "Bob" }));
+     * environment.addAgent(new Agent({ name: "Chaz" }));
+     *
+     * environment.stat('name'); // returns ['Alice', 'Bob', 'Chaz']
+     * ```
+     *
      * @since 0.3.14
      */
     stat(key: string, useCache?: boolean): any[];
     /**
      * Pass a function to cache and use the return value within the same environment tick.
-     * @param {Function} fn - The function to memoize.
-     * @return {any} The return value of the function that was passed.
+     * @param fn - The function to memoize.
+     * @return The return value of the function that was passed.
      * @since 0.3.14
+     *
+     * ```js
+     * // Within the same time cycle, this function will only be called once.
+     * // The cached value will be used on subsequent calls.
+     * const blueAgents = environment.memo(() => {
+     *   return environment.getAgents().filter(a => a.get('color') === 'blue');
+     * });
+     * ```
      */
     memo(fn: Function, key?: string): any;
 }

package/dist/environments/GridEnvironment.d.ts

@@ -3,11 +3,22 @@ import { Agent } from "../agents/Agent";
 import { Cell } from "../agents/Cell";
 import { Environment, TickOptions } from "./Environment";
 /**
- * @since 0.0.5
+ * A `GridEnvironment` is the **deprecated** version of a cellular automata.
+ * It's now recommended that you use a standard {@linkcode Environment} with a
+ * {@linkcode Terrain}. This class will be removed entirely in v0.6.0.
+ *
+ * In a `GridEnvironment` with an {@linkcode ASCIIRenderer}, {@linkcode Agent}s are rendered
+ * using their `"value"` data (a single character).
+ *
+ * @deprecated since 0.4.0
+ * @since 0.0.10
  */
 declare class GridEnvironment extends Environment {
     cells: Map<string, Cell>;
     _cellHashes: Array<string>;
+    /**
+     * Create a `GridEnvironment` with the given `width` and `height`.
+     */
     constructor(width?: number, height?: number);
     /**
      * Fill every cell of the grid with an agent
@@ -16,11 +27,12 @@ declare class GridEnvironment extends Environment {
      */
     fill(): void;
     /**
+     * @hidden
      * @since 0.1.0
      */
     normalize(x: number, y: number): Point;
     /**
-     * For GridEnvironments, `addAgent` takes `x` and `y` values
+     * For `GridEnvironment`s, `addAgent` takes `x` and `y` values
      * and automatically adds a Agent to that cell coordinate.
      * @param {number} x_
      * @param {number} y_
@@ -29,8 +41,8 @@ declare class GridEnvironment extends Environment {
      */
     addAgentAt(x_?: number, y_?: number, agent?: Agent): Agent;
     /**
-     * For GridEnvironments, `removeAgent` takes `x` and `y` values
-     * and removes the Agent (if there is one) at that cell coordinate.
+     * For GridEnvironments, `removeAgentAt` takes `x` and `y` values
+     * and removes the `Agent` (if there is one) at that cell coordinate.
      * @param {number} x_
      * @param {number} y_
      * @since 0.1.0
@@ -99,17 +111,19 @@ declare class GridEnvironment extends Environment {
     neighbors(agent: Agent, radius?: number, moore?: boolean): Agent[];
     /**
      * Execute all cell rules.
+     * @hidden
      * @param { boolean } randomizeOrder
      */
     _executeCellRules(randomizeOrder: boolean): void;
     /**
      * Execute all enqueued cell rules.
+     * @hidden
      * @param { boolean } randomizeOrder
      */
     _executeEnqueuedCellRules(randomizeOrder: boolean): void;
     /**
-     * Override/extend Environment.tick to include the
-     * GridEnvironment's cells.
+     * Override/extend {@linkcode Environment.tick} to include the
+     * `GridEnvironment`'s cells.
      * @override
      * @param {number} opts
      */