Introduction to the NetTango builder
Starting with an existing NetLogo model

 

NetTango is a domain-blocks-based interface for the NetLogo agent-based modeling environment.

There are three possible ways to begin a project with the NetTango Builder:

  1. Starting with a blank project
  2. Starting with an existing model from the NetLogo Models Library.
  3. Starting with an existing model by uploading from your computer.

In this step-by-step tutorial, we are going to explain how to start with an existing model from the NetLogo Models Library (#2). We are going to design a blocks-based programming interface for the NetLogo Ants model. Along the way, we are going to explain each component of the NetTango Builder in detail. We are also going to cover the relevant concepts, interface tools, and alternative design choices.

 

If you would like to see the final version of the blocks-based Ant model programming environment, click here .

If you would like to download the completed NetTango builder project file, click here .

Use a compatible browser

We advise you to run the NetTango Builder on a modern browser (e.g., Chrome, Safari, Firefox) and keep your browser up-to-date.


 
 
 

1. Preparing our project

 
1a. Loading the base model
 

We are going to work with a model that is already in the NetLogo Models Library, so we will click the "Files " button below the embedded blank NetLogo model. A context menu will appear. There, we will click the "Choose NetLogo library model " item. This will show a dialog where we can pick a model from the list of the library models or we can use the search box. We will write ants   to the search box and click the top item. Then we will click the "Load the model " button. This will load the Ants model to our project.

If you are going to use one of your own models, you should use the "Import NetLogo Model " item from the same menu. The file you provide should be a NetLogo Desktop file with the .nlogo extension. NetLogo web files (.html) are not currently supported.

 

The NetTango builder has auto-save functionality built-in. If you make changes to your project, you can safely close the browser window. The latest version of your model will be there when you open the NetTango builder again.

You can also save your project as an external file with the .ntjson extension by clicking the "Files " button and then clicking the "Export NetTango Project " item. We advise you to do so only after making significant progress with your project because each time you click this button, the NetTango builder will generate a brand new file, which might make it difficult to track versions.

You can load an existing ntjson project file by clicking clicking the "Files " button and then clicking the "Import NetTango JSON File " item.

 
Make a plan

It is advised to have a plan at hand before creating new projects with the NetTango builder. Here are some of the considerations to keep in mind:

  • Which agents are going to be programmable with the blocks-based interface?
  • What kinds of behavior will the users be programming?
  • How will you break or combine each behavior into easily recognizeable code blocks?
  • Which domain-specific words are best suited for each code block?

We advise against one-to-one conversion of NetLogo code to NetTango blocks and encourage the use of more domain-specific terms. If you would like to see examples, please scroll down to the Example NetTango Projects section.

 
1b. Block Spaces

The next step in our project is to create two "Block Spaces". Each block space in NetTango is a self-contained widget that has its own blocks library. There can be as many block spaces in a NetTango project as needed. There can be just one, as well. The block spaces can simplify the programming environment in various ways. For example, you can use separate block spaces for each agent breed. Here, we will use one block space for the "setup" procedure and another for the "go" procedure for our ants model because we only have one agent breed.

Create two new block spaces by clicking the "Add Block Space " button twice.

Rename your block spaces as Setup   and Go   .

The names of the block spaces do not have any effect in the code execution. They are solely for users to distinguish the spaces from each other. Notice the change in the NetLogo Code widget below the block spaces. You willl see two comments as ; Code for Setup and ; Code for Go. Once we add our code-blocks and assemble them as algorithms, the corresponding NetLogo code will appear in this area.

 

 
 
 

2. Creating the Setup blocks

The setup procedure in the Ants model does the following actions:

  1. Clear all and reset the ticks counter.
  2. Set the default shape of the turtles as "bug".
  3. Create a nest at the center of the model.
  4. Create the ants at the center of the model.
  5. Create the piles of food away from the nest.

We are going to create a corresponding code-block for the last three of these actions. As a design decision, the first two actions will be hard coded in our model. We are not going to create blocks for them.


 
2a. Creating a procedure block

We will get started with creating a procedure block. Each block space needs at least one procedure to encapsulate the blocks-based algorithms assembled inside.

We want our users to be able to manipulate the function of the button. To do so, we will create a new procedure block called "Setup".

Click the "Add Block " button under the title of the "Setup" space. A pop-up menu will appear. Navigate to the "Basics " section and then click to the "Procedure " item.

 

A pop-up window titled "Setup Block" will appear on the screen.

1. Change the "Display Name" to Setup   .

2. Notice that the "Limit" is pre-defined as 1. This means that the users can only drag one setup block to their coding area. It is important to keep the limit as 1 because we cannot have multiple procedures with the same name in NetLogo.

3. Change the contents of the "NetLogo code format" to "to blocks-setup". When the user drags our procedure block to the coding area, a procedure named "blocks-setup" will be added to the end of the embedded NetLogo model. Because this is a procedure block, the NetTango builder will also add an "end" to the code. Any blocks that we attach to this procedure block will be pasted within the "blocks-setup" procedure.

 

Click the "Add New Block " button at the bottom.

Notice that when you drag the "setup" block to the coding area (white background), the original block on the right will be disabled. This indicates that the user has ran out of the limit.

Also notice that the NetLogo code area below the blocks will show an empty blocks-setup procedure once you drag the block to the coding area.

 
Take advantage of the visual affordances of blocks-based programming

The NetTango builder provides a number of tools to change the appearance of the blocks, which can help us design blocks that are easier to learn. You can use colors, font formatting, and even emojis to indicate functionality, category, or other important distinctions. You can modify the visual properties of blocks by clicking the arrow next to the "Blocks Styles " section in the "Setup Block" screen.

Note: By default, the NetTango builder provides built-in colors for block types (e.g., command blocks are gray and procedure blocks are dark-red).

 
 
 
2b. Creating a command block

Now that we have a procedure to fill-in, we are going to start creating our command blocks. Our first block will be "Create ants".

Click the "Add Block " button under the title of the "Setup" space. A pop-up menu will appear. Navigate to the "Basics " section and then click to the "Procedure " item.

 

A pop-up window titled "Setup Block" will appear on the screen.

1. Change the "Display Name" to Create ants   .

2. Change the "NetLogo code format" to "create-turtles {0}". The expression {0} means that the value of our very first parameter will be pasted here by the NetTango engine.

3. Click the "Add Parameter " button below the colors. A new section with the title "Parameter 0" with some options will appear below the button.

4. Change the "Display name" to how many?   . The display name is shown to the users but it does not have any impact on the actual NetLogo code.

5. Change the "Type" to "range ". This will allow us to set a minimum (7) and a maximum (8) value for the parameter.

6. Change the "Default" to 125   , which is the default value for this parameter in the Ants model.

7. Leave the "Min" as 0   . This will allow us to set a minimum (7) and a maximum (8) value for the parameter.

8. Change the "Max" to 300   .

 

Click the "Add New Block " button at the bottom.

Notice that the "Limit" option is left as blank for command blocks. This means that the users can drag as many instances of this block to their coding area as they wish.

Try your new block by dragging multiple copies to the coding area and attaching them to the Setup procedure.

Notice that only the NetLogo code of the blocks that are attached to the Setup procedure will appear in the NetLogo Code widget below the block-based programming area. Also notice that even though we have a "Create ants 300" block in the space, it is not reflected in the code because the blocks that are not attached to any procedure are omitted by the NetTango compiler.


 
2c. Connecting the base model

We created our 4 code blocks for the Setup space. When we drag the code blocks and assemble them as algorithms, we can see that the NetTango builder is generating the corresponding NetLogo code.

However, if we recompile our model and click the button, we will notice that our model still runs the old code. This is because we need to modify our model to specifically run the "blocks-setup" procedure.

 
 

Doing so is easy:

1. Scroll up and click the "NetLogo Code " tab

2. Locate the "to setup" procedure and remove the lines 16-19 (shown below) and replace them with a single line of code "blocks-setup"


          create-turtles population
          [ set size 2         ;; easier to see
            set color red  ]   ;; red = not carrying food
          setup-patches
                                    

3. Click the "Recompile Code " button at the top of the NetLogo Code tab and close the NetLogo Code tab altogether.

 

Congratulations! We are now halfway done. If you followed each step of this tutorial so far, you should now be able to modify the behavior of the setup button of the Ants model with code-blocks.


 
2d. Creating the rest of the Setup blocks

Now that you created two blocks, it should be rather straightfoward to create the rest of the Setup blocks without step-by-step instructions. Refer to the information below to create the remaining blocks:

 

Create a nest:

Display name Create a nest
NetLogo code format  

    ask patches [
        set nest? (distancexy 0 0) < {0}  
        if nest? [ set pcolor violet]  
        set nest-scent 200 - distancexy 0 0
    ]
Parameter: Diameter Type: range
Default: 5
Min: 1
Max: 10
 
 

Create a food pile:

Display name Create a food pile
NetLogo code format  

    ask patches with [distancexy {0} {1} < 5][ 
        set food one-of [1 2]
        set pcolor {P0}
    ]
Parameter: X Coordinate Type: range
Default: 10
Min: -25
Max: 25
Parameter: Y Coordinate Type: range
Default: 10
Min: -25
Max: 25
Property: Color Type: select
Default: Cyan

Options:
Actual Value Display Value
Cyan Cyan
Sky Sky
Blue Blue
Yellow Yellow
Red Red
 

 
 
 

3. Creating the Go blocks

The go procedure in the Ants model is fairly more complex compared to the setup procedure. It has the following rules followed by each ant autonomously:

In addition to individual ant behavior, there is also a chemical diffusion & (i.e., pheromone evaporation) logic in the Go procedure. We are going to keep those parts hard-coded in our NetTango environment as a design decision in this tutorial.

 

 
3a. Creating a procedure block

As usual, we will get started with creating our procedure block for the Go space.

 

Click the "Add Block " button under the title of the "Go" space. A pop-up menu will appear. Navigate to the "Basics " section and then click to the "Procedure " item.

 

A pop-up window titled "Go Block" will appear on the screen.

1. Change the "Display Name" to Go   .

2. Leave the "Limit" as 1.

3. Change the contents of the "NetLogo code format" to "to blocks-go".

 

Click the "Add New Block " button at the bottom.

 

 
3b. Creating an "ask" block for agent rules

As our each ant-agent will follow their rules independently, we need an "ask" block. The wording of our ask block may vary based on context. Here, we are going to create an "Each ant" block. Some alternatives may be "Ants do", "Ant actions", or even simple emojis such as "🐜 🐜 🐜 🐜 🐜".

 

Click the "Add Block " button under the title of the "Go" space. A pop-up menu will appear. Navigate to the "Control Blocks " section and then click to the "Ask Turtles " item.

 

A pop-up window titled "Go Block" will appear on the screen.

1. Change the "Display Name" to Each ant   .

2. Set the "Limit" as 1.  

3. Leave the contents of the "NetLogo code format" as "ask turtles".

Click the "Add New Block " button at the bottom.

 

 
3c. Creating two "if" blocks for conditionals & branching

Our ants will do different things whether they are carrying food or not. One of the strategies would be to divide the logic into two separate procedures. Another strategy would be to create two separate spaces. Here, we will stick to a third, more crude/straightforward approach. We will provide our users two if blocks. We could do the same with a combined "ifelse" block, as well, but we will use two separate blocks for simplicity.

 

Click the "Add Block " button under the title of the "Go" space. A pop-up menu will appear. Navigate to the "Basics " section and then click to the "ifelse " item.

 

A pop-up window titled "Go Block" will appear on the screen.

1. Change the "Display Name" to If I am not carrying food   .

2. Change the contents of the "NetLogo code format" to "if color = red".

Click the "Add New Block " button at the bottom.

 
 

Now we will duplicate our "if I am not carrying food" block by clicking the "Modify Block " button under the title of the "Go" space. A pop-up menu will appear. Navigate to the "If I am not carrying food " item and then click to the "duplicate " item at the bottom of this list.

You will have an exactly identical block appearing at the bottom of the blocks list. Now, we will edit the second of our "If I am not carrying food" blocks to an "If I am carrying food" block. To do so, click the "Modify Block " button under the title of the "Go" space. A pop-up menu will appear. Navigate to the second "If I am not carrying food " item and then click to the "Edit " item.

 

A pop-up window titled "Go Block" will appear on the screen.

1. Change the "Display Name" to If I am carrying food   .

2. Change the contents of the "NetLogo code format" to "if color != red".

Click the "Update Block " button at the bottom.

 
 

 
3d. Connecting the base model

We created 4 code blocks for the Go space so far. When we drag the code blocks and assemble them as algorithms, we can see that the NetTango builder is generating the corresponding NetLogo code.

However, if we recompile our model and click the button, we will once again notice that our model still runs the old code. We need to modify our model to specifically run the "blocks-go" procedure.

 
 

1. Scroll up and click the "NetLogo Code " tab

2. Locate the "to go" procedure and remove the highlighted lines (69-75) of code below and replace them with a single line of code "blocks-go"


                                    
          ask turtles
          [ if who >= ticks [ stop ] ;; delay initial departure
            ifelse color = red
            [ look-for-food  ]       ;; not carrying food? look for it
            [ return-to-nest ]       ;; carrying food? take it back to nest
            wiggle
            fd 1 ]
                                    

Now, you can click the "Recompile Code " button at the top of the NetLogo Code tab and close the NetLogo Code tab altogether.

 

Congratulations! We are now halfway done with creating our Go blocks. If you followed each step of this tutorial so far, you should now be able to modify the go procedure of the Ants model with code-blocks as shown below.

 
 
3e. Creating the rest of the Go blocks

Now we can finish building our NetTango Ants modeling environment by creating our command blocks. As this is a repetitive process, once again we will provide you with information about each block but we will not provide step-by-step instructions.

 

Turn around:

Display name Turn around
NetLogo code format  

    right 180
 
 

Pick food:

Display name Pick food
NetLogo code format  

    if food > 0 [
      set food food - 1
      set color orange + 1
    ]
 
 

Drop food:

Display name Drop food
NetLogo code format  

    set color red
 
 

Drop pheromone chemical:

Display name Drop pheromone
NetLogo code format  

    set chemical chemical + 60 
 
 

Turn towards pheromone smell:

Display name Turn towards pheromone smell
NetLogo code format  

    if (chemical >= 0.05) and (chemical < 2) [ 
        uphill-chemical 
    ] 
 
 

Turn towards nest smell:

Display name Turn towards nest smell
NetLogo code format  

    uphill-nest-scent 
 
 

Wiggle:

Display name Wiggle
NetLogo code format  

    right random 40
    left random 40
    if not can-move? 1 [ rt 180 ]
 
 

Move forward:

Display name Move forward
NetLogo code format  

    forward 1
 
 
 

 
 
Wrapping up

Congratulations! You have created your very first NetTango project. By now, you should have a fully functional domain-blocks-based environment for the NetLogo Ants model.

In case you did not follow along but skimmed the tutorial and you would like to test out the finished project, you can test the finished project with the following link:

Blocks based Ants modeling environment (opens a new window)

You can also download the finished project file with the following link:

Project file

 
 

If you would like to preview and debug your project at each point during the process, you can click the "Files " button below the NetLogo model and then clicking the "Preview Standalone HTML page " item.

 

Once you finished your project and it is ready for deployement, you can save it as an .html file by clicking the "Files " button below the NetLogo model and then clicking the "Export Standalone HTML File " item.

 

 
 
Example projects

The NetTango builder has an embedded example project if you would like to quickly tinker with a pre-built project or if it is intimidating to start with an empty project.

To access the embedded example project, scroll to the end of the page and click the "Load WSP Testing Defaults " button. Keep in mind that this will erase your previous work without a prompt. Make sure to export your existing project if necessary.

 
 

 

If you would like to get your hands on more example projects, here are a few others created by our research team members:

 

Rolypollies

Download the Project file

Demo the Rollypollies environment (opens a new window)

The Rollypolies environment is developed by Sugat Dabholkar and Teresa Granito.

 

Gas Particle Sandbox with Phenomenological Programming

Download the Project file

Demo the Rollypollies environment (opens a new window)

The Gas Particle Sandbox with Phenomenological Programming environment is developed by Umit Aslan, Nicholas LaGrassa, Michael Horn & Uri Wilensky.