Mathematical Constants

e = 2.718281828459045
pi = 3.141592653589793

Boolean Constants

false
true

Color Constants

black = 0
gray = 5
white = 9.9
red = 15
orange = 25
brown = 35
yellow = 45
green = 55
lime = 65
turquoise = 75
cyan = 85
sky = 95
blue = 105
violet = 115
magenta = 125
pink = 135

See the Colors section of the Programming Guide for more details.

abs

abs number

Reports the absolute value of number.

show abs -7
=> 7
show abs 5
=> 5

acos

acos number

Reports the arc cosine (inverse cosine) of the given number. The input must be in the range -1 to 1. The result is in degrees, and lies in the range 0 to 180.

all?

all? agentset [reporter]

Reports true if all of the agents in the agentset report true for the given reporter. Otherwise reports false as soon as a counterexample is found.

The reporter must report a boolean value for every agent tested (either true or false), otherwise an error occurs.

if all? turtles [color = red]
  [ show "every turtle is red!" ]

See also any?.

and

condition1 and condition2

Reports true if both condition1 and condition2 are true.

Note that if condition1 is false, then condition2 will not be run (since it can't affect the result).

if (pxcor > 0) and (pycor > 0)
  [ set pcolor blue ]  ;; the upper-right quadrant of
                       ;; patches turn blue

any?

any? agentset

Reports true if the given agentset is non-empty, false otherwise.

Equivalent to "count agentset > 0", but more efficient (and arguably more readable).

if any? turtles with [color = red]
  [ show "at least one turtle is red!" ]

Note: nobody is not an agentset. You only get nobody back in situations where you were expecting a single agent, not a whole agentset. If any? gets nobody as input, an error results.

See also all, nobody.

approximate-hsb

approximate-hsb hue saturation brightness

Reports a number in the range 0 to 140, not including 140 itself, that represents the given color, specified in the HSB spectrum, in NetLogo's color space.

All three values should be in the range 0 to 255.

The color reported may be only an approximation, since the NetLogo color space does not include all possible colors. (It contains only certain discrete hues, and for each hue, either saturation or brightness may vary, but not both -- at least one of the two is always 255.)

show approximate-hsb 0 0 0
=> 0  ;; (black)
show approximate-hsb 127.5 255 255
=> 85.2 ;; (cyan)

See also extract-hsb, approximate-rgb, extract-rgb.

approximate-rgb

approximate-rgb red green blue

Reports a number in the range 0 to 140, not including 140 itself, that represents the given color, specified in the RGB spectrum, in NetLogo's color space.

All three inputs should be in the range 0 to 255.

The color reported may be only an approximation, since the NetLogo color space does not include all possible colors. (See approximate-hsb for a description of what parts of the HSB color space NetLogo colors cover; this is difficult to characterize in RGB terms.)

show approximate-rgb 0 0 0
=> 0  ;; black
show approximate-rgb 0 255 255
=> 85.2 ;; cyan

See also extract-rgb, approximate-hsb, and extract-hsb.

Arithmetic Operators (+, *, -, /, ^, <, >, =, !=, <=, >=)

All of these operators take two inputs, and all act as "infix operators" (going between the two inputs, as in standard mathematical use). NetLogo correctly supports order of operations for infix operators.

The operators work as follows: + is addition, * is multiplication, - is subtraction, / is division, ^ is exponentiation, < is less than, > is greater than, = is equal to, != is not equal to, <= is less than or equal, >= is greater than or equal.

Note that the subtraction operator (-) always takes two inputs unless you put parentheses around it, in which case it can take one input. For example, to take the negative of x, write (- x), with the parentheses.

All of the comparison operators also work on strings.

All of the comparison operators work on agents. Turtles are compared by who number. Patches are compared top to bottom left to right, so patch 0 10 is less than patch 0 9 and patch 9 0 is less than patch 10 0. Links are ordered by end points and in case of a tie by breed. So link 0 9 is before link 1 10 as the end1 is smaller, and link 0 8 is less than link 0 9. If there are multiple breeds of links unbreeded links will come before breeded links of the same end points and breeded links will be sorted in the order they are declared in the Procedures tab.

Agentsets can be tested for equality or inequality. Two agentsets are equal if they are the same type (turtle or patch) and contain the same agents.

If you are not sure how NetLogo will interpret your code, you should add parentheses.

show 5 * 6 + 6 / 3
=> 32
show 5 * (6 + 6) / 3
=> 20

asin

asin number

Reports the arc sine (inverse sine) of the given number. The input must be in the range -1 to 1. The result is in degrees, and lies in the range -90 to 90.

ask

ask agentset [commands]
ask agent [commands]

The specified agent or agentset runs the given commands.

ask turtles [ fd 1 ]
  ;; all turtles move forward one step
ask patches [ set pcolor red ]
  ;; all patches turn red
ask turtle 4 [ rt 90 ]
  ;; only the turtle with id 4 turns right

Note: only the observer can ask all turtles or all patches. This prevents you from inadvertently having all turtles ask all turtles or all patches ask all patches, which is a common mistake to make if you're not careful about which agents will run the code you are writing.

Note: Only the agents that are in the agentset at the time the ask begins run the commands.

ask-concurrent

ask-concurrent agentset [commands]

The agents in the given agentset run the given commands, using a turn-taking mechanism to produce simulated concurrency. See the Ask-Concurrent section of the Programming Guide for details on how this works.

Note: Only the agents that are in the agentset at the time the ask begins run the commands.

See also without-interruption.

at-points

agentset at-points [[x1 y1] [x2 y2] ...]

Reports a subset of the given agentset that includes only the agents on the patches the given distances away from the calling agent. The distances are specified as a list of two-item lists, where the two items are the x and y offsets.

If the caller is the observer, then the points are measured relative to the origin, in other words, the points are taken as absolute patch coordinates.

If the caller is a turtle, the points are measured relative to the turtle's exact location, and not from the center of the patch under the turtle.

ask turtles at-points [[2 4] [1 2] [10 15]]
  [ fd 1 ]  ;; only the turtles on the patches at the
            ;; distances (2,4), (1,2) and (10,15),
            ;; relative to the caller, move

atan

atan x y

Reports the arc tangent, in degrees (from 0 to 360), of x divided by y.

When y is 0: if x is positive, it reports 90; if x is negative, it reports 270; if x is zero, you get an error.

Note that this version of atan is designed to conform to the geometry of the NetLogo world, where a heading of 0 is straight up, 90 is to the right, and so on clockwise around the circle. (Normally in geometry an angle of 0 is right, 90 is up, and so on, counterclockwise around the circle, and atan would be defined accordingly.)

show atan 1 -1
=> 135
show atan -1 1
=> 315

autoplot?

autoplot?

Reports true if auto-plotting is on for the current plot, false otherwise.

auto-plot-off
auto-plot-on

auto-plot-off
auto-plot-on

This pair of commands is used to control the NetLogo feature of auto-plotting in the current plot. Auto-plotting will automatically update the x and y axes of the plot whenever the current pen exceeds these boundaries. It is useful when wanting to show all plotted values in the current plot, regardless of the current plot ranges.

back
bk

back number

The turtle moves backward by number steps. (If number is negative, the turtle moves forward.)

Turtles using this primitive can move a maximum of one unit per time increment. So bk 0.5 and bk 1 both take one unit of time, but bk 3 takes three.

If the turtle cannot move backward number steps because it is not permitted by the current topology the turtle will complete as many steps of 1 as it can and stop.

See also forward, jump, can-move?.

base-colors

base-colors

Reports a list of the 14 basic NetLogo hues.

print base-colors
=> [5 15 25 35 45 55 65 75 85 95 105 115 125 135]
ask turtles [ set color one-of base-colors ]
;; each turtle turns a random base color
ask turtles [ set color one-of remove gray base-colors ]
;; each turtle turns a random base color except for gray

beep

beep

Emits a beep. Note that the beep sounds immediately, so several beep commands in close succession may produce only one audible sound.

Example:

beep                       ;; emits one beep
repeat 3 [ beep ]          ;; emits 3 beeps at once,
                           ;; so you only hear one sound
repeat 3 [ beep wait 0.1 ] ;; produces 3 beeps in succession, 
                           ;; separated by 1/10th of a second

both-ends

both-ends

Reports the agentset of the 2 nodes connected by this link.

crt 2
ask turtle 0 [ create-link-with turtle 1 ]
ask link 0 1 [
  ask both-ends [ set color red ] ;; turtles 0 and 1 both turn red
]

breed

breed

This is a built-in turtle and link variable. It holds the agentset of all turtles or links of the same breed as this turtle or link. (For turtles or links that do not have any particular breed, this is the turtles agentset of all turtles or the links agentset of all links respectively.) You can set this variable to change a turtle or link's breed.

See also breed, directed-link-breed, undirected-link-breed

Example:

breed [cats cat]
breed [dogs dog]
;; turtle code:
if breed = cats [ show "meow!" ]
set breed dogs
show "woof!"

directed-link-breed [ roads road ]
;; link code
if breed = roads [ set color gray ]

breed

breed [<breeds> <breed>]

This keyword, like the globals, turtles-own, and patches-own keywords, can only be used at the beginning of the Procedures tab, before any procedure definitions. It defines a breed. The first input defines the name of the agentset associated with the breed. The second input defines the name of a single member of the breed.

Any turtle of the given breed:

• is part of the agentset named by the breed name
• has its breed built-in variable set to that agentset

Most often, the agentset is used in conjunction with ask to give commands to only the turtles of a particular breed.

breed [mice mouse]
breed [frogs frog]
to setup
  clear-all
  create-mice 50
  ask mice [ set color white ]
  create-frogs 50
  ask frogs [ set color green ]
  show [breed] of one-of mice    ;; prints mice
  show [breed] of one-of frogs   ;; prints frogs
end

show mouse 1
;; prints (mouse 1)
show frog 51
;; prints (frog 51)
show turtle 51
;; prints (frog 51)

See also globals, patches-own, turtles-own, <breeds>-own, create-<breeds>, <breeds>-at, <breeds>-here.

but-first
bf
but-last
bl

but-first list
but-first string
but-last list
but-last string

When used on a list, but-first reports all of the list items of list except the first, and but-last reports all of the list items of list except the last.

On strings, but-first and but-last report a shorter string omitting the first or last character of the original string.

;; mylist is [2 4 6 5 8 12]
set mylist but-first mylist
;; mylist is now [4 6 5 8 12]
set mylist but-last mylist
;; mylist is now [4 6 5 8]
show but-first "string"
;; prints "tring"
show but-last "string"
;; prints "strin"

can-move?

can-move? distance

Reports true if the calling turtle can move distance in the direction it is facing without violating the topology; reports false otherwise.

It is equivalent to:

patch-ahead distance != nobody

carefully

carefully [ commands1 ] [ commands2 ]

Runs commands1. If a runtime error occurs inside commands1, NetLogo won't stop and alert the user that an error occurred. It will suppress the error and run commands2 instead.

The error-message reporter can be used in commands2 to find out what error was suppressed in commands1. See error-message.

Note: both sets of commands run without interruption (as with the without-interruption command).

carefully [ show 1 / 1 ] [ print error-message ]
=> 1
carefully [ show 1 / 0 ] [ print error-message ]
=> division by zero

ceiling

ceiling number

Reports the smallest integer greater than or equal to number.

show ceiling 4.5
=> 5
show ceiling -4.5
=> -4

clear-all
ca

clear-all

Resets all global variables to zero, and calls reset-ticks, clear-turtles, clear-patches, clear-drawing, clear-all-plots, and clear-output.

clear-all-plots

clear-all-plots

Clears every plot in the model. See clear-plot for more information.

clear-drawing
cd

clear-drawing

Clears all lines and stamps drawn by turtles.

clear-links

clear-links

Kills all links.

See also die.

clear-output

clear-output

Clears all text from the model's output area, if it has one. Otherwise does nothing.

clear-patches
cp

clear-patches

Clears the patches by resetting all patch variables to their default initial values, including setting their color to black.

clear-plot

clear-plot

In the current plot only, resets all plot pens, deletes all temporary plot pens, resets the plot to its default values (for x range, y range, etc.), and resets all permanent plot pens to their default values. The default values for the plot and for the permanent plot pens are set in the plot Edit dialog, which is displayed when you edit the plot. If there are no plot pens after deleting all temporary pens, that is to say if there are no permanent plot pens, a default plot pen will be created with the following initial settings:

• Pen: down
• Color: black
• Mode: 0 (line mode)
• Name: "default"
• Interval: 1

See also clear-all-plots.

clear-turtles
ct

clear-turtles

Kills all turtles.

Also resets the who numbering, so the next turtle created will be turtle 0.

See also die.

color

color

This is a built-in turtle or link variable. It holds the color of the turtle or link. You can set this variable to make the turtle or link change color. Color can be represented either as a NetLogo color (a single number), or an RGB color (a list of 3 numbers). See details in the Colors section of the Programming Guide.

See also pcolor.

cos

cos number

Reports the cosine of the given angle. Assumes the angle is given in degrees.

show cos 180
=> -1

count

count agentset

Reports the number of agents in the given agentset.

show count turtles
;; prints the total number of turtles
show count patches with [pcolor = red]
;; prints the total number of red patches

create-ordered-turtles
cro
create-ordered-<breeds>

create-ordered-turtles number
create-ordered-turtles number [ commands ]
create-ordered<breeds> number
create-ordered<breeds> number [ commands ]

Creates number new turtles. New turtles start at position (0, 0), are created with the 14 primary colors, and have headings from 0 to 360, evenly spaced.

If the create-ordered-<breeds> form is used, the new turtles are created as members of the given breed.

If commands are supplied, the new turtles immediately run them commands. This is useful for giving the new turtles a different color, heading, or whatever. (The new turtles are created all at once then run one at a time, in random order.)

cro 100 [ fd 10 ]  ;; makes an evenly spaced circle

Note: While the commands are running, no other agents are allowed to run any code (as with the without-interruption command). This ensures that if ask-concurrent is being used, the new turtles cannot interact with any other agents until they are fully initialized.

create-<breed>-to
create-<breeds>-to
create-<breed>-from
create-<breeds>-from
create-<breed>-with
create-<breeds>-with
create-link-to
create-links-to
create-link-from
create-links-from
create-link-with
create-links-with

create-<breed>-to turtle
create-<breed>-to turtle [ commands ]
create-<breed>-from turtle
create-<breed>-from turtle [ commands ]
create-<breed>-with turtle
create-<breed>-with turtle [ commands ]
create-<breeds>-to turtleset
create-<breeds>-to turtleset [ commands ]
create-<breeds>-from turtleset
create-<breeds>-from turtleset [ commands ]
create-<breeds>-with turtleset
create-<breeds>-with turtleset [ commands ]
create-link-to turtle
create-link-to turtle [ commands ]
create-link-from turtle
create-link-from turtle [ commands ]
create-link-with turtle
create-link-with turtle [ commands ]
create-links-to turtleset
create-links-to turtleset [ commands ]
create-links-from turtleset
create-links-from turtleset [ commands ]
create-links-with turtleset
create-links-with turtleset [ commands ]

Used for creating breeded and unbreeded links between turtles.

create-link-with creates an undirected link between the caller and agent. create-link-to creates a directed link from the caller to agent. create-link-from creates a directed link from agent to the caller.

When the plural form of the breed name is used, an agentset is expected instead of an agent and links are created between the caller and all agents in the agentset.

The optional command block is the set of commands each newly formed link runs. (The links are created all at once then run one at a time, in random order.)

A node cannot be linked to itself. Also, you cannot have more than one undirected link of the same breed between the same two nodes, nor can you have more than one directed link of the same breed going in the same direction between two nodes.

If you try to create a link where one (of the same breed) already exists, nothing happens. If you try to create a link from a turtle to itself you get a runtime error.

to setup
   crt 5
   ;; turtle 1 creates links with all other turtles
   ;; the link between the turtle and itself is ignored
   ask turtle 0 [ create-links-with other turtles ]
   show count links ;; shows 4
   ;; this does nothing since the link already exists
   ask turtle 0 [ create-link-with turtle 1 ]
   show count links ;; shows 4 since the previous link already existed
   ask turtle 2 [ create-link-with turtle 1 ] 
   show count links ;; shows 5
end

directed-link-breed [red-links red-link]
undirected-link-breed [blue-links blue-link]

to setup
  crt 5
  ;; create links in both directions between turtle 0
  ;; and all other turtles
  ask turtle 0 [ create-red-links-to turtles ]
  ask turtle 0 [ create-red-links-from turtles ]
  show count links ;; shows 8
  ;; now create undirected links between turtle 0 and other turtles
  ask turtle 0 [ create-blue-links-with turtles ]
  show count links ;; shows 12
end

create-turtles
crt
create-<breeds>

create-turtles number
create-turtles number [ commands ]
create-<breeds> number
create-<breeds> number [ commands ]

Creates number new turtles . New turtles have random integer headings and the color is randomly selected from the 14 primary colors.

If the create-<breeds> form is used, the new turtles are created as members of the given breed.

If commands are supplied, the new turtles immediately run them commands. This is useful for giving the new turtles a different color, heading, or whatever. (The new turtles are created all at once then run one at a time, in random order.)

crt 100 [ fd 10 ]     ;; makes a randomly spaced circle

breed [canaries canary]
breed [snakes snake]
to setup
  clear-all
  create-canaries 50 [ set color yellow ]
  create-snakes 50 [ set color green ]
end

Note: While the commands are running, no other agents are allowed to run any code (as with the without-interruption command). This ensures that if ask-concurrent is being used, the new turtles cannot interact with any other agents until they are fully initialized.

See also hatch, sprout.

create-temporary-plot-pen

create-temporary-plot-pen string

A new temporary plot pen with the given name is created in the current plot and set to be the current pen.

Few models will want to use this primitive, because all temporary pens disappear when clear-plot or clear-all-plots are called. The normal way to make a pen is to make a permanent pen in the plot's Edit dialog.

If a temporary pen with that name already exists in the current plot, no new pen is created, and the existing pen is set to the the current pen. If a permanent pen with that name already exists in the current plot, you get a runtime error.

The new temporary plot pen has the following initial settings:

• Pen: down
• Color: black
• Mode: 0 (line mode)
• Interval: 1

See: clear-plot, clear-all-plots, and set-current-plot-pen.

date-and-time

date-and-time

Reports a string containing the current date and time. The format is shown below. All fields are fixed width, so they are always at the same locations in the string. The potential resolution of the clock is milliseconds. (Whether you get resolution that high in practice may vary from system to system, depending on the capabilities of the underlying Java Virtual Machine.)

show date-and-time
=> "01:19:36.685 PM 19-Sep-2002"

die

die

The turtle or link dies.

if xcor > 20 [ die ]
;; all turtles with xcor greater than 20 die
ask links with [color = blue] [ die ]
;; all blue links die

See also: clear-turtles clear-links

diffuse

diffuse patch-variable number

Tells each patch to give equal shares of (number * 100) percent of the value of patch-variable to its eight neighboring patches. number should be between 0 and 1. Regardless of topology the sum of patch-variable will be conserved across the world. (If a patch has fewer than eight neighbors, each neighbor still gets an eighth share; the patch keeps any leftover shares.)

Note that this is an observer command only, even though you might expect it to be a patch command. (The reason is that it acts on all the patches at once -- patch commands act on individual patches.)

diffuse chemical 0.5
;; each patch diffuses 50% of its variable
;; chemical to its neighboring 8 patches. Thus,
;; each patch gets 1/8 of 50% of the chemical
;; from each neighboring patch.)

