NetTango Builder tutorial
This tutorial will walk you through modifying an existing NetLogo model to combine it with NetTango blocks to create an interactive page. For this sample, we'll be using the Slime model from the NetLogo models library.
First things first if the model is new to us, we want to look at the model, play with it, read up on it in the Info tab, and decide what parts of it we want to turn into blocks. While it's possible to try to convert a model's code line-by-line to blocks, using such fine-grained blocks is probably going to be confusing and difficult for users to use.
The slime model isn't too complex, we can see it only has a few widgets, and the code is less than 50 lines long, including comments.
patches-own [chemical]
to setup
clear-all
create-turtles population
[ set color red
set size 2 ;; easier to see
setxy random-xcor random-ycor ]
ask patches [ set chemical 0 ]
reset-ticks
end
to go
ask turtles
[ if chemical > sniff-threshold ;; ignore pheromone unless there's enough here
[ turn-toward-chemical ]
rt random-float wiggle-angle - random-float wiggle-angle + wiggle-bias
fd 1
set chemical chemical + 2 ] ;; drop chemical onto patch
diffuse chemical 1 ;; diffuse chemical to neighboring patches
ask patches
[ set chemical chemical * 0.9 ;; evaporate chemical
set pcolor scale-color green chemical 0.1 3 ] ;; update display of chemical concentration
tick
end
to turn-toward-chemical ;; turtle procedure
;; examine the patch ahead of you and two nearby patches;
;; turn in the direction of greatest chemical
let ahead [chemical] of patch-ahead 1
let myright [chemical] of patch-right-and-ahead sniff-angle 1
let myleft [chemical] of patch-left-and-ahead sniff-angle 1
ifelse (myright >= ahead) and (myright >= myleft)
[ rt sniff-angle ]
[ if myleft >= ahead
[ lt sniff-angle ] ]
;; default: don't turn
end
; Copyright 1997 Uri Wilensky.
; See Info tab for full copyright and license.For this tutorial, what we think is the core of this model is the idea that the slimes move randomly unless they sniff a strong enough chemical scent, in which case they turn towards the strongest nearby scent. This behavior is enough to make the self-organizing slime clumps, so it's worth distilling it out into blocks. Our goal will be to replace most of the code in the ask turtles [ ... ] section of the go procedure.
to go
ask turtles
[ if chemical > sniff-threshold ;; ignore pheromone unless there's enough here
[ turn-toward-chemical ]
rt random-float wiggle-angle - random-float wiggle-angle + wiggle-bias
fd 1
set chemical chemical + 2 ] ;; drop chemical onto patch
diffuse chemical 1 ;; diffuse chemical to neighboring patches
ask patches
[ set chemical chemical * 0.9 ;; evaporate chemical
set pcolor scale-color green chemical 0.1 3 ] ;; update display of chemical concentration
tick
endNow, below the model, we can click Add New Block Space and enter a name instead of Block Space 1, how about Slime Actions?
Procedures are the links between the NetLogo model and the NetTango code. All blocks in NetTango must be placed under a procedure, and NetTango will generate the NetLogo code for those procedures. We then just modify the NetLogo code to call out to those procedures as appropriate and we should be in business.
In our Slime Actions block space we can clock Add Block > Basics > Procedure. The resulting popup let's us make modifications to our block. All we'll change here is the Display Name to slime actions and the Code Format to to slime-actions. Click Add New Block when done, and we should see slime actions in our block space, and we can drag it onto the "live" area.
One thing to notice is that the NetLogo model now requires a recompile, since it saw the NetTango code changed. If we hit the Recompile button on the model, we'll see in the code tab at the bottom our slime-actions procedure has been injected into the model code, as below. We should be able to setup and run the model without issues. It's always good to test as you go, making sure things are working!
; --- NETTANGO BEGIN ---
; Code for Slime Actions
to slime-actions
end
; --- NETTANGO END ---Now we'll actually inject our slime-actions NetTango procedure into the NetLogo model. Replace all the code in the ask turtles [ ... ] section of the go procedure with ask turtles [ slime-actions ]. It should look as below. Be careful with [ and ] brackets, if an extra one gets left behind you'll probably get some weird error messages. Once you've finished the change, Recompile your code and run setup and go to see some turtles sit around and do nothing! Again, we're testing every little change to keep fixing things easy if something isn't correct.
to go
ask turtles [ slime-actions ]
diffuse chemical 1 ;; diffuse chemical to neighboring patches
ask patches
[ set chemical chemical * 0.9 ;; evaporate chemical
set pcolor scale-color green chemical 0.1 3 ] ;; update display of chemical concentration
tick
endOur slimes are sitting around, doing nothing at all! Let's add a couple of commands in NetTango so they can actually move around. Here we can use some pre-defined NetTango blocks to save us some time.
Again, in our Slime Actions block space we can clock Add Block > Turtle Commands > Forward. You can check out the predefined settings in the block definition window. Notice the Display Name which will be given to the block in the NetTango UI, the Type which defines this block as a Command (a single chunk of NetLogo code to insert into a procedure), and the Code Format, which in this cases uses the fd {0} to denote a parameter that the user can change in the block. The steps parameter value will be substituted in for the {0} when the NetLogo code is compiled.
We should stop and test, checking that if we add our forward block to the slime actions block in the NetTango space, then Recompile, setup, and go, that our slimes should now move forward with turning or dropping any chemical.
Adding the wiggle command isn't too hard as we can use another pre-defined block starting point. In our Slime Actions block space we can clock Add Block > Turtle Commands > Wiggle. Take a look at the code and then Add New Block when ready. Test it out, adding it to our slime actions block chain, Recompile, setup, and go. We should see our slimes moving forward, and wiggling a little left and right each tick.
But wait! There is a little more work to do here. The existing model used wiggle-angle and wiggle-bias widgets to control the amount of slime turning. the wiggle block comes with an angle by default, but the bias we do not have. So let's add a bias! Slime Actions block space, Modify Block > wiggle > edit, and we'll see the block editor. Now we want to Add Parameter, give it a Name of bias, Type of range, a Unit label of ° (can copy from here or the existing parameter), a Default of 0, a Min of -45, a Max of 45, and a Step size of 5. See the picture for more.
That's enough to have a parameter to play with in the UI, but it doesn't put the value in code anywhere. For that we have to change the Code Format to left (random {0} - ({0} / 2) + {1}), where {1} will reference our new bias parameter. Once done, we're ready to test again, so Recompile, setup, and go. Set the bias to a large negative number and confirm our slimes mostly wiggle to one direction.
Here is what our block space currently looks like. You can grab the model at this point from here, too (might need to right-click and save-as to download). Just use Import NetTango JSON to load it up.
Now we want another turtle command, but this one is totally custom. In our Slime Actions block space we can clock Add Block > Basics > Command. Let's set the Display name to drop chemical, and set the Code Format to set chemical chemical + 2. Add New Block and then test it as we used to now. We should have slimes that move forward, wiggle, and drop a little green chemical that diffuses out.
In our Slime Actions block space we can clock Add Block > Basics > if. Set the Display Name to if chemical strength, and the Code Format to if chemical > {0}. That {0} will be the sniff-threshold widget replacement - so add a new parameter, Name of amount, Type of range, leave Unit label blank, Default of 1, a Min of 0, a Max of 1, and a Step size of 1. There isn't much to test here, but go ahead and add the if block to our chain and Recompile the model code to make sure everything is working.
We're almost done! One more custom command. In our Slime Actions block space we can clock Add Block > Basics > Command. Let's set the Display name to turn toward chemical, and set the Code Format to turn-toward-chemical. Add New Block once done. We can put this block inside our if chemical stregth block to test it. If everything is working right, we should now have a block-based model that duplicates the code-based functionality.
One more step is to clean-up the model UI. We no longer need some of the widgets, so we can click the Mode: Interactive lock icon on the model to enter Mode: Authoring. Then right click and delete the wiggle-bias, wiggle-angle, and sniff-threshold widgets.
But wait! What about the sniff-angle widget? We didn't recreate it's functionality! Let's go ahead and delete the sniff-angle widget anyway. We'll get a compile error, which is expected, since we deleted the widget without changing the code that uses it. Our idea for adding sniff-angle back in is to make it a parameter for the turn toward chemical block and procedure.
Start in the NetLogo Code of the model, change the to turn-toward-chemical ;; turtle procedure procedure definition to take a parameter, to turn-toward-chemical [sniff-angle] ;; turtle procedure. If you try to recompile now you'll get a different error than before. Close the NetLogo Code, and go back to the NetTango block spaces.
In the Slime Actions block space, click Modify Blocks > turn toward chemical > edit. First, edit the Code Format to be turn-toward-chemical {0}. Then Add Parameter with: Name of sniff angle, Type of range, Unit label of °, Default of 45, a Min of 0, a Max of 180, and a Step size of 5. Update Block when complete.
You can take a minute to play around with the checkboxes to hide various components (but the defaults are fine). Hit Files > Export NetTango Page to get a stand-alone HTML page that you can post wherever you like to play around with the slimes using blocks.
Don't forget to also hit Files > Export standalone HTML file. This gives you a file you can re-import into the NetTango builder later on using Files > Import NetTango JSON file if you have other changes you wish to make. You can also post this file online and hot-link to it for usage without exporting he standalone HTLM file.
Here is the final NetTango builder code (might need to right click and save as to download as a file).
And that's that! This is a relatively simple model, but hopefully these steps give you ideas about how to convert other models to blocks. The big takeaways are:
- The use of the procedure to hook the NetTango blocks into the NetLogo model.
- The choice of how granular to make the blocks - just coarse enough to get the core idea of the model through.
- The contextualization of what used to be widget sliders. Now we see in the code where those values are used.