Command List

These are all the commands that affect properties of a patch. A patch has several built-in properties: xcor, ycor, and patch color. Additional properties may be declared by you, with the patches-own command.

Turtle, Observer, Patch

ask-patch-at [list of commands]

Parameters:
[list of commands] List of patch commands A list of commands for the patch to run

Description:
This command asks the patch which is xcor units in the x direction and ycor units in the y direction away from the caller to run the [list of commands]. The caller of this command will wait for the patch to finish before moving on. The observer is considered to be located at (0, 0).

Examples:
ask-patch-at 5 6 [setpc red] makes the patch 5 units to the right and 6 units up from the caller turn red.

ask-patch-at -3 -8 [setpc blue] makes the patch 3 units to the left and 8 units down from the caller turn blue.

Related Commands:
ask-breed ask-list-of-turtles ask-patches ask-patches-with ask-turtle ask-turtles ask-turtles-with
Observer

ask-patches [list of commands]

Parameters:
[list of commands] List of patch commands A list of commands for the patches to run

Description:
This observer command asks all of the patches to run the [list of commands]. The observer will wait for the patches to finish before moving on.

Asking the patches to do something is a moderately expensive operation since StarLogo creates a thread for each patch. Try to group commands that you would have put into separate ask-patches into the same one to minimize thread creation overhead.

Examples:
ask-patches [setpc red] colors all of the patches red.

Related Commands:
ask-breed ask-list-of-turtles ask-patch-at ask-turtle ask-turtles ask-turtles-with setbg
Observer

ask-patches-with [condition] [list-of-commands]

Parameters:
[condition] List of patch commands list of commands that evaluates to either true or false
[list-of-commands] Number list of commands to run

Description:
This observer command asks all of the patches that satisfy [condition] to run the [list-of-commands]. The observer will wait for the patches to finish before moving on.

Examples:
ask-patches-with [pc = red] [setpc blue] colors all of the red patches blue

Related Commands:
ask-patch-at
Turtle, Observer, Patch

average-of-patches [list of commands]

Parameters:
[list of commands] List of patch commands A list of commands for the patches to run which returns a number

Description:
Returns the numerical average of the [list of commands] when evaluated across all the patches.

Examples:
average-of-patches [pc] returns the average of the patch color of all of the patches.

Notes:
If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-breed median-of-patches min-of-patches mode-of-patches sum-of-patches variance-of-patches
Turtle, Observer, Patch

average-of-patches-with [condition] [list of commands]

Parameters:
[condition] List of patch commands An expression that returns a true or false value
[list of commands] List of patch commands A list of commands for the patches to run which returns a number

Description:
Returns the numerical average of the [list of commands] when evaluated across all the patches that satisfy the condition (must return a boolean of true or false) specified by the [condition].

Examples:
average-of-patches-with [color = red] [food] returns the average food of all the red patches

Notes:
If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-breed-with median-of-patches-with min-of-patches-with mode-of-patches-with sum-of-patches-with variance-of-patches-with
Observer

clear-graphics (cg)

Description:
Sets all patches to black.

Observer

clear-patches

Description:
Sets all patches to black and resets all patch variables to 0.

Observer

clearall (ca) (clear-all)

Description:
Kills all turtles, sets all patches to black, and resets all variables to 0.

Turtle, Observer, Patch

count-patches

Description:
Returns the number of patches.

Related Commands:
count-patches-with count-turtles
Turtle, Observer, Patch

count-patches-with [list of commands]

Parameters:
[list of commands] Number condition to determine whether to count a turtle

Description:
Returns the number of patches whose [list of commands] is true.

Examples:
count-patches-with [(distance 0 0) < 5] returns the number of patches inside a circle of radius 5 centered at the origin.

Related Commands:
count-patches
Turtle, Observer, Patch

count-pc color

Parameters:
color Number color to determine whether to count a patch

Description:
Returns the number of patches that are the color color.