diffuse4

diffuse4 patch-variable number

Like diffuse, but only diffuses to the four neighboring patches (to the north, south, east, and west), not to the diagonal neighbors.

diffuse4 chemical 0.5
;; each patch diffuses 50% of its variable
;; chemical to its neighboring 4 patches. Thus,
;; each patch gets 1/4 of 50% of the chemical
;; from each neighboring patch.)

directed-link-breed

directed-link-breed [<link-breeds> <link-breed>]

This keyword, like the globals and breeds keywords, can only be used at the beginning of the Procedures tab, before any procedure definitions. It defines a directed link breed. Links of a particular breed are always all directed or all undirected The first input defines the name of the agentset associated with the link breed. The second input defines the name of a single member of the breed. Directed links can be created using create-link(s)-to, and create-link(s)-from, but not create-link(s)-with

Any link of the given link breed:

• is part of the agentset named by the link breed name
• has its built-in variable breed set to that agentset
• is directed or undirected as declared by the keyword

Most often, the agentset is used in conjunction with ask to give commands to only the links of a particular breed.

directed-link-breed [streets street]
directed-link-breed [highways highway]
to setup
  clear-all
  crt 2
  ;; create a link from turtle 0 to turtle 1
  ask turtle 0 [ create-street-to turtle 1 ]
  ;; create a link from turtle 1 to turtle 0
  ask turtle 0 [ create-highway-from turtle 1 ]
