Introduction to NetTango: Creating a domains-blocks-based environment for the Ants Model

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:

Starting with a blank project
Starting with an existing model from the NetLogo Models Library.
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 in the search box and click the top item ("Sample Models/Biology/Ants"). 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 separate or combine each behavior into easily recognizable 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 will 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:

Clear all and reset the ticks counter.
Set the default shape of the turtles as "bug".
Create a nest at the center of the model.
Create the ants at the center of the model.
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 the "new 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 the "empty command " 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 and a maximum 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 and a maximum 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 2 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 straightforward 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
Quote values in code: never-quote

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:

Am I carrying food (i.e., color = red)?
- No? Then, I will look for food:
  - If there is food here (on my patch):
    - I will pick up 1 food from the patch.
    - I will change my state to carrying food (color = orange).
    - I will turn 180 degrees.
  - If there is no food here:
    - I will smell the environment.
    - If I smell pheromone, I will turn towards the strongest smell.
- Yes? Then, I will return to the nest:
  - If I arrived at the nest:
    - I will change my state to "not carrying food" (i.e., color = orange).
    - I will turn around.
  - If I did not arrive at the nest, yet:
    - I will drop some chemical to the current patch.
    - I will turn towards the strongest nest smell.
I will wiggle a bit.
I will move forward 1 unit.

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 the "new 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".

4. Under " Which blocks are allowed to be added to this chain starter? " select "Allow blocks with at least one of the chosen tags". Then enter "ask ants" as a new tag name. This will be referenced when we create the next block, an "ask" block.

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

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

Since 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 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".

4. Add the tag "ask ants" which we first created in the "Go" procedure block. Now only this block can be placed directly beneath the "Go" procedure block.

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

Adding Tags

Add tags to your blocks to help group and organize them. Tags work with control clauses to restrict where blocks can be placed in a program, either for NetLogo syntactical correctness or for modeling purposes. In this tutorial, we only added a tag to the "Each ant" block for syntax purposes, making sure that the "Go" block could only accept that block. This helped prevent errors and ensure that all other blocks are contained within the "Each ant" block. For example, the "Move forward" block (see Step 3e) would create an error if it were outside the "Each ant" block and directly within the "Go" block.

Feel free to add more restrictions for design purposes. Say you wanted to make sure that the "Drop pheromone" block cannot be placed directly within the "Each ant" block and can only appear within an "if" block. You would have to add a tag to the "if" blocks and make sure the "Each ant" block can only accept blocks with that tag. Then only "if" blocks could be placed directly within the "Each ant" block, and "Drop pheromone" would have to be placed within an "if" block.

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 "Control Blocks " section and then click the "if " 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 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 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.

3e. Creating the rest of the Go blocks

Now we can finish building our NetTango Ants modeling environment by creating three additional if blocks and 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.

If there is food here:

Display name	If there is food here
NetLogo code format	`if food > 0`

If I am at the nest:

Display name	If I am at the nest
NetLogo code format	`if nest?`

If I am not at the nest:

Display name	If I am not at the nest
NetLogo code format	`if not nest?`

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 (feel free to also use this link to view the suggested block ordering):

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 deployment, 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.