email: frank@consxy.com | resume (pdf)

CLNL NVM

NetLogo Virtual Machine: the simulation engine.

- function agent-value* - agent-value is the general agent variable access function. For many NetLogo reporters, the compilation results is agent-value. The list of valid values are any builtin variable in the NetLogo dictionary, as well as any -own variable.
- function ask - ask is equivalent to ask in NetLogo.
- function clear-all - Clears ticks, turtles, patches, globals (unimplemented).
- function count - count is equivalent to count in netLogo. Returns n, the number of agents in agentset.
- function create-turtles - Creates n new turtles at the origin.
- function create-world - Initializes the world in the NVM.
- function current-state - Dumps out the state of the world.
- function die - The turtle or link dies
- function display - As of yet, this does nothing. A placeholder method for forced dipslay updates from the engine.
- function export-world - Dumps out a csv matching NetLogo's export world.
- function forward - Moves the current turtle forward n steps, one step at a time.
- function hatch - The turtle in self creates n new turtles. Each new turtle inherits of all its variables, including its location, from self.
- function lookup-color - Returns the number used to represent colors in NetLogo.
- function of - of is equivalent to of in NetLogo.
- function one-of - From an agentset, returns a random-agent. If the agentset is empty, returns :nobody. From a list, returns a random-value. If the list is empty, an error occurs.
- function patches - Reports the agentset consisting of all the patches.
- function random - Returns a random number strictly closer to zero than n.
- function random-float - Returns a random number strictly closer to zero than n.
- function random-xcor - Returns a random floating point number in the allowable range of turtle coordinates along the x axis.
- function random-ycor - Returns a random floating point number in the allowable range of turtle coordinates along the y axis.
- function reset-ticks - Resets the tick counter to zero, sets up all plots, then updates all plots.
- function set-default-shape - Specifies a default initial shape for a breed. When a turtle, or it changes breeds, its shape is set to the given shape.
- function setxy - Sets the x-coordinate and y-coordinate for the turle. Equivalent to set xcor x set ycor y, except it happens in one step inside of two.
- function show - A command that prints the given NetLogo value to the command center.
- function stop - Returns from the current stop block, which will halt the currently running thing, be that the program, current ask block, or procedure. Stop has odd semantics that are best gleaned from the actual NetLogo manual.
- function tick - Advances the tick counter by one and updates all plots.
- function ticks - Reports the current value of the tick counter. The result is always a number and never negative.
- function turn-left - The turtle turns left by number degrees. (If number is negative, it turns right.)
- function turn-right - The turtle turns right by number degrees. (If number is negative, it turns left.)
- function turtles - Reports the agentset consisting of all the turtles.
- function turtles-here - Returns the agentset consisting of all the turtles sharing the patch with the agent in by self
- function with - with is equivalent to with in NetLogo.
- function with-stop-handler - with-stop-handler is a convenience macro to handle when programs issue a stop condition. When one does, a simple :stop is returned.

agent-value var &optional agent => result

var---A variable name agent---an agent, defaulting to self result---the value of var

agent-value is the general agent variable access function. For many NetLogo reporters, the compilation results is agent-value. The list of valid values are any builtin variable in the NetLogo dictionary, as well as any *-own variable.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html for builtins

ask agent-or-agentset fn => result

`agent-or-agentset::= agent | agentset`

`result::= :undefined`

fn---a function, run on each agent agent---a NetLogo agent agentset---a NetLogo agentset

ask is equivalent to ask in NetLogo.

The specified agentSET or agent runs the given fn. In the case of an agentSET, the order in which the agents are run is random each time, and only agents that are in the set at the beginning of the call.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#ask

clear-all => result

`result::= :undefined`

Clears ticks, turtles, patches, globals (unimplemented).

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#clear-all

count agentset => n

agentset---a netLogo agentset n---a number

count is equivalent to count in netLogo. Returns n, the number of agents in agentset.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#count

create-turtles n &optional breed fn => result

`result::= :undefined`