end

ask turtle 0 [ show one-of in-links ]
;; prints (street 0 1)
ask turtle 0 [ show one-of out-links ]
;; prints (highway 1 0)

See also breed, undirected-link-breed

display

display

Causes the view to be updated immediately. (Exception: if the user is using the speed slider to fast-forward the model, then the update may be skipped.)

Also undoes the effect of the no-display command, so that if view updates were suspended by that command, they will resume.

no-display
ask turtles [ jump 10 set color blue set size 5 ]
display
;; turtles move, change color, and grow, with none of
;; their intermediate states visible to the user, only
;; their final state

Even if no-display was not used, "display" can still be useful, because ordinarily NetLogo is free to skip some view updates, so that fewer total updates take place, so that models run faster. This command lets you force a view update, so whatever changes have taken place in the world are visible to the user.

ask turtles [ set color red ]
display
ask turtles [ set color blue]
;; turtles turn red, then blue; use of "display" forces
;; red turtles to appear briefly

Note that display and no-display operate independently of the switch in the view control strip that freezes the view.

See also no-display.

distance

distance agent

Reports the distance from this agent to the given turtle or patch.

The distance to or a from a patch is measured from the center of the patch. Turtles and patches use the wrapped distance (around the edges of the world) if wrapping is allowed by the topology and the wrapped distance is shorter.