Examples:
count-pc blue returns the number of blue patches.

Notes:
This command can also be executed by patches, for example within an ask-patches statement.

Related Commands:
count-color count-color-range count-pc-range
Turtle, Observer, Patch

count-pc-range mincolor maxcolor

Parameters:
mincolor Number low end of range of colors to determine whether to count a patch
maxcolor Number high end of range of colors to determine whether to count a patch

Description:
Returns the number of patches that have colors between mincolor and maxcolor, inclusive.

Examples:
count-pc-range 64 66.5 returns the number of patches that are lime (65) or very close to it.

Related Commands:
count-color count-color-range count-pc
Observer

diffuse variable percentage

Parameters:
variable String patch variable to diffuse
percentage Number percentage of patch variable's value to diffuse

Description:
Makes each patch give 1/8 of percentage of variable to each neighboring patch.
percentage should be expressed as a number between 0 and 1. variable should be a patch variable.

Examples:
diffuse food 20 causes each patch to give 1/8 of 20 percent of the variable food to each of its eight neighboring patches.

Notes:
diffuse must be run by the observer, even though it affects patches.

Related Commands:
diffuse4 nsum nsum4
Observer

diffuse4 variable percentage

Parameters:
variable Number patch variable to diffuse
percentage Number percentage of variable's value to diffuse

Description:
Makes each patch give 1/4 of percentage of variable to each non-diagonal (N,E,S,W) neighboring patch.
percentage should be expressed as a number between 0 and 1. variable should be a patch variable.

Examples:
diffuse food 20 causes each patch to give 1/4 of 20 percent of the variable food to each of its four directly-neighboring patches.

Notes:
diffuse4 must be run by the observer, even though it affects patches.

Related Commands:
diffuse nsum nsum4
Observer

inspect-patch xcor ycor

Parameters:
xcor Number
ycor Number

Description:
Brings up the patch monitor of the patch whose coordinates are (xcor, ycor). A patch monitor allows the user to see all of the information about a patch in real time.

Examples:
inspect-patch 1 1 brings up the patch monitor for the patch at coordinates (1,1).

Related Commands:
inspect-turtle
Turtle, Observer, Patch

max-of-patches [list of commands]

Parameters:
[list of commands] List of commands list of commands that evaluate to a number

Description:
Evaluates the [list of commands] given for every patch. Returns the coordinates of the patch whose [list of commands] value is greatest, or returns a list of coordinates if there is more than one patch with that minimum value.

Examples:
max-of-patches [food] returns the coordinates of the patch whose food variable is the largest.

Notes:
If [list of commands] contains no numbers, the smallest possible number is returned. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
max-of-turtles median-of-patches min-of-patches mode-of-patches sdev-of-patches sum-of-patches variance-of-patches
Turtle, Observer, Patch

max-of-patches-with [condition] [list of commands]

Parameters:
[condition] List of commands list of commands that evaluates to true or false
[list of commands] List of commands list of commands that evaluate to a number

Description:
Reports the highest value of [list of commands] when run over the turtles that satisfy [condition]. If there are no patches in which [condition] is true, reports minnum, the smallest number possible without going into negative infinity.

Examples:
max-of-patches-with [color = 0] [food] reports the largest food value of the black colored patches.

Notes:
This command can also be executed by patches, for example within an ask-patches statement.

Related Commands:
max-of-turtles-with median-of-patches-with min-of-patches-with mode-of-patches-with sdev-of-patches-with sum-of-patches-with variance-of-patches-with
Turtle, Observer, Patch

median-of-patches [list of commands]

Parameters:
[list of commands] Number list of commands that evaluate to a number

Description:
Returns the median of the [list of commands] when [list of commands] is evaluated by all patches.

Examples:
median-of-patches [color] returns a number corresponding to the median of the colors of all patches.

