0.10.12Class 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. They are also the end points of Links.
You do not call new Turtle(), instead class Turtles
creates it's Turtle instances. I.e. class Turtles is a factory
for all of it's Turtle instances. So don't do this:
Ask this turtle to "die"
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
Returns an array of the Links that have this Turtle as one of the end points
Array:
An AgentList Array of my Links
Return the patch this Turtle is on. Return null if Turtle off-world.
Return this Turtle's heading
Sets this Turtle's heading
(any)
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:
Set Turtles x, y position. If z given, override default z of 0.
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:
Place the turtle at the given patch/turtle location
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
Return distance from me to the Patch or Turtle
2.5D: use z too if both agent.z and this.z exist
(any)
any:
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.
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
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
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.
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.
TODO: Document Patch properties and methods.
A list of this patch's 8 Moore neighbors.
A list of this patch's 4 Von Neumann neighbors (north, south, east, west).
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
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
Assign a DataSet's values into the patches as the given property name
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
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.
Return breeds in a subset of an AgentSet
Ex: patches.inRect(5).withBreed(houses)
(AgentSet)
A breed AgentSet
AgentArray:
Remove all Agents from this AgentSet using agent.die() for each agent.
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
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
Magic to return AgentArrays rather than AgentList or other AgentArray subclasses when using AA methods Symbol.species
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
See World and [MyClass's foo property]World#bboxTransform. Convert this AgentArray to Array in-place
Array:
This AgentArray converted to Array
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 at index. Returns undefined if empty. Wrap the index to be within the array.
(any)
any:
aa.atIndex(aa.length)
//=> { x: 0, 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]
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:
Create copy of this AgentArray
any:
AgentArray
Return this AgentArray sorted by the reporter in ascending/descending order. If reporter is a string, convert to a fcn returning that property.
AgentArray:
Class Model is the primary interface for modelers, integrating the Patches/Patch Turtles/Turtle and Links/Link AgentSets .. i.e.:
Convention: Three abstract methods are provided by the modeler
(boolean
= true)
Automatically advancee tick count each step if true
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.
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.
Increment the tick cound. Not needed if autoTick true
Increment the tick cound. Not needed if autoTick true
An abstract method to perform one-time initialization.
An abstract method to perform one-time initialization.
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 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 run the model one step.
An abstract method to run the model one step.
Set the Geometry of this Model
(string)
One of 'radians', 'degrees', 'heading'
Class Model is the primary interface for modelers, integrating the Patches/Patch Turtles/Turtle and Links/Link AgentSets .. i.e.:
Convention: Three abstract methods are provided by the modeler
(boolean
= true)
Automatically advancee tick count each step if true
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.
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.
Increment the tick cound. Not needed if autoTick true
Increment the tick cound. Not needed if autoTick true
An abstract method to perform one-time initialization.
An abstract method to perform one-time initialization.
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 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 run the model one step.
An abstract method to run the model one step.
Set the Geometry of this Model
(string)
One of 'radians', 'degrees', 'heading'
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 r,g,b,a ints in [0-255] ("a" defaulted to 255) to a css color string.
(any)
(any)
(any)
(any
= 255)
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)
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.
Return a Promise for getting an image.
use: imagePromise('./path/to/img').then(img => imageFcn(img))
(URL)
string for path to image
Promise:
A promise resolving to the image
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
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
Use timeoutPromise for an animation loop. Calls the fcn each step Stops after steps calls, negative means run forever
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
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
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.
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)
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)
Return a random float centered around r, in [-r/2, r/2)
(number)
The center float
number:
a float in [-r/2, r/2)
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)
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
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
Clamp a float to be between [min, max).
number:
a float between min/max
Convert from degrees to radians
(number)
a value in degrees: in [0, 360)
number:
the value as radians: in [0, 2PI)
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)
Convert from heading to radians
(number)
a value in degrees: in [0, 360)
number:
a value in radians: in [0, 2PI)
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
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
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 random item from an array
(any)
(Array)
array to choose from
any:
The chosen item