ask turtles [ show max-one-of turtles [distance myself] ]
;; each turtle prints the turtle farthest from itself

distancexy

distancexy xcor ycor

Reports the distance from this agent to the point (xcor, ycor).

The distance from a patch is measured from the center of the patch. Turtles and patches use the wrapped distance (around the edges of the world) if wrapping is allowed by the topology and the wrapped distance is shorter.

if (distancexy 0 0) > 10
  [ set color green ]
;; all turtles more than 10 units from
;; the center of the world turn green.

downhill
downhill4

downhill patch-variable
downhill4 patch-variable

Moves the turtle to the neighboring patch with the lowest value for patch-variable. If no neighboring patch has a smaller value than the current patch, the turtle stays put. If there are multiple patches with the same lowest value, the turtle picks one randomly. Non-numeric values are ignored.

downhill considers the eight neighboring patches; downhill4 only considers the four neighbors.

Equivalent to the following code (assumes variable values are numeric):

move-to patch-here  ;; go to patch center
let p min-one-of neighbors [patch-variable]  ;; or neighbors4
if [patch-variable] of p < patch-variable [
  face p
  move-to p
]

Note that the turtle always ends up on a patch center and has a heading that is a multiple of 45 (downhill) or 90 (downhill4).

See also uphill, uphill4.

dx
dy

dx
dy

Reports the x-increment or y-increment (the amount by which the turtle's xcor or ycor would change) if the turtle were to take one step forward in its current heading.

Note: dx is simply the sine of the turtle's heading, and dy is simply the cosine. (If this is the reverse of what you expected, it's because in NetLogo a heading of 0 is north and 90 is east, which is the reverse of how angles are usually defined in geometry.)

Note: In earlier versions of NetLogo, these primitives were used in many situations where the new patch-ahead primitive is now more appropriate.

empty?