n---an integer, the numbers of turtles to create breed---a breed fn---A function, applied to each turtle after creation

Creates n new turtles at the origin.

new turtles have random integer headings and the color is randomly selected from the 14 primary colors. If Fn is supplied, the new turtles immediately run it. If a breed is supplied, that is the breed the new turtles are set to.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#create-turtles

create-world &key dims globals turtles-own-vars patches-own-vars breeds => result

```dims::= (:xmin xmin :xmax xmax :ymin ymin :ymax ymax)` `

globals::= global` `

turtles-own-vars::= turtles-own-var` `

patches-own-vars::= patches-own-var` `

breeds::= breed``` `result::= :undefined`

`global::= (global-name global-access-func)`

xmin---An integer representing the minimum patch coord in X xmax---An integer representing the maximum patch coord in X ymin---An integer representing the minimum patch coord in Y ymax---An integer representing the maximum patch coord in Y turtles-own-var---Symbol for the turtles own variable in the keyword package patches-own-var---Symbol for the patches own variable in the keyword package breed---A list of symbols representing the possible preeds global-name---Symbol for the global in the keyword package global-access-func---Function to get the value of the global

Initializes the world in the NVM.

This should be called before using the engine in any real capacity. If called when an engine is already running, it may do somethign weird.

current-state => world-state

world-state---A list, the current state of the whole world

Dumps out the state of the world.

This is useful for visualizations and also storing in a common lisp data structure for easy usage in a common lisp instance. It's preferable to use this when working with the nvm than the output done by export-world.

Currently this only dumps out turtle and patch information.

This is called current-state because export-world is an actual primitive used by NetLogo.

die => result

`result::= :undefined`

The turtle or link dies

A dead agent ceases to exist. The effects of this include: - The agent will not execute any further code. - The agent will disappear from any agentsets it was in, reducing the size of those agentsets by one. - Any variable that was storing the agent will now instead have nobody in it. - If the dead agent was a turtle, every link connected to it also dies. - If the observer was watching or following the agent, the observer's perspective resets.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#die

display => result

`result::= :undefined`

As of yet, this does nothing. A placeholder method for forced dipslay updates from the engine.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#display

export-world => world-csv

world-csv---A string, the csv of the world

Dumps out a csv matching NetLogo's export world.

This is useful for serializing the current state of the engine in order to compare against NetLogo or to reimport later. Contains everything needed to boot up a NetLogo instance in the exact same state.

forward n => result

`result::= :undefined`

n---a double, the amount the turtle moves forward

Moves the current turtle forward n steps, one step at a time.

This moves forward one at a time in order to make the view updates look good in the case of a purposefully slow running instance. If the number is negative, the turtle moves backward.

If the current agent is not a turtle, it raises an error.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#forward

hatch n &optional fn => result

`result::= :undefined`

n---an integer, the numbers of turtles to hatch fn---A function, applied to each turtle after creation

The turtle in self creates n new turtles. Each new turtle inherits of all its variables, including its location, from self.

If Fn is supplied, the new turtles immediately run it.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#hatch

lookup-color color => color-number

color---a symbol representing a color color-number---the NetLogo color integer

Returns the number used to represent colors in NetLogo.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#Constants

of fn agent-or-agentset => result

`agent-or-agentset::= agent | agentset`

`result::= result-list | result-value`

fn---a function, run on each agent agent---a NetLogo agent agentset---a NetLogo agentset result-list---a list result-value---a single value

of is equivalent to of in NetLogo.

The specified agentSET or agent runs the given fn. In the case of an agentSET, the order in which the agents are run is random each time, and only agents that are in the set at the beginning of the call.

result-LIST is returned when the input is an agentSET, but result-VALUE is returned when only passed an agent.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#of

one-of list-or-agentset => result

`list-or-agentset::= list | agentset`

`result::= random-value | random-agent | :nobody`

list---A list agentset---An agent set random-value---a value in list random-agent---an agent if agentset is non empty

