0.10.16Class Turtle instances represent the dynamic, behavioral element of modeling. Each turtle knows the patch it is on, and interacts with that and other patches, as well as other turtles. Turtles are also the end points of Links.
You do not call new Turtle(), instead class Turtles creates Turtle instances
via Turtles#create or Turtles#createOne
I.e. class Turtles is a factory for all of it's Turtle instances. So don't do this:
Ask this turtle to "die"
A property for the x-increment if the turtle were to take one step forward in its current heading.
A property for the y-increment if the turtle were to take one step forward in its current heading.
Turn turtle so at to be facing the given Turtle or Patch
Turn turtle so at to be facing the given x, y patch coordinate
Handle turtle x,y,z if turtle off-world. Uses the Turtle's atEdge property to determine how to manage the Turtle. Defaults to 'wrap', wrapping the x,y,z to the opposite edge.
atEdge can be:
Factory method: create num new turtles at this turtle's location.
(number
= 1)
The number of new turtles to create
(AgentSet
= this.agentSet)
The type of turtles to create,
defaults to my type
(Function
= turtle=>{})
A function to initialize the new
turtles, defaults to no-op
Array:
An Array of the new Turtles, generally ignored
due to the init function
Return this Turtle's heading
Sets this Turtle's heading
(any)
Returns an array of the Links that have this Turtle as one of the end points
Array:
An AgentList Array of my Links
Place the turtle at the given patch/turtle location
Return the patch this Turtle is on. Return null if Turtle off-world.
Set Turtles x, y position. If z given, override default z of 0.
Computes the difference between the my heading and the given heading, the smallest angle by which t could be rotated to produce heading.
(Angle)
The heading I wish to be roated to.
Angle:
A Turtle is an object living on the Patches world. Their coordinates are floats, unlike Patches with integer coordinates. They can morph between types of turtles (breeds) and storee information, both within themselves but also on Patches and Links.
The Turtles (plural) array, (AgentSet) is a collection of Turtle objects that the Turtles array creates and manages.
You do not create either individual Turtle objects, the Turtles array does. You also do not create the Turtles array, class Model does.
You use both, however, using the methods they both provide.
Extends AgentSet
(Model)
The model I belong to
((Turtle | Turtle3d))
The Turtle class
(string)
The name of this new Turtles instance
((null | Turtles)
= null)
Used to create a breed subclass
Return the closest turtle within radius distance of x,y. Return null if no turtles within radius. If I am a breed, return the closest fellow breed.
Turtle:
The closest Turtle
Create num Turtles, adding them to this Turtles array. The init function is called to initialize each new Turtle. Returns an array of the new Turtles
(any)
(Function
= turtle=>{})
A function to initialize new turtles.
(number)
Number of Turtles to create
Array:
The newly created Turtles
Return all the Turtles with a cone of me. The cone is coneAngle wide, centered on my heading. If I am a breed, return only fellow breeds.
(Turtle)
(number)
(any)
(boolean
= false)
Whether or not to return me as well
AgentList:
The turtles within the cone.
Return an array of Turtles within the array of patchs. If I am a breed, return only the Turtles of my breed.
AgentList:
The turtles withn the Patches array.
Return an array of Turtles within the dx,dy patchRect centered on turtle. If I am a breed, return only the Turtles of my breed.
(Turtle)
The Turtle at the patchRect center.
(number)
The integer x radius of the patchRect
(number
= dx)
The integer y radius of the patchRect
(boolean
= false)
Whether or not to return me as well
AgentList:
The turtles within the patchRect
Return an array of Turtles within the dx,dy patchRect centered on x,y. If I am a breed, return only the Turtles of my breed.
(number)
the patchRect center's integer x value
(number)
the patchRect center's integer y value
(number)
The integer x radius of the patchRect
(number
= dx)
The integer y radius of the patchRect
(boolean
= false)
Whether or not to return me as well
AgentList:
The turtles within the patchRect
Return all the Turtles within radius of me. If I am a breed, return only fellow breeds.
AgentList:
The turtles within radius of me
Position the Turtles in this breed in an equally spaced circle of the given center and radius. The turtle headings will be away from the center.
Class Link instances form a link between two Turtles, forming a graph with the Turtles being the nodes, and the Links the edges.
TODO: Document Link properties and methods.
Links are a collection of all the Link objects between turtles.
Extends AgentSet
Class Patch instances represent a square on the Patches grid. They hold variables that are in the patches the turtles live on. The set of all patches is the world on which the turtles live and the model runs.
You do not use new Patch, rather Class Model creates the patches
for you, using the World data passed to the Model.
You never do this:
Returns an Array of the particular breed on this patch.
(String)
AgentArray:
Return an array of this patch's 8 Moore neighbors.
AgentArray:
Return an array of this patch's 4 Von Neumann neighbors (north, south, east, west).
AgentArray:
Return an Array of the turtles on this patch.
AgentArray:
Patches are the world other AgentSets live on. They define a coord system from the Model's World values: minX, maxX, minY, maxY, (minZ, maxZ) (z optional) Patches form a grid of Patch objects which can store world data (elevation, fires, ant pheromones, buildings, roads, gis spatial data, water and so on)
Created by class Model. Used by modeler in their Model subclass
Extends AgentSet
(Model)
An instance of class Model
(Patch)
The Patch class managed by Patches
(string)
Name of the AgentSet
Assign a DataSet's values into the patches as the given property name
Return the 8 patch "Moore" neighbors of the given patch. Will be less than 8 on the edge of the patches
(Patch)
a Patch instance
AgentList:
An array of the neighboring patches
Return the 4 patch "Van Neumann" neighbors of the given patch. Will be less than 4 on the edge of the patches
(Patch)
a Patch instance
AgentList:
An array of the neighboring patches
A model's Patches, Turtles, Links, are all subclasses of AgentSet.
AgentSets are AgentArrays that are factories for their own Agents.
That means you do not call new Turtle(), rather Turtles
will create the Turtle instances, adding them to itself.
Finally, a Breed is simply a subarray of Patches, Turtles, Links. Patches could have a Streets breed, Turtles could have Cops and Robbers breeds, and Links Spokes and Rim breeds
AgentSets are not created directly by modelers. Instead, class Model creates them along with their Breeds. You can easily skip this initially, instead simply understand AgentSets are the basis for Patches, Turtles, Links & Breeds
Extends AgentArray
(Model)
Instance of Class Model to which I belong
(String)
Name of this AgentSet. Ex: Patches
Magic to return AgentArrays rather than AgentSets Symbol.species
Remove all Agents from this AgentSet using agent.die() for each agent.
Add common variables to an Agent being added to this AgentSet.
Each Agent has it's AgentSet and the Model instance. It also has an id, set by the AgentSet's global ID.
The Agent also has three methods added: setBreed, getBreed, isBreed.
Move an agent from its AgentSet/breed to be in this AgentSet/breed
(Agent)
An agent, a member of another AgentSet
Agent:
The updated agent
Return breeds in a subset of an AgentSet
Ex: patches.inRect(5).withBreed(houses)
(AgentSet)
A breed AgentSet
AgentArray:
Subclass of Array with convenience methods used by NetLogo. Tipically the items in the array are Objects but can be any type.
Extends Array
(any)
Zero or more items in Array
Convert an existing Array to an AgentArray "in place". Use array.slice() if a new array is wanted
(Array)
Array to convert to AgentArray
AgentArray:
array converted to AgentArray
Magic to return AgentArrays rather than AgentList or other AgentArray subclasses when using AA methods Symbol.species
Return at index. Returns undefined if empty. Wrap the index to be within the array.
(any)
any:
aa.atIndex(aa.length)
//=> { x: 0, y: 0 }
Create copy of this AgentArray
any:
AgentArray
Return first item in this array. Returns undefined if empty.
any:
aa.first()
//=> { x: 0, y: 0 }
Return last item in this array. Returns undefined if empty.
any:
aa.last()
//=> { x: 1, y: 0 }
Return array of property values from this array's objects. Array type is specified, defaults to AgentArray
Array:
Array of given type
aa.props('x')
//=> [0, 0, 1]
aa.props('y')
//=> [0, 1, 0]
Return this AgentArray sorted by the reporter in ascending/descending order. If reporter is a string, convert to a fcn returning that property.
AgentArray:
See World and [MyClass's foo property]World#bboxTransform. Convert this AgentArray to Array in-place
Array:
This AgentArray converted to Array
Creates an Object of Arrays, one Array per each property in obj. Obj is key, arrayType pairs: x: Float32Array This is advanced, used for web workers, very large data sets, and remote communication
(Object)
Object of prop, array type pairs
Object:
aa.typedSample({x: Uint8Array, y: Uint8Array})
//=> {x: new Uint8Array([0, 0, 1]), y: new Uint8Array([0, 1, 0])}
Return new AgentArray of the unique values of this array
AgentArray:
Use: turtles.with(t => t.foo > 20).ask(t => t.bar = true)
(Function)
fcn(agent, [index], [array])
AgentArray:
Class Model2D is the primary interface for modelers, integrating the Patches/Patch Turtles/Turtle and Links/Link AgentSets .. i.e.:
Note: Our default class Model differes only in that
Convention: Three abstract methods are provided by the modeler
Resets model to initial state w/ new Patches, Turtles, Links. The worldOptions will default to initial values but can be changed by modeler. Setup() often called after reset() to re-initialize the model.
An abstract method for initializing the model
Note: can be used with reset(). This will reinitialize the Patches, Turtles, Links for re-running the model
An abstract method to perform one-time initialization.
An abstract method to run the model one step.
Increment the tick cound. Not needed if autoTick true, the default
Model3D uses Model2D with one change:
Model3D is our default Model.
Extends Model2D
This is our default Model which simply re-exports Model3D Thus when using:
import Model from './Model.js'
..you will be using ./Model3D
Class World defines the coordinate system for the model. It has transforms for multiple coordinate systems.
The world is defined by an object with 6 properties:
WorldOptions = {
minX: integer,
maxX: integer,
minY: integer,
maxY: integer,
minZ: integer,
maxZ: integer,
}
Return an instance of a bounding box 2D transform. It linearly interpolates between the given minX, minY, maxX, maxY, and the world's values of the same properties.
The parameters are in the popular geojson order: west, south, east, north
Useful for Canvas top-left transforms and geojson transforms.
(number)
min bounding box x value
(number)
min bounding box y value
(number)
max bounding box x value
(number)
max bounding box y value
BBoxTransform:
Instance of the BBoxTransform
Basic 2D view.
TODO: Document this class
Extends TwoView
(any)
(any
= {})
(any
= {})
Basic 3D view.
TODO: Document this class
Extends ThreeView
(any)
(any
= {})
(any
= {})
A general color module, supporting css string colors, canvas2d pixel colors, webgl and canvas2d Uint8ClampedArray r,g,b,a arrays.
CSS colors in HTML are strings, see Mozillas Color Reference, taking one of 7 forms:
See this wikipedia article on differences between HSL and HSB/HSV.
Convert 4 ints, h,s,l,a, h in [0-360], s,l in [0-100]% a in [0-255] to a css color string.
NOTE: h=0 and h=360 are the same, use h in 0-359 for unique colors.
(any)
(any)
(any)
(any
= 255)
Convert 4 r,g,b,a ints in [0-255] ("a" defaulted to 255) to a css color string.
(any)
(any)
(any)
(any
= 255)
A NetLogo-like mouse handler.
TODO: Example usage.
(any)
(any)
(any
= (evt,mouse)=>{})
A DataSet is an object with width/height and an array of numbers of length = width * height.
The array can be a TypedArray or a JavaScript Array.
(number)
The integer width of the array
(number)
The integer height of the array
(array)
The array of numbers of length width * height
An assortment of helper functions. To use: import * as util from src/utils.js.
Clamp a float to be between [min, max).
number:
a float between min/max
Create a blank 2D canvas of a given width/height.
(number)
The canvas height in pixels
(number)
The canvas width in pixels
(boolean
= offscreenOK())
If true, return "Offscreen" canvas
Canvas:
The resulting Canvas object
As above, but returing the 2D context object instead of the canvas. Note ctx.canvas is the canvas for the ctx, and can be use as an image.
(number)
The canvas height in pixels
(number)
The canvas width in pixels
(boolean
= offscreenOK())
If true, return "Offscreen" canvas
Context2D:
The resulting Canvas's 2D context
Convert from degrees to radians
(number)
a value in degrees: in [0, 360)
number:
the value as radians: in [0, 2PI)
Convert from heading to radians
(number)
a value in degrees: in [0, 360)
number:
a value in radians: in [0, 2PI)
Return a Promise for getting an image.
use: imagePromise('./path/to/img').then(img => imageFcn(img)) or: await imagePromise('./path/to/img')
(URL)
string for path to image
Promise:
A promise resolving to the image
A true modulus function, differing from the % remainder operation.
(number)
The value to calculate the modulus of
(number)
The number relative to which the modulus is calculated.
number:
The value of v mod n
Return random item from an array
(any)
(Array)
array to choose from
any:
The chosen item
Round a number to be of a given decimal precision. If the number is an array, round each item in the array
(number
= 4)
The number of decimal digits
number:
The resulting number
Convert from radians to degrees
(number)
a value in radians: in [0, 2PI)
number:
the value as degrees: in [0, 360)
Convert from radians to heading
Heading is 0-up (y-axis), clockwise angle measured in degrees. Radians is euclidean: 0-right (x-axis), counterclockwise in radians
(number)
a value in radians: in [0, 2PI)
number:
a value in degrees: in [0, 360)
Return a random float centered around r, in [-r/2, r/2)
(number)
The center float
number:
a float in [-r/2, r/2)
Returns a random float in [0, max)
(number)
The max float to return
number:
a float in [0, max)
Returns a random float in [min, max)
number:
a float in [min, max)
Returns an int in [0, max), equal or grater than 0, less than max
(number)
The max integer to return
number:
an integer in [0, max)
Returns an int in [min, max), equal or grater than min, less than max
number:
an integer in [min, max)
Install a seeded random generator as Math.random Uses an optimized version of the Park-Miller PRNG.
Math.random will return a sequence of "random" numbers in a known sequence. Useful for testing to see if the same results occur in multiple runs of a model with the same parameters.
(number
= 123456)
Repeats the function f(i, a) i in 0, n-1. a is an optional array, default a new empty Array returns a, only needed if f() places data in a
(number)
An integer number of times to run f()
(function)
The function called.
(Array
= [])
An optional array for use by f()
Array:
The result of calling f() n times
Return an object with samples of the models components. Useful for testing Models without needing a View, just data.
(Model)
A model to sample
Object:
An object with all the samples
Fill this context with the given image, resizing it to img size if needed.
(Context2D)
a canvas 2D context
(Image)
the Image to install in this ctx
Subtract two headings, returning the smaller difference.
Computes the difference between the given headings, that is, the number of degrees in the smallest angle by which heading2 could be rotated to produce heading1 See NetLogo's subtract-headings for explanation
number:
The smallest andle from head0 to head1
Use timeoutPromise for an animation loop. Calls the fcn each step Stops after steps calls, negative means run forever
Return promise for pause of ms. Use: await timeoutPromise(ms)
(number
= 1000)
Number of ms to pause
Promise:
A promise to wait this number of ms
Merge a module's obj key/val pairs into to the global/window namespace. Primary use is to make console logging easier when debugging modules.
(Object)
Object who's key/val pairs will be installed in window.
Class Turtle3D subclasses Turtles, adding 3D methods using Three.js's Object3D module. See NetLogo who's 3D semantics we follow.
Just as with Turtle, you do not call new Turtle3D(),
instead class Turtles creates Turtle3D instances via
Model modifying the Turtles/Turtle3D initialization.
3D is the default. To revert to 2D, see Model2D
Again, class Turtles is a factory for all of it's Turtle3D instances. So don't do this:
Extends Turtle2D
Return Promise for ajax/xhr data.
type: 'arraybuffer', 'blob', 'document', 'json', 'text'. method: 'GET', 'POST' use: xhrPromise('./path/to/data').then(data => dataFcn(data))
(UTL)
A URL path to the data to be retrieved
(string
= 'text')
The type of the data
(string
= 'GET')
The retrieval method
any:
The resulting data of the given type