empty? list
empty? string

Reports true if the given list or string is empty, false otherwise.

Note: the empty list is written []. The empty string is written "".

end

end

Used to conclude a procedure. See to and to-report.

end1

end1

This is a built-in link variable. It indicates the first endpoint (turtle) of a link. For directed links this will always be the source for undirected links it will always be the turtle with the lower who number. You cannot set end1.

crt 2
ask turtle 0 
[ create-link-to turtle 1 ]
ask links
[ show end1 ] ;; shows turtle 0

end2

end2

This is a built-in link variable. It indicates the second endpoint (turtle) of a link. For directed links this will always be the destination for undirected links it will always be the turtle with the higher who number. You cannot set end2.

crt 2
ask turtle 1 
[ create-link-with turtle 0 ]
ask links
[ show end2 ] ;; shows turtle 1

error-message

error-message

Reports a string describing the error that was suppressed by carefully.

This reporter can only be used in the second block of a carefully command.

See also carefully.

every

every number [ commands ]

Runs the given commands only if it's been more than number seconds since the last time this agent ran them in this context. Otherwise, the commands are skipped.

By itself, every doesn't make commands run over and over again. You need to use every inside a loop, or inside a forever button, if you want the commands run over and over again. every only limits how often the commands run.

Above, "in this context" means during the same ask (or button press or command typed in the Command Center). So it doesn't make sense to write ask turtles [ every 0.5 [ ... ] ], because when the ask finishes the turtles will all discard their timers for the "every". The correct usage is shown below.

every 0.5 [ ask turtles [ fd 1 ] ]
;; twice a second the turtles will move forward 1
every 2 [ set index index + 1 ]
;; every 2 seconds index is incremented

See also wait.

exp

exp number

Reports the value of e raised to the number power.

Note: This is the same as e ^ number.

export-view
export-interface
export-output
export-plot
export-all-plots
export-world

export-view filename
export-interface filename
export-output filename
export-plot plotname filename
export-all-plots filename
export-world filename

export-view writes the current contents of the current view to an external file given by the string filename. The file is saved in PNG (Portable Network Graphics) format, so it is recommended to supply a filename ending in ".png".

export-interface is similar, but for the whole interface tab.

export-output writes the contents of the model's output area to an external file given by the string filename. (If the model does not have a separate output area, the output portion of the Command Center is used.)

export-plot writes the x and y values of all points plotted by all the plot pens in the plot given by the string plotname to an external file given by the string filename. If a pen is in bar mode (mode 0) and the y value of the point plotted is greater than 0, the upper-left corner point of the bar will be exported. If the y value is less than 0, then the lower-left corner point of the bar will be exported.

export-all-plots writes every plot in the current model to an external file given by the string filename. Each plot is identical in format to the output of export-plot.

export-world writes the values of all variables, both built-in and user-defined, including all observer, turtle, and patch variables, the drawing, the contents of the output area if one exists, the contents of any plots and the state of the random number generator, to an external file given by the string filename. (The result file can be read back into NetLogo with the import-world primitive.) export-world does not save the state of open files.

export-plot, export-all-plots and export-world save files in in plain-text, "comma-separated values" (.csv) format. CSV files can be read by most popular spreadsheet and database programs as well as any text editor.

If the file already exists, it is overwritten.

If you wish to export to a file in a location other than the model's location, you should include the full path to the file you wish to export. (Use the forward-slash "/" as the folder separator.)

Note that the functionality of these primitives is also available directly from NetLogo's File menu.

export-world "fire.csv"
;; exports the state of the model to the file fire.csv
;; located in the NetLogo folder
export-plot "Temperature" "c:/My Documents/plot.csv"
;; exports the plot named
;; "Temperature" to the file plot.csv located in
;; the C:\My Documents folder
export-all-plots "c:/My Documents/plots.csv"
;; exports all plots to the file plots.csv
;; located in the C:\My Documents folder

extensions

extensions [name ...]

Allows the model to use primitives from the extensions with the given names. See the Extensions guide for more information.

extract-hsb

extract-hsb color

Reports a list of three values in the range 0 to 255 representing the hue, saturation and brightness, respectively, of the given NetLogo color in the range 0 to 140, not including 140 itself.

show extract-hsb red
=> [2.198 206.372 215]
show extract-hsb cyan
=> [127.5 145.714 196]

See also approximate-hsb, approximate-rgb, extract-rgb.

extract-rgb

extract-rgb color

Reports a list of three values in the range 0 to 255 representing the levels of red, green, and blue, respectively, of the given NetLogo color in the range 0 to 140, not including 140 itself.

show extract-rgb red
=> [215 50 41]
show extract-rgb cyan
=> [84 196 196]

See also approximate-rgb, approximate-hsb, extract-hsb.

face

face agent

Set the caller's heading towards agent.

If wrapping is allowed by the topology and the wrapped distance (around the edges of the world) is shorter, face will use the wrapped path.

If the caller and the agent are at the exact same position, the caller's heading won't change.

facexy

facexy number number

Set the caller's heading towards the point (x,y).

If wrapping is allowed by the topology and the wrapped distance (around the edges of the world) is shorter and wrapping is allowed, facexy will use the wrapped path.

If the caller is on the point (x,y), the caller's heading won't change.

file-at-end?

file-at-end?

Reports true when there are no more characters left to read in from the current file (that was opened previously with file-open). Otherwise, reports false.

file-open "my-file.txt"
print file-at-end?
=> false ;; Can still read in more characters
print file-read-line
=> This is the last line in file
print file-at-end
=> true ;; We reached the end of the file

See also file-open, file-close-all.

file-close

file-close

Closes a file that has been opened previously with file-open.

Note that this and file-close-all are the only ways to restart to the beginning of an opened file or to switch between file modes.

If no file is open, does nothing.

See also file-close-all, file-open.

file-close-all

file-close-all

Closes all files (if any) that have been opened previously with file-open.

See also file-close, file-open.

file-delete

file-delete string

Deletes the file specified as string

string must be an existing file with writable permission by the user. Also, the file cannot be open. Use the command file-close to close an opened file before deletion.