From an agentset, returns a random-agent. If the agentset is empty, returns :nobody. From a list, returns a random-value. If the list is empty, an error occurs.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#one-of

patches => all-patches

all-patches---a NetLogo agentset, all patches

Reports the agentset consisting of all the patches.

This agentset is special in that it represents the living patches each time it's used, so changes depending on the state of the engine.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#patches

random n => random-number

n---an integer, the upper bound of the random random-number---an integer, the random result

Returns a random number strictly closer to zero than n.

If number is positive, returns a random integer greater than or equal to 0, but strictly less than number.

If number is negative, returns a random integer less than or equal to 0, but strictly greater than number.

If number is zero, the result is always 0.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random

random-float n => random-number

n---a double, the upper bound of the random float random-number---a double, the random result

Returns a random number strictly closer to zero than n.

If number is positive, returns a random floating point number greater than or equal to 0 but strictly less than number.

If number is negative, returns a random floating point number less than or equal to 0, but strictly greater than number.

If number is zero, the result is always 0.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random-float

random-xcor => random-number

random-number---a float, the random result

Returns a random floating point number in the allowable range of turtle coordinates along the x axis.

These range from min-pxcor - 0.5 (inclusive) to max-pxcor + 0.5 (exclusive)

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random-cor

random-ycor => random-number

random-number---a float, the random result

Returns a random floating point number in the allowable range of turtle coordinates along the y axis.

These range from min-pycor - 0.5 (inclusive) to max-pycor + 0.5 (exclusive)

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random-cor

reset-ticks => result

`result::= :undefined`

Resets the tick counter to zero, sets up all plots, then updates all plots.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#reset-ticks

set-default-shape breed shape => result

`result::= :undefined`

breed---a valid breed shape---a string

Specifies a default initial shape for a breed. When a turtle, or it changes breeds, its shape is set to the given shape.

set-default-shape doesn't affect existing agents, only agents you create afterwards.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#set-default-shape

setxy x y => result

`result::= :undefined`

x---a double y---a double

Sets the x-coordinate and y-coordinate for the turle. Equivalent to set xcor x set ycor y, except it happens in one step inside of two.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#setxy

show value => result

`result::= :undefined`

value---a NetLogo value

A command that prints the given NetLogo value to the command center.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#show

stop => result

`result::= :undefined`

Returns from the current stop block, which will halt the currently running thing, be that the program, current ask block, or procedure. Stop has odd semantics that are best gleaned from the actual NetLogo manual.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#stop

tick => result

`result::= :undefined`

Advances the tick counter by one and updates all plots.

If the tick counter has not been started yet with reset-ticks, an error results.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#tick

ticks => current-ticks

current-ticks---A positiv double, representing the current number of ticks

Reports the current value of the tick counter. The result is always a number and never negative.

If the tick counter has not been started yet with reset-ticks, an error results.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#ticks

turn-left n => result

`result::= :undefined`

n---a double, the amount the turtle turns

The turtle turns left by number degrees. (If number is negative, it turns right.)

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#right

turn-right n => result

`result::= :undefined`

n---a double, the amount the turtle turns

The turtle turns right by number degrees. (If number is negative, it turns left.)

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#right

turtles => all-turtles

all-turtles---a NetLogo agentset, all turtles

Reports the agentset consisting of all the turtles.

This agentset is special in that it represents the living turtles each time it's used, so changes depending on the state of the engine.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#turtles

turtles-here => turtles

turtles---an agentset

Returns the agentset consisting of all the turtles sharing the patch with the agent in by self

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#turtles-here

with agentset fn => result-agentset

agentset---a NetLogo agentset fn---a boolean function, run on each agent to determine if included result-agentset---an agentset of valid agents

with is equivalent to with in NetLogo.

Returns a new agentset containing only those agents that reported true when fn is called.

See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#with

with-stop-handler &rest forms => handled-form

forms---body to be handled handled-form---body with handling

with-stop-handler is a convenience macro to handle when programs issue a stop condition. When one does, a simple :stop is returned.