Notes:
If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches max-of-patches median-of-patches-with min-of-patches mode-of-patches sdev-of-patches sum-of-patches variance-of-patches
Turtle, Observer, Patch

median-of-patches-with [1st list of commands] [2nd list of commands]

Parameters:
[1st list of commands] List of commands list of commands that evaluates to true or false
[2nd list of commands] List list of commands that evaluate to a number

Description:
Returns the median of the [2nd list of commands] when evaluated across all the patches that satisfy the conditions specified by the [1st list of commands].

Examples:
median-of-patches-with [color = red] [food] returns the median food of all the red patches.

Notes:
If [2nd list of commands] contains no numbers, an error occurs. If some of the [2nd list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches-with max-of-patches-with median-of-patches min-of-patches-with mode-of-patches-with sdev-of-patches-with sum-of-patches-with variance-of-patches variance-of-patches-with
Turtle, Observer, Patch

min-of-patches [list of commands]

Parameters:
[list of commands] List of patch commands list of commands that evaluate to a number

Description:
Reports the lowest value of [list of commands] when run over all of the patches.

Examples:
min-of-patches [food] reports the smallest value of the patch variable food for all patches.

Notes:
Note: If [list of commands] contains no numbers, the greatest possible number is returned. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches max-of-patches median-of-patches min-of-patches-with mode-of-patches sdev-of-list sdev-of-patches sum-of-patches variance-of-patches
Turtle, Observer, Patch

min-of-patches-with [condition] [list of commands]

Parameters:
[condition] List of commands list of commands that evaluate to true or false
[list of commands] List of commands list of commands to that evaluate to a number

Description:
Reports the lowest value of [list of commands] when run over the turtles that satisfy [condition]. If there are no patches in which [condition] is true, reports maxnum, the largest number possible without going into positive infinity.

Examples:
min-of-patches-with [color = red] [food] reports the smallest value of the patch variable food for red patches.

Notes:
Note: If [list of commands] contains no numbers, the greatest possible number is returned. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches-with max-of-patches-with median-of-patches-with min-of-patches min-of-patches-with mode-of-patches-with sdev-of-patches-with sum-of-patches-with variance-of-patches-with
Turtle, Observer, Patch

mode-of-patches [list of commands]

Parameters:
[list of commands] List of patch commands list of commands that evaluate to a number

Description:
Returns the mode of the given [list of commands] when evaluated across all the patches.

Examples:
mode-of-patches [food] returns the mode of the food value for all patches.

Notes:
Note: If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches max-of-patches median-of-patches min-of-patches mode-of-patches-with sdev-of-list sdev-of-patches sum-of-patches variance-of-patches
Turtle, Observer, Patch

mode-of-patches-with [condition] [list of commands]

Parameters:
[condition] List of patch commands list of commands that evaluate to true or false
[list of commands] List of patch commands list of commands to that evaluate to a number

Description:
Returns the mode of the [list of commands] when evaluated across all the patches that satisfy the [condition]

Examples:
mode-of-patches-with [color = red] [food] returns the mode of the food of all the red patches.

Notes:
Note: If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches-with max-of-patches-with median-of-patches-with min-of-patches-with mode-of-patches sdev-of-patches-with sum-of-patches-with variance-of-patches-with
Observer

nsum neighbor-variable patch-sum-variable

Parameters:
neighbor-variable Variable the variable of the neighbor you would like to sum up
patch-sum-variable Variable the variable that should be set to the sum of the neighbors' variables

Description:
For each patch, takes the sum of neighbor-variable from all neighboring patches and places it in patch-sum-variable. Both neighbor-variable and patch-sum-variable should be patch variables.

Examples:
nsum food surrounding-food takes the food variable of all the surrounding patches and stores the value of their sum in the patch-variable surrounding-food.

Notes:
nsum must be run by the observer even though it affects patches.

Related Commands:
diffuse diffuse4 nsum4
Observer

nsum4 neighbor-variable patch-sum-variable

Parameters:
neighbor-variable Variable the variable of the neighbor you would like to sum up
patch-sum-variable Variable the variable that should be set to the sum of the neighbors' variables

Description:
For each patch, takes the sum of neighbor-variable from the non-diagonal (N,E,S,W) neighboring patches and places it in patch-sum-variable. Variable should be a patch variable.

Examples:
nsum4 grass totalgrass adds up the value of grass in the non-diagonal patches and places it in totalgrass.

Notes:
nsum4 must be run by the observer even though it affects patches.

Related Commands:
diffuse diffuse4 nsum
Turtle, Patch

patchcolor (pc)

Description:
Reports the color of the patch the turtle is on.

Examples:
if pc = red [fd 1] commands the turtle to move forward one unit if the color of the patch the turtle is on is red.

Notes:
This command can also be executed by patches, for example within an ask-patches statement.

Related Commands:
pc-ahead pc-ahead-one-patch pc-at pc-towards setbg setpc stamp
Observer

patches-own [variable-list]

Parameters:
[variable-list] Variable a list of patch variables separated by spaces

Description:
Defines a set of variables to be properties of patches. The [variable-list] contains one or more names separated by spaces

Examples:
patches-own [size value] declares two patch variables - size and value.

Notes:
patches-own must only be used once in any program, and remain outside of any procedures. Typically patches-own is defined once at the top of the Observer Procedures window.

Related Commands:
breeds globals turtles-own
Turtle

pc-ahead (pc-ahead-one-step)

Description:
Reports the color of the patch one space ahead in the direction that the turtle is facing. If called by the observer, it will assume coordinates of (0,0).

Notes:
if pc-ahead = blue [fd 1] commands the caller to move forward 1 if the patch ahead of it is blue.

Related Commands:
patchcolor pc-ahead-one-patch pc-at pc-towards
Turtle

pc-ahead-one-patch

Description:
Returns the color of the patch one patch ahead. This is equivalent to pc-at round dx round dy

Examples:
pc-ahead-one-patch will return the color of the next patch in front of the turtle

Notes:
The patch returned may or may not be the same as pc-ahead. In this version the patch returned is never the same as the patch that the caller is on.

Related Commands:
patchcolor pc-ahead
Turtle, Observer, Patch

pc-at xcor ycor

Parameters:
xcor Number
ycor Number

Description:
Reports the color of the patch xcor units in the x direction and ycor units in the y direction away from the caller.

Examples:
pc-at 1 1 reports the color of the patch one unit to the right and one unit above the caller.

Notes:
This command can also be executed by patches, for example within an ask-patches statement.

Related Commands:
patchcolor pc-ahead pc-towards stamp-at
Turtle, Observer, Patch

pc-towards angle distance

Parameters:
angle Number
distance Number

Description:
Reports the color of the patch angle away at an angle distance from the caller.

Examples:
pc-towards 0 1 returns the color of the patch which is one unit directly in front of the caller.

Notes:
This command can also be executed by patches, for example within an ask-patches statement.

Related Commands:
patchcolor pc-ahead pc-at stamp-towards
Turtle, Patch

scale-pc color variable limit1 limit2

Parameters:
color Number Color
variable Number
limit1 Number Lower limit
limit2 Number Upper limit

Description:
Patches set their color to a shade of color based on their value of variable. limit1 and limit2 determine the amount of gradation. If a turtle calls this, the patch underneath the turtle scale its patch color.

Examples:
scale-color green density 0 20
Patches turn one of twenty shades of green. Patches with lower density turn darker green.

scale-color blue energy 20 0
Patches turn one of twenty shades of green. Patches with lower density turn lighter green.

Notes:
This is a patch command. It must be called from within an ask-patches or ask-patch-at statement.

If the patch exceeds the limits, it turns black on the dark end of the specturm and turns white on the bright end of the spectrum.

Related Commands:
scale-color setpc
Turtle, Observer, Patch

sdev-of-patches [list of commands]

Parameters:
[list of commands] List of commands

Description:
Returns the standard deviation of the given [list of commands] when evaluated across all the patches.

Examples:
sdev-of-patches [food] returns the stadard deviation of the food amongst all the patches.

Notes:
If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
max-of-patches median-of-patches min-of-patches mode-of-patches sdev-of-patches-with sum-of-patches variance-of-patches
Turtle, Observer, Patch

sdev-of-patches-with [first list of commands] [second list of commands]

Parameters:
[first list of commands] List of commands
[second list of commands] List of commands

Description:
Returns the standard deviation of the [second list of commands] when evaluated across all the patches that satisfy the conditions (must return a boolean of true or false) specified by the [first list of commands].

Examples:
sdev-of-patches-with [color = red] [food] returns the standard deviation of the food of all the red patches.

Notes:
If [second list of commands] contains no numbers, an error occurs. If some of the [second list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
max-of-patches-with median-of-patches-with min-of-patches-with mode-of-patches-with sdev-of-patches sum-of-patches-with variance-of-patches-with
Patch

setpc (setpatchcolor) color

Parameters:
color Color

Description:
This command is run as a patch command inside an ask-patches statement. The patches being asked will set their color to color. Use stamp if you want to have a turtle change the color of a patch.

Examples:
ask-patches [setpc blue] commands the patches to set their color to blue.

Related Commands:
patchcolor scale-pc setbg stamp
Turtle, Observer, Patch

setvariable value

Parameters:
value Anything the value to set the variable to

Description:
Sets the variable to the value specified

Examples:
setheight 5 Sets the height of the caller to 5.

Notes:
variables must first be declared in a turtles-own, breeds-own, patches-own or globals

Related Commands:
set setvariable-at setvariable-of setvariable-towards variable
Turtle

stamp color

Parameters:
color Number

Description:
Sets color of patch under turtle to color

Examples:
stamp red sets the patch under the turtle to red

stamp 0 sets the patch under the turtle to color 0 (black)

stamp color sets the patch under the turtle to the color of the turtle

Related Commands:
patchcolor pstamp setpc stamp-at stamp-towards
Turtle, Observer, Patch

stamp-at xcor ycor color

Parameters:
xcor Number number of patches away in the x direction
ycor Number number of patches away in the y direction
color Number color to set

Description:
Sets the color of the patch at xcor ycor relative to the caller to color.

Examples:
stamp-at 1 1 0 sets the color of the patch one unit to the right and one unit above the caller to black (color 0).

Related Commands:
pc-at pstamp-at stamp stamp-towards
Turtle, Observer, Patch

stamp-towards angle distance color

Parameters:
angle Number angle from the caller
distance Number distance from the caller
color Number color to set

Description:
Sets the color of the patch distance away at an angle angle from the caller to color.

Examples:
stamp-towards 0 1 0 sets the color of the patch one unit directly in front of the caller to black (color 0).

Related Commands:
pc-towards pstamp-towards stamp stamp-at
Turtle, Observer, Patch

sum-of-patches [list-of-commands]

Parameters:
[list-of-commands] List of commands list of commands that return a number

Description:
Reports the sum of [list-of-commands] for every patch.

Examples:
show sum-of-patches [food] prints the total amount of food in the world.

Related Commands:
average-of-patches max-of-patches median-of-patches min-of-patches mode-of-patches sdev-of-patches sum-of-patches-with variance-of-patches
Turtle, Observer, Patch

sum-of-patches-with [condition] [list-of-commands]

Parameters:
[condition] List of commands list of commands that evaluates to either true or false
[list-of-commands] List of commands list of commands that returns a number

Description:
Reports the total value of [list-of-commands] when run over the turtles that satisfy [condition]. If there are no patches in which [condition] is true, it reports 0.

Examples:
sum-of-patches-with [pc = green or pc = blue] [density] returns the sum of the densities of all patches which are blue or green.

Notes:
This command can also be executed by patches, for example within an ask-patches statement.

Related Commands:
average-of-patches-with max-of-patches-with median-of-patches-with min-of-patches-with mode-of-patches-with sdev-of-patches-with sum-of-patches variance-of-patches-with
Turtle, Observer, Patch

variable

Description:
Returns the value of the variable specified

Examples:
height returns the value of the variable named height

Notes:
variables must first be declared in a turtles-own, breeds-own, patches-own or globals

Related Commands:
set setvariable variable-at variable-of variable-towards
Turtle, Observer, Patch

variable-at xcor ycor

Parameters:
xcor Number number of steps in the x-direction from the caller
ycor Number number of steps in the y-direction from the caller

Description:
Returns the value of the variable specified at a distance of xcor in the x direction and ycor in the y direction from the caller

Examples:
size-at 1 1 returns the size of the turtle one patch away in the x direction and y patch away in the y direction

Notes:
variables must first be declared in a turtles-own, breeds-own, patches-own or globals

Related Commands:
setvariable-at variable variable-of variable-towards
Turtle, Observer, Patch

variable-of number1

Parameters:
number1 Number turtle who number

Description:
Returns the value of the variable specified for the turtle with who number number1

Examples:
height-of 0 returns the height of turtle number 0

Notes:
variables must first be declared in a turtles-own, breeds-own, patches-own or globals

Related Commands:
setvariable-of variable variable-at variable-towards
Turtle, Observer, Patch

variable-towards angle distance

Parameters:
angle Number angle from caller
distance Number distance from caller

Description:
Returns the value of the variable specified at an angle of angle and distance of distance away from the caller

Examples:
happiness-towards 0 1 returns the happiness of the turtle directly in front of and one space beyond the caller

Notes:
variables must first be declared in a turtles-own, breeds-own, patches-own or globals

Related Commands:
setvariable-towards variable variable-at variable-of
Turtle, Observer, Patch

variance-of-patches [list of commands]

Parameters:
[list of commands] List of patch commands A list of commands for the patches to run which returns a number

Description:
Returns the numerical variance of the [list of commands] when evaluated across all the patches.

Examples:
variance-of-patches [pc] returns the variance of the patch color of all of the patches.

Notes:
If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches max-of-patches median-of-patches median-of-patches-with min-of-patches mode-of-patches sdev-of-patches sum-of-patches variance-of-patches-with
Turtle, Observer, Patch

variance-of-patches-with [condition] [list of commands]

Parameters:
[condition] List of patch commands An expression that returns a true or false value
[list of commands] List of patch commands A list of commands for the patches to run which returns a number

Description:
Returns the numerical variance of the [list of commands] when evaluated across all the patches that satisfy the condition (must return a boolean of true or false) specified by the [condition].

Examples:
variance-of-patches-with [color = red] [food] returns the variance of food of all the red patches.

Notes:
If [list of commands] contains no numbers, an error occurs. If some of the [list of commands], when evaluated, are not numbers, those values are ignored.

Related Commands:
average-of-patches-with max-of-patches-with median-of-patches-with min-of-patches-with mode-of-patches-with sdev-of-patches-with sum-of-patches-with variance-of-patches
Turtle, Patch

xcor

Description:
Returns the x-coordinate of the turtle or patch.

Examples:
if xcor = 2 [setc red] commands the turtle to set its color to red of its x-coordinate is equal to 2.

Related Commands:
setxcor who xcor-at xcor-of xcor-towards ycor
Turtle, Patch

ycor

Description:
Returns the y-coordinate of the turtle or patch.

Examples:
if ycor = 2 [setc red] commands the turtle to set its color to red of its y-coordinate is equal to 2.

Related Commands:
setycor who xcor ycor-at ycor-of ycor-towards