Note that the string can either be a file name or an absolute file path. If it is a file name, it looks in whatever the current directory is. This can be changed using the command set-current-directory. It is defaulted to the model's directory.

file-exists?

file-exists? string

Reports true if string is the name of an existing file on the system. Otherwise it reports false.

Note that the string can either be a file name or an absolute file path. If it is a file name, it looks in whatever the current directory is. This can be changed using the command set-current-directory. It defaults to to the model's directory.

file-flush

file-flush

Forces file updates to be written to disk. When you use file-write or other output commands, the values may not be immediately written to disk. This improves the performance of the file output commands. Closing a file ensures that all output is written to disk.

Sometimes you need to ensure that data is written to disk without closing the file. For example, you could be using a file to communicate with another program on your machine and want the other program to be able to see the output immediately.

file-open

file-open string

This command will interpret string as a path name to a file and open the file. You may then use the reporters file-read, file-read-line, and file-read-characters to read in from the file, or file-write, file-print, file-type, or file-show to write out to the file.

Note that you can only open a file for reading or writing but not both. The next file i/o primitive you use after this command dictates which mode the file is opened in. To switch modes, you need to close the file using file-close.

Also, the file must already exist if opening a file in reading mode.

When opening a file in writing mode, all new data will be appended to the end of the original file. If there is no original file, a new blank file will be created in its place. (You must have write permission in the file's directory.) (If you don't want to append, but want to replace the file's existing contents, use file-delete to delete it first, perhaps inside a carefully if you're not sure whether it already exists.)

Note that the string can either be a file name or an absolute file path. If it is a file name, it looks in whatever the current directory is. This can be changed using the command set-current-directory. It is defaulted to the model's directory.

file-open "my-file-in.txt"
print file-read-line
=> First line in file ;; File is in reading mode
file-open "C:\\NetLogo\\my-file-out.txt"
;; assuming Windows machine
file-print "Hello World" ;; File is in writing mode

See also file-close.

file-print

file-print value

Prints value to an opened file, followed by a carriage return.

The calling agent is not printed before the value, unlike file-show.

Note that this command is the file i/o equivalent of print, and file-open needs to be called before this command can be used.

See also file-show, file-type, and file-write.

file-read

file-read

This reporter will read in the next constant from the opened file and interpret it as if it had been typed in the Command Center. It reports the resulting value. The result may be a number, list, string, boolean, or the special value nobody.

Whitespace separates the constants. Each call to file-read will skip past both leading and trailing whitespace.

Note that strings need to have quotes around them. Use the command file-write to have quotes included.

Also note that the file-open command must be called before this reporter can be used, and there must be data remaining in the file. Use the reporter file-at-end? to determine if you are at the end of the file.

file-open "my-file.data"
print file-read + 5
;; Next value is the number 1
=> 6
print length file-read
;; Next value is the list [1 2 3 4]
=> 4

See also file-open and file-write.

file-read-characters

file-read-characters number

Reports the given number of characters from an opened file as a string. If there are fewer than that many characters left, it will report all of the remaining characters.

Note that it will return every character including newlines and spaces.

Also note that the file-open command must be called before this reporter can be used, and there must be data remaining in the file. Use the reporter file-at-end? to determine if you are at the end of the file.

file-open "my-file.txt"
print file-read-characters 5
;; Current line in file is "Hello World"
=> Hello

See also file-open.

file-read-line

file-read-line

Reads the next line in the file and reports it as a string. It determines the end of the file by a carriage return, an end of file character or both in a row. It does not return the line terminator characters.

Also note that the file-open command must be called before this reporter can be used, and there must be data remaining in the file. Use the reporter file-at-end? to determine if you are at the end of the file.

file-open "my-file.txt"
print file-read-line
=> Hello World

See also file-open.

file-show

file-show value

Prints value to an opened file, preceded by the calling agent, and followed by a carriage return. (The calling agent is included to help you keep track of what agents are producing which lines of output.) Also, all strings have their quotes included similar to file-write.

Note that this command is the file i/o equivalent of show, and file-open needs to be called before this command can be used.

See also file-print, file-type, and file-write.

file-type

file-type value

Prints value to an opened file, not followed by a carriage return (unlike file-print and file-show). The lack of a carriage return allows you to print several values on the same line.

The calling agent is not printed before the value. unlike file-show.

Note that this command is the file i/o equivalent of type, and file-open needs to be called before this command can be used.

See also file-print, file-show, and file-write.

file-write

file-write value

This command will output value, which can be a number, string, list, boolean, or nobody to an opened file, not followed by a carriage return (unlike file-print and file-show).

The calling agent is not printed before the value, unlike file-show. Its output also includes quotes around strings and is prepended with a space. It will output the value in such a manner that file-read will be able to interpret it.

Note that this command is the file i/o equivalent of write, and file-open needs to be called before this command can be used.

file-open "locations.txt"
ask turtles 
  [ file-write xcor file-write ycor ]

See also file-print, file-show, and file-type.

filter

filter [reporter] list

Reports a list containing only those items of list for which the boolean reporter is true -- in other words, the items satisfying the given condition.

In reporter, use ? to refer to the current item of list.

show filter [? < 3] [1 3 2]
=> [1 2]
show filter [first ? != "t"] ["hi" "there" "everyone"]
=> ["hi" "everyone"]

See also map, reduce, ?.

first

first list
first string

On a list, reports the first (0th) item in the list.

On a string, reports a one-character string containing only the first character of the original string.

floor

floor number

Reports the largest integer less than or equal to number.

show floor 4.5
=> 4
show floor -4.5
=> -5

follow

follow turtle

Similar to ride, but, in the 3D view, the observer's vantage point is behind and above turtle.

See also follow-me, ride, reset-perspective, watch, subject.

follow-me

follow-me

Asks the observer to follow the calling turtle.

See also follow.

foreach

foreach list [ commands ]
(foreach list1 ... [ commands ])

With a single list, runs commands for each item of list. In commands, use ? to refer to the current item of list.

foreach [1.1 2.2 2.6] [ show (word ? " -> " round ?) ]
=> 1.1 -> 1
=> 2.2 -> 2
=> 2.6 -> 3

