code.consxy.com Git - clnl/blob - docs/DocsNvm.md

   1 # Package CLNL-NVM
   2
   3 CLNL NVM
   4
   5 NetLogo Virtual Machine: the simulation engine.
   6
   7 ## Contents
   8
   9 * **function [agent-value](#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.
  10 * **function [ask](#function-ask)** - _ask_ is equivalent to ask in NetLogo.
  11 * **function [clear-all](#function-clear-all)** - Clears ticks, turtles, patches, globals (unimplemented).
  12 * **function [count](#function-count)** - _count_ is equivalent to count in _n_etLogo.  Returns _n_, the number of agents in _agentset_.
  13 * **function [create-turtles](#function-create-turtles)** - Creates _n_ new turtles at the origin.
  14 * **function [create-world](#function-create-world)** - Initializes the world in the NVM.
  15 * **function [current-state](#function-current-state)** - Dumps out the state of the world.
  16 * **function [die](#function-die)** - The turtle or link dies
  17 * **function [display](#function-display)** - As of yet, this does nothing.  A placeholder method for forced dipslay updates from the engine.
  18 * **function [export-world](#function-export-world)** - Dumps out a csv matching NetLogo's export world.
  19 * **function [forward](#function-forward)** - Moves the current turtle forward _n_ steps, one step at a time.
  20 * **function [hatch](#function-hatch)** - The turtle in *self* creates _n_ new turtles. Each new turtle inherits of all its variables, including its location, from self.
  21 * **function [lookup-color](#function-lookup-color)** - Returns the number used to represent colors in NetLogo.
  22 * **function [of](#function-of)** - _of_ is equivalent to of in NetLogo.
  23 * **function [one-of](#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.
  24 * **function [patches](#function-patches)** - Reports the agentset consisting of all the patches.
  25 * **function [random](#function-random)** - Returns a random number strictly closer to zero than _n_.
  26 * **function [random-float](#function-random-float)** - Returns a random number strictly closer to zero than _n_.
  27 * **function [random-xcor](#function-random-xcor)** - Returns a random floating point number in the allowable range of turtle coordinates along the x axis.
  28 * **function [random-ycor](#function-random-ycor)** - Returns a random floating point number in the allowable range of turtle coordinates along the y axis.
  29 * **function [reset-ticks](#function-reset-ticks)** - Resets the tick counter to zero, sets up all plots, then updates all plots.
  30 * **function [set-default-shape](#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.
  31 * **function [setxy](#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.
  32 * **function [show](#function-show)** - A command that prints the given NetLogo value to the command center.
  33 * **function [stop](#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.
  34 * **function [tick](#function-tick)** - Advances the tick counter by one and updates all plots.
  35 * **function [ticks](#function-ticks)** - Reports the current value of the tick counter. The result is always a number and never negative.
  36 * **function [turn-left](#function-turn-left)** - The turtle turns left by number degrees. (If number is negative, it turns right.)
  37 * **function [turn-right](#function-turn-right)** - The turtle turns right by number degrees. (If number is negative, it turns left.)
  38 * **function [turtles](#function-turtles)** - Reports the agentset consisting of all the turtles.
  39 * **function [turtles-here](#function-turtles-here)** - Returns the agentset consisting of all the turtles sharing the patch with the agent in by *self*
  40 * **function [with](#function-with)** - _with_ is equivalent to with in NetLogo.
  41 * **function [with-stop-handler](#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.
  42
  43 ## Function **AGENT-VALUE**
  44
  45 #### Syntax:
  46
  47 **agent-value** _var_ _&optional_ _agent_ => _result_
  48
  49 #### Arguments and Values:
  50
  51 _var_---A variable name
  52 _agent_---an agent, defaulting to *self*
  53 _result_---the value of _var_
  54
  55 #### Description:
  56
  57 _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.
  58
  59 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html for builtins
  60
  61 ## Function **ASK**
  62
  63 #### Syntax:
  64
  65 **ask** _agent-or-agentset_ _fn_ => _result_
  66
  67 ```agent-or-agentset::= agent | agentset```
  68 ```result::= :undefined```
  69
  70 #### Arguments and Values:
  71
  72 _fn_---a function, run on each agent
  73 _agent_---a NetLogo agent
  74 _agentset_---a NetLogo agentset
  75
  76 #### Description:
  77
  78 _ask_ is equivalent to ask in NetLogo.
  79
  80 The specified _agent_SET or _agent_ runs the given _fn_.  In the case of an _agent_SET, 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.
  81
  82 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#ask
  83
  84 ## Function **CLEAR-ALL**
  85
  86 #### Syntax:
  87
  88 **clear-all** => _result_
  89
  90 ```result::= :undefined```
  91
  92 #### Description:
  93
  94 Clears ticks, turtles, patches, globals (unimplemented).
  95
  96 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#clear-all
  97
  98 ## Function **COUNT**
  99
 100 #### Syntax:
 101
 102 **count** _agentset_ => _n_
 103
 104 #### Arguments and Values:
 105
 106 _agentset_---a _n_etLogo agentset
 107 _n_---a number
 108
 109 #### Description:
 110
 111 _count_ is equivalent to count in _n_etLogo.  Returns _n_, the number of agents in _agentset_.
 112
 113 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#count
 114
 115 ## Function **CREATE-TURTLES**
 116
 117 #### Syntax:
 118
 119 **create-turtles** _n_ _&optional_ _breed_ _fn_ => _result_
 120
 121 ```result::= :undefined```
 122
 123 #### Arguments and Values:
 124
 125 _n_---an integer, the numbers of turtles to create
 126 _breed_---a breed
 127 _fn_---A function, applied to each turtle after creation
 128
 129 #### Description:
 130
 131 Creates _n_ new turtles at the origin.
 132
 133 _n_ew turtles have random integer headings and the color is randomly selected from the 14 primary colors.  If F_n_ is supplied, the new turtles immediately run it.  If a _breed_ is supplied, that is the breed the new turtles are set to.
 134
 135 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#create-turtles
 136
 137 ## Function **CREATE-WORLD**
 138
 139 #### Syntax:
 140
 141 **create-world** _&key_ _dims_ _globals_ _turtles-own-vars_ _patches-own-vars_ _breeds_ => _result_
 142
 143 ```dims::= (:xmin xmin :xmax xmax :ymin ymin :ymax ymax)```
 144 ```globals::= global*```
 145 ```turtles-own-vars::= turtles-own-var*```
 146 ```patches-own-vars::= patches-own-var*```
 147 ```breeds::= breed*```
 148 ```result::= :undefined```
 149 ```global::= (global-name global-access-func)```
 150
 151 #### Arguments and Values:
 152
 153 _xmin_---An integer representing the minimum patch coord in X
 154 _xmax_---An integer representing the maximum patch coord in X
 155 _ymin_---An integer representing the minimum patch coord in Y
 156 _ymax_---An integer representing the maximum patch coord in Y
 157 _turtles-own-var_---Symbol for the turtles own variable in the keyword package
 158 _patches-own-var_---Symbol for the patches own variable in the keyword package
 159 _breed_---A list of symbols representing the possible preeds
 160 _global-name_---Symbol for the global in the keyword package
 161 _global-access-func_---Function to get the value of the global
 162
 163 #### Description:
 164
 165 Initializes the world in the NVM.
 166
 167 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.
 168
 169 ## Function **CURRENT-STATE**
 170
 171 #### Syntax:
 172
 173 **current-state** => _world-state_
 174
 175 #### Arguments and Values:
 176
 177 _world-state_---A list, the current state of the whole world
 178
 179 #### Description:
 180
 181 Dumps out the state of the world.
 182
 183 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.
 184
 185 Currently this only dumps out turtle and patch information.
 186
 187 This is called _current-state_ because export-world is an actual primitive used by NetLogo.
 188
 189 ## Function **DIE**
 190
 191 #### Syntax:
 192
 193 **die** => _result_
 194
 195 ```result::= :undefined```
 196
 197 #### Description:
 198
 199 The turtle or link dies
 200
 201 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.
 202
 203 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#die
 204
 205 ## Function **DISPLAY**
 206
 207 #### Syntax:
 208
 209 **display** => _result_
 210
 211 ```result::= :undefined```
 212
 213 #### Description:
 214
 215 As of yet, this does nothing.  A placeholder method for forced dipslay updates from the engine.
 216
 217 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#display
 218
 219 ## Function **EXPORT-WORLD**
 220
 221 #### Syntax:
 222
 223 **export-world** => _world-csv_
 224
 225 #### Arguments and Values:
 226
 227 _world-csv_---A string, the csv of the world
 228
 229 #### Description:
 230
 231 Dumps out a csv matching NetLogo's export world.
 232
 233 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.
 234
 235 ## Function **FORWARD**
 236
 237 #### Syntax:
 238
 239 **forward** _n_ => _result_
 240
 241 ```result::= :undefined```
 242
 243 #### Arguments and Values:
 244
 245 _n_---a double, the amount the turtle moves forward
 246
 247 #### Description:
 248
 249 Moves the current turtle forward _n_ steps, one step at a time.
 250
 251 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.
 252
 253 If the current agent is not a turtle, it raises an error.
 254
 255 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#forward
 256
 257 ## Function **HATCH**
 258
 259 #### Syntax:
 260
 261 **hatch** _n_ _&optional_ _fn_ => _result_
 262
 263 ```result::= :undefined```
 264
 265 #### Arguments and Values:
 266
 267 _n_---an integer, the numbers of turtles to hatch
 268 _fn_---A function, applied to each turtle after creation
 269
 270 #### Description:
 271
 272 The turtle in *self* creates _n_ new turtles. Each new turtle inherits of all its variables, including its location, from self.
 273
 274 If F_n_ is supplied, the new turtles immediately run it.
 275
 276 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#hatch
 277
 278 ## Function **LOOKUP-COLOR**
 279
 280 #### Syntax:
 281
 282 **lookup-color** _color_ => _color-number_
 283
 284 #### Arguments and Values:
 285
 286 _color_---a symbol representing a color
 287 _color-number_---the NetLogo color integer
 288
 289 #### Description:
 290
 291 Returns the number used to represent colors in NetLogo.
 292
 293 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#Constants
 294
 295 ## Function **OF**
 296
 297 #### Syntax:
 298
 299 **of** _fn_ _agent-or-agentset_ => _result_
 300
 301 ```agent-or-agentset::= agent | agentset```
 302 ```result::= result-list | result-value```
 303
 304 #### Arguments and Values:
 305
 306 _fn_---a function, run on each agent
 307 _agent_---a NetLogo agent
 308 _agentset_---a NetLogo agentset
 309 _result-list_---a list
 310 _result-value_---a single value
 311
 312 #### Description:
 313
 314 _of_ is equivalent to of in NetLogo.
 315
 316 The specified _agent_SET or _agent_ runs the given _fn_.  In the case of an _agent_SET, 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.
 317
 318 _result_-LIST is returned when the input is an _agent_SET, but _result_-VALUE is returned when only passed an _agent_.
 319
 320 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#of
 321
 322 ## Function **ONE-OF**
 323
 324 #### Syntax:
 325
 326 **one-of** _list-or-agentset_ => _result_
 327
 328 ```list-or-agentset::= list | agentset```
 329 ```result::= random-value | random-agent | :nobody```
 330
 331 #### Arguments and Values:
 332
 333 _list_---A list
 334 _agentset_---An agent set
 335 _random-value_---a value in _list_
 336 _random-agent_---an agent if _agentset_ is non empty
 337
 338 #### Description:
 339
 340 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.
 341
 342 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#one-of
 343
 344 ## Function **PATCHES**
 345
 346 #### Syntax:
 347
 348 **patches** => _all-patches_
 349
 350 #### Arguments and Values:
 351
 352 _all-patches_---a NetLogo agentset, all patches
 353
 354 #### Description:
 355
 356 Reports the agentset consisting of all the patches.
 357
 358 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.
 359
 360 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#patches
 361
 362 ## Function **RANDOM**
 363
 364 #### Syntax:
 365
 366 **random** _n_ => _random-number_
 367
 368 #### Arguments and Values:
 369
 370 _n_---an integer, the upper bound of the random
 371 _random-number_---an integer, the random result
 372
 373 #### Description:
 374
 375 Returns a random number strictly closer to zero than _n_.
 376
 377 If number is positive, returns a random integer greater than or equal to 0, but strictly less than number.
 378
 379 If number is negative, returns a random integer less than or equal to 0, but strictly greater than number.
 380
 381 If number is zero, the result is always 0.
 382
 383 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random
 384
 385 ## Function **RANDOM-FLOAT**
 386
 387 #### Syntax:
 388
 389 **random-float** _n_ => _random-number_
 390
 391 #### Arguments and Values:
 392
 393 _n_---a double, the upper bound of the random float
 394 _random-number_---a double, the random result
 395
 396 #### Description:
 397
 398 Returns a random number strictly closer to zero than _n_.
 399
 400 If number is positive, returns a random floating point number greater than or equal to 0 but strictly less than number.
 401
 402 If number is negative, returns a random floating point number less than or equal to 0, but strictly greater than number.
 403
 404 If number is zero, the result is always 0.
 405
 406 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random-float
 407
 408 ## Function **RANDOM-XCOR**
 409
 410 #### Syntax:
 411
 412 **random-xcor** => _random-number_
 413
 414 #### Arguments and Values:
 415
 416 _random-number_---a float, the random result
 417
 418 #### Description:
 419
 420 Returns a random floating point number in the allowable range of turtle coordinates along the x axis.
 421
 422 These range from min-pxcor - 0.5 (inclusive) to max-pxcor + 0.5 (exclusive)
 423
 424 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random-cor
 425
 426 ## Function **RANDOM-YCOR**
 427
 428 #### Syntax:
 429
 430 **random-ycor** => _random-number_
 431
 432 #### Arguments and Values:
 433
 434 _random-number_---a float, the random result
 435
 436 #### Description:
 437
 438 Returns a random floating point number in the allowable range of turtle coordinates along the y axis.
 439
 440 These range from min-pycor - 0.5 (inclusive) to max-pycor + 0.5 (exclusive)
 441
 442 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#random-cor
 443
 444 ## Function **RESET-TICKS**
 445
 446 #### Syntax:
 447
 448 **reset-ticks** => _result_
 449
 450 ```result::= :undefined```
 451
 452 #### Description:
 453
 454 Resets the tick counter to zero, sets up all plots, then updates all plots.
 455
 456 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#reset-ticks
 457
 458 ## Function **SET-DEFAULT-SHAPE**
 459
 460 #### Syntax:
 461
 462 **set-default-shape** _breed_ _shape_ => _result_
 463
 464 ```result::= :undefined```
 465
 466 #### Arguments and Values:
 467
 468 _breed_---a valid breed
 469 _shape_---a string
 470
 471 #### Description:
 472
 473 Specifies a default initial shape for a _breed_. When a turtle, or it changes breeds, its shape is set to the given shape.
 474
 475 _set-default-shape_ doesn't affect existing agents, only agents you create afterwards.
 476
 477 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#set-default-shape
 478
 479 ## Function **SETXY**
 480
 481 #### Syntax:
 482
 483 **setxy** _x_ _y_ => _result_
 484
 485 ```result::= :undefined```
 486
 487 #### Arguments and Values:
 488
 489 _x_---a double
 490 _y_---a double
 491
 492 #### Description:
 493
 494 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.
 495
 496 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#setxy
 497
 498 ## Function **SHOW**
 499
 500 #### Syntax:
 501
 502 **show** _value_ => _result_
 503
 504 ```result::= :undefined```
 505
 506 #### Arguments and Values:
 507
 508 _value_---a NetLogo value
 509
 510 #### Description:
 511
 512 A command that prints the given NetLogo value to the command center.
 513
 514 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#show
 515
 516 ## Function **STOP**
 517
 518 #### Syntax:
 519
 520 **stop** => _result_
 521
 522 ```result::= :undefined```
 523
 524 #### Description:
 525
 526 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.
 527
 528 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#stop
 529
 530 ## Function **TICK**
 531
 532 #### Syntax:
 533
 534 **tick** => _result_
 535
 536 ```result::= :undefined```
 537
 538 #### Description:
 539
 540 Advances the tick counter by one and updates all plots.
 541
 542 If the tick counter has not been started yet with reset-ticks, an error results.
 543
 544 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#tick
 545
 546 ## Function **TICKS**
 547
 548 #### Syntax:
 549
 550 **ticks** => _current-ticks_
 551
 552 #### Arguments and Values:
 553
 554 _current-ticks_---A positiv double, representing the current number of ticks
 555
 556 #### Description:
 557
 558 Reports the current value of the tick counter. The result is always a number and never negative.
 559
 560 If the tick counter has not been started yet with reset-ticks, an error results.
 561
 562 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#ticks
 563
 564 ## Function **TURN-LEFT**
 565
 566 #### Syntax:
 567
 568 **turn-left** _n_ => _result_
 569
 570 ```result::= :undefined```
 571
 572 #### Arguments and Values:
 573
 574 _n_---a double, the amount the turtle turns
 575
 576 #### Description:
 577
 578 The turtle turns left by number degrees. (If number is negative, it turns right.)
 579
 580 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#right
 581
 582 ## Function **TURN-RIGHT**
 583
 584 #### Syntax:
 585
 586 **turn-right** _n_ => _result_
 587
 588 ```result::= :undefined```
 589
 590 #### Arguments and Values:
 591
 592 _n_---a double, the amount the turtle turns
 593
 594 #### Description:
 595
 596 The turtle turns right by number degrees. (If number is negative, it turns left.)
 597
 598 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#right
 599
 600 ## Function **TURTLES**
 601
 602 #### Syntax:
 603
 604 **turtles** => _all-turtles_
 605
 606 #### Arguments and Values:
 607
 608 _all-turtles_---a NetLogo agentset, all turtles
 609
 610 #### Description:
 611
 612 Reports the agentset consisting of all the turtles.
 613
 614 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.
 615
 616 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#turtles
 617
 618 ## Function **TURTLES-HERE**
 619
 620 #### Syntax:
 621
 622 **turtles-here** => _turtles_
 623
 624 #### Arguments and Values:
 625
 626 _turtles_---an agentset
 627
 628 #### Description:
 629
 630 Returns the agentset consisting of all the turtles sharing the patch with the agent in by *self*
 631
 632 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#turtles-here
 633
 634 ## Function **WITH**
 635
 636 #### Syntax:
 637
 638 **with** _agentset_ _fn_ => _result-agentset_
 639
 640 #### Arguments and Values:
 641
 642 _agentset_---a NetLogo agentset
 643 _fn_---a boolean function, run on each agent to determine if included
 644 _result-agentset_---an agentset of valid agents
 645
 646 #### Description:
 647
 648 _with_ is equivalent to with in NetLogo.
 649
 650 Returns a new agentset containing only those agents that reported true when _fn_ is called.
 651
 652 See http://ccl.northwestern.edu/netlogo/docs/dictionary.html#with
 653
 654 ## Function **WITH-STOP-HANDLER**
 655
 656 #### Syntax:
 657
 658 **with-stop-handler** _&rest_ _forms_ => _handled-form_
 659
 660 #### Arguments and Values:
 661
 662 _forms_---body to be handled
 663 _handled-form_---body with handling
 664
 665 #### Description:
 666
 667 _with-stop-handler_ is a convenience macro to handle when programs issue a stop condition.  When one does, a simple :stop is returned.