Option Lists in AnyLogic

April 26th, 2019

There is a lesser known feature in AnyLogic that will allow you to build more structured models: Option Lists. I didn't use them for quite some time, but since I started, I deploy them in almost any model. In this article I will explain the use and benefits of this feature.

What is it?

Option List is a data type that restricts the possible values of a variable to a number of predefined choices. Sort of like a dropdown, that only allows you to set certain values.

If you are familiar with Java, you might be wondering that this sounds like Java Enums. That is because it is actually (almost) congruent to the AnyLogic Option List, which uses Java Enums in the background!

The advantage of the AnyLogic version: it offers a nice little GUI to define enums without the need for Java code. Also the Option Lists defined in AnyLogic can be shown and edited in the project structure tree.

How to define it?

In the AnyLogic Project tab, right click on any entry of your project, then select: New / Option List.

A window for defining the name of the option list, as well as the entries appears. By Java convention, the name should start with a capital letter ( Weekday), and the entries are in all caps (MONDAY).

That's it, now the Option List is ready to be used.

Why and when should I use it?

As the Java documentation puts it: You should use enum types any time you need to represent a fixed set of constants. For example the four directions (North, East, South, West), the seven weekdays (Monday, Tuesday, ...), the job levels in your company (Dishwasher, Cook, Boss). I think you get the idea.

Why store such information in an enum and not in a simple String? There are a handful of benefits:

You avoid redundancies and spelling errors by limiting the number of possible entries.

You can use it in switch-decisions:

switch (day) {
 case MONDAY:
      System.out.println("Monday");
      break;            
 default:
      System.out.println("Any other day");
      break;
}

You can easily iterate through the list of entries.

for (Weekday wd : Weekday.values()) {
 System.out.printf(wd);
}

You can use it as column type in the internal database. A dropdown will now suggest the possible options, entries that do not match any entry from the list will be rejected. Helps you to keep error free database entries. Also: When getting the values from the database you do not have to parse it anymore, AnyLogic can directly use it as a variable of the option list type.

You can use it as type for agent parameters. This way, when filling the parameters, you can make use of a radio button or dropdown choice selection, without the need to parse a string to the correct value.

Java Enums

As stated before, the AnyLogic Option List is nothing but a Java Enum. So when you do not need the AnyLogic GUI for it, or you want to avoid that it is visible in the project tree, you can alternatively define it directly in standard Java code.

public enum Type {NORTH,EAST,SOUTH,WEST}

The place to do so is in the properties of the agent where you want to use it, under Additional Class Code. If you want to use the Enum in the whole project, define it in the Additional Class Code section of your Main agent.

You can extend this definition with everything that is allowed in Java: field defintions, constructors, constants and methods. To show the principle, in our example I'll add a field for a single integer value to each enum entry, as well as a constructor and a get function:

public enum Type {
   NORTH(1),
   EAST(2),
   SOUTH(3),
   WEST(4);
   
   private int value;
   
   private Type(int value) {
      this.value = value;
   }
   public int getValue() {
      return value;
   }
}

The enum you defined in this way in Java code can be referenced in the agents where you defined it and all agents that are inside it. However, there is a restriction compared to the AnyLogic Option List: You will not be able to use this enums for the internal database, and they won't show up in the dropdown for the type defintion of variables. For the latter you can manually enter the Enum name in the field and still use it, for the database you cannot use it at all.

Conclusion

Option Lists make your life easier in AnyLogic. With them you can have a fixed set of options for a variable / database entry / parameter and do have to worry less about parsing, redundancy and spelling mistakes. Alternatively you can directly use Java Enums, which you can use more flexible, but have small restrictions in the integration to the other AnyLogic modules.