With multiple lists, runs commands for each group of items from each list. So, they are run once for the first items, once for the second items, and so on. All the lists must be the same length. In commands, use ?1 through ?n to refer to the current item of each list.

Some examples make this clearer:

(foreach [1 2 3] [2 4 6]
   [ show word "the sum is: " (?1 + ?2) ])
=> "the sum is: 3"
=> "the sum is: 6"
=> "the sum is: 9"
(foreach list (turtle 1) (turtle 2) [3 4]
  [ ask ?1 [ fd ?2 ] ])
;; turtle 1 moves forward 3 patches
;; turtle 2 moves forward 4 patches

See also map, ?.

forward
fd

forward number

The turtle moves forward by number steps, one step at a time. (If number is negative, the turtle moves backward.)

fd 10 is equivalent to repeat 10 [ jump 1 ]. fd 10.5 is equivalent to repeat 10 [ jump 1 ] jump 0.5.

If the turtle cannot move forward number steps because it is not permitted by the current topology the turtle will complete as many steps of 1 as it can, then stop.

See also jump, can-move?.

fput

fput item list

Adds item to the beginning of a list and reports the new list.

;; suppose mylist is [5 7 10]
set mylist fput 2 mylist
;; mylist is now [2 5 7 10]

globals

globals [var1 ...]

This keyword, like the breed, <breeds>-own, patches-own, and turtles-own keywords, can only be used at the beginning of a program, before any function definitions. It defines new global variables. Global variables are "global" because they are accessible by all agents and can be used anywhere in a model.

Most often, globals is used to define variables or constants that need to be used in many parts of the program.

hatch
hatch-<breeds>

hatch number [ commands ]
hatch-<breeds> number [ commands ]

This turtle creates number new turtles. Each new turtle is identical to, and at the same location as, its parent. The new turtles then run commands. You can use the commands to give the new turtles different colors, headings, locations, or whatever. (The new turtles are created all at once, then run one at a time, in random order.)

If the hatch-<breeds> form is used, the new turtles are created as members of the given breed. Otherwise, the new turtles are the same breed as their parent.

Note: While the commands are running, no other agents are allowed to run any code (as with the without-interruption command). This ensures that if ask-concurrent is being used, the new turtles cannot interact with any other agents until they are fully initialized.

hatch 1 [ lt 45 fd 1 ]
;; this turtle creates one new turtle,
;; and the child turns and moves away
hatch-sheep 1 [ set color black ]
;; this turtle creates a new turtle
;; of the sheep breed

See also create-turtles, sprout.

heading

heading

This is a built-in turtle variable. It indicates the direction the turtle is facing. This is a number greater than or equal to 0 and less than 360. 0 is north, 90 is east, and so on. You can set this variable to make a turtle turn.

See also right, left, dx, dy.

Example:

set heading 45      ;; turtle is now facing northeast
set heading heading + 10 ;; same effect as "rt 10"

hidden?

hidden?

This is a built-in turtle or link variable. It holds a boolean (true or false) value indicating whether the turtle or link is currently hidden (i.e., invisible). You can set this variable to make a turtle or link disappear or reappear.

See also hide-turtle, show-turtle, hide-link, show-link

Example:

set hidden? not hidden?
;; if turtle was showing, it hides, and if it was hiding,
;; it reappears

hide-link

hide-link

The link makes itself invisible.

Note: This command is equivalent to setting the link variable "hidden?" to true.

See also show-link.

hide-turtle
ht

hide-turtle

The turtle makes itself invisible.

Note: This command is equivalent to setting the turtle variable "hidden?" to true.

See also show-turtle.

histogram

histogram list

Histograms the values in the given list

Draws a histogram showing the frequency distribution of the values in the list. The heights of the bars in the histogram represent the numbers of values in each subrange.

Before the histogram is drawn, first any previous points drawn by the current plot pen are removed.

Any non-numeric values in the list are ignored.

The histogram is drawn on the current plot using the current plot pen and pen color. Use set-plot-x-range to control the range of values to be histogrammed, and set the pen interval (either directly with set-plot-pen-interval, or indirectly via set-histogram-num-bars) to control how many bars that range is split up into.

Be sure that if you want the histogram drawn with bars that the current pen is in bar mode (mode 1).

For histogramming purposes the plot's X range is not considered to include the maximum X value. Values equal to the maximum X will fall outside of the histogram's range.

histogram [color] of turtles
;; draws a histogram showing how many turtles there are
;; of each color

home

home

The calling turtles moves to the origin (0,0). Equivalent to setxy 0 0.

hsb

hsb hue saturation brightness

Reports a RGB list when given a color in HSB format. Hue, saturation, and brightness are integers in the range 0-255. The RGB list contains three integers in the same range.

See also rgb

hubnet-broadcast

hubnet-broadcast tag-name value

This broadcasts value from NetLogo to the variable, in the case of Calculator HubNet, or interface element, in the case of Computer HubNet, with the name tag-name to the clients.

See the HubNet Authoring Guide for details and instructions.

hubnet-broadcast-view

hubnet-broadcast-view

This broadcasts the current state of the 2D view in the NetLogo model to all the Computer HubNet Clients. It does nothing for Calculator HubNet.

Note: This is an experimental primitive and its behavior may change in a future version.

See the HubNet Authoring Guide for details and instructions.

hubnet-enter-message?

hubnet-enter-message?

Reports true if a new computer client just entered the simulation. Reports false otherwise. hubnet-message-source will contain the user name of the client that just logged on.

See the HubNet Authoring Guide for details and instructions.

hubnet-exit-message?

hubnet-exit-message?

Reports true if a computer client just exited the simulation. Reports false otherwise. hubnet-message-source will contain the user name of the client that just logged off.

See the HubNet Authoring Guide for details and instructions.

hubnet-fetch-message

hubnet-fetch-message

If there is any new data sent by the clients, this retrieves the next piece of data, so that it can be accessed by hubnet-message, hubnet-message-source, and hubnet-message-tag. This will cause an error if there is no new data from the clients.

See the HubNet Authoring Guide for details.

hubnet-message

hubnet-message

Reports the message retrieved by hubnet-fetch-message.

See the HubNet Authoring Guide for details.

hubnet-message-source

hubnet-message-source

Reports the name of the client that sent the message retrieved by hubnet-fetch-message.

See the HubNet Authoring Guide for details.

hubnet-message-tag

hubnet-message-tag

Reports the tag that is associated with the data that was retrieved by hubnet-fetch-message. For Calculator HubNet, this will report one of the variable names set with the hubnet-set-client-interface primitive. For Computer HubNet, this will report one of the Display Names of the interface elements in the client interface.

See the HubNet Authoring Guide for details.

hubnet-message-waiting?

hubnet-message-waiting?

This looks for a new message sent by the clients. It reports true if there is one, and false if there is not.

See the HubNet Authoring Guide for details.

hubnet-reset

hubnet-reset

Starts up the HubNet system. HubNet must be started to use any of the other hubnet primitives with the exception of hubnet-set-client-interface.

See the HubNet Authoring Guide for details.

hubnet-send

hubnet-send string tag-name value

hubnet-send list-of-strings tag-name value

For Calculator HubNet, this primitive acts in exactly the same manner as hubnet-broadcast. (We plan to change this in a future version of NetLogo.)

For Computer HubNet, it acts as follows:

For a string, this sends value from NetLogo to the tag tag-name on the client that has string for its user name.

For a list-of-strings, this sends value from NetLogo to the tag tag-name on all the clients that have a user name that is in the list-of-strings.

Sending a message to a non-existent client, using hubnet-send, generates a hubnet-exit-message.

See the HubNet Authoring Guide for details.

hubnet-send-view

hubnet-send-view string

hubnet-send-view list-of-strings

For Calculator HubNet, does nothing.

For Computer HubNet, it acts as follows:

For a string, this sends the current state of the 2D view in the NetLogo model to the Computer HubNet Client with string for its user name.

For a list-of-strings, this sends the current state of the view in the NetLogo model to all the Computer HubNet Clients that have a user name that is in the list-of-strings.

Sending the 2D view to a nonexistent client, using hubnet-send-view, generates a hubnet-exit-message.

Note: This is an experimental primitive and its behavior may change in a future version.

See the HubNet Authoring Guide for details.

hubnet-set-client-interface

hubnet-set-client-interface client-type client-info

If client-type is "COMPUTER", client-info is an empty list for computer HubNet.

hubnet-set-client-interface "COMPUTER"[]

Future versions of HubNet will support other client types. Even for Computer HubNet, the meaning of the second input to this command may change.

See the HubNet Authoring Guide for details.

if

if condition [ commands ]

Reporter must report a boolean (true or false) value.

If condition reports true, runs commands.

The reporter may report a different value for different agents, so some agents may run commands and others don't.

if xcor > 0[ set color blue ]
;; turtles in the right half of the world
;; turn blue

See also ifelse, ifelse-value.

ifelse

ifelse reporter [ commands1 ] [ commands2 ]

Reporter must report a boolean (true or false) value.

If reporter reports true, runs commands1.

If reporter reports false, runs commands2.

The reporter may report a different value for different agents, so some agents may run commands1 while others run commands2.

ask patches
  [ ifelse pxcor > 0
      [ set pcolor blue ]
      [ set pcolor red ] ]
;; the left half of the world turns red and
;; the right half turns blue

See also if, ifelse-value.

ifelse-value

ifelse-value reporter [reporter1] [reporter2]

Reporter must report a boolean (true or false) value.

If reporter reports true, the result is the value of reporter1.

If reporter reports false, the result is the value of reporter2.

This can be used when a conditional is needed in the context of a reporter, where commands (such as ifelse) are not allowed.

ask patches [
  set pcolor ifelse-value (pxcor > 0) [blue] [red]
]
;; the left half of the world turns red and
;; the right half turns blue
show n-values 10 [ifelse-value (? < 5) [0] [1]]
=> [0 0 0 0 0 1 1 1 1 1]
show reduce [ifelse-value (?1 > ?2) [?1] [?2]]
  [1 3 2 5 3 8 3 2 1]
=> 8

See also if, ifelse.

import-drawing

import-drawing filename

Reads an image file into the drawing, scaling it to the size of the world, while retaining the original aspect ratio of the image. The image is centered in the drawing. The old drawing is not cleared first.

Agents cannot sense the drawing, so they cannot interact with or process images imported by import-drawing. If you need agents to sense an image, use import-pcolors or import-pcolors-rgb.

The following image file formats are supported: BMP, JPG, GIF, and PNG. If the image format supports transparency (alpha), that information will be imported as well.

import-pcolors

import-pcolors filename

Reads an image file, scales it to the same dimensions as the patch grid while maintaining the original aspect ratio of the image, and transfers the resulting pixel colors to the patches. The image is centered in the patch grid. The resulting patch colors may be distorted, since the NetLogo color space does not include all possible colors. (See the Color section of the Programming Guide.) import-pcolors may be slow for some images, particularly when you have many patches and a large image with many different colors.

Since import-pcolors sets the pcolor of patches, agents can sense the image. This is useful if agents need to analyze, process, or otherwise interact with the image. If you want to simply display a static backdrop, without color distortion, see import-drawing.

The following image file formats are supported: BMP, JPG, GIF, and PNG. If the image format supports transparency (alpha), then all fully transparent pixels will be ignored. (Partially transparent pixels will be treated as opaque.)

import-pcolors-rgb

import-pcolors-rgb filename

Reads an image file, scales it to the same dimensions as the patch grid while maintaining the original aspect ratio of the image, and transfers the resulting pixel colors to the patches. The image is centered in the patch grid. Unlike import-pcolors the exact colors in the original image are retained. The pcolor variable of all the patches will be an RGB list rather than an (approximated) NetLogo color.

The following image file formats are supported: BMP, JPG, GIF, and PNG. If the image format supports transparency (alpha), then all fully transparent pixels will be ignored. (Partially transparent pixels will be treated as opaque.)

import-world

import-world filename

Reads the values of all variables for a model, both built-in and user-defined, including all observer, turtle, and patch variables, from an external file named by the given string. The file should be in the format used by the export-worl