Creating custom material item types

If you have material items of different types in your model with specific custom attributes (width, length, processing cost, etc.) and you want them to look different at model runtime, you should create custom material item types and generate material items of different types in your model. This document describes how to do it.

 To define a custom material item type

  1. Drag the Material Item Type element from the Material Handling Library palette into the graphical editor.

  2. The New agent wizard will open. 
  3. On the first page of the wizard, specify Agent type name (e.g. Box). Click Next to proceed to the next step.

  1. Choose animation for the material item of this type. If you want the material items to be animated both in 2D and 3D, choose 3D and select 3D animation shape from the list below. Otherwise, select 2D and select the figure suiting your needs from the list. Alternatively you can choose None and define animation shape later.

  2. Here you can define the parameters of the material item. Click < add new... > and specify the parameter's name, its type and default value. To remove a parameter from the list, click the button. You can always add more parameters onto the material item diagram after you finish creating it. 

  1. Click Finish. AnyLogic will automatically open the diagram of the new material item type. You can find the animation figure in the axis origin.

Material item type properties

General

Name – The name of the material item type.
 Since AnyLogic generates Java class for each material item type, you should follow Java naming guidelines. Please start name with an uppercase letter. 

Ignore – If selected, the material item type is excluded from the model.

Parameters preview

Parameters preview properties are available only when this material item type has any parameters.
Here you can rearrange parameters of this material item. Material items of this type will list parameters in their property view in this well-defined order. 

Agent actions

On startup – Code to be executed after all agents throughout the whole model are constructed, connected, and initialized, and before anything else is done. This is a place for some additional initialization and starting agentt’s activities such as events. The order of execution of On startup code of different objects is not guaranteed.

On destroy – Code to be executed on destroying agent of this type (e.g. when the user terminates the experiment and the root object is destroyed, On destroy code of embedded objects are executed in some order).

On arrival to target destination – Code to be executed when the agent arrives at the destination.

On before step – Code to be executed for this agent before a step is taken in agent based model with synchronization. On before step actions are executed for agents in some deterministic order.

On step – Code to be executed for this agent on taking a step in agent based model with synchronizationOn step actions are executed for agents in some deterministic order.

Agent in flowcharts

Use in flowcharts as – Here you choose the role for this agent in the flowcharts. To enable using this agent as material item in the blocks of the AnyLogic Material Handling Library, leave the Material item option selected.

On enter flowchart block – Here you can write the code to be executed when this material item enters the flowchart.

On exit flowchart block – Here you can write the code to be executed when this material item exits the flowchart.

On seize resource – Here you can write the code to be executed when this material item seizes the resource while being in the flowchart.

On release resource – Here you can write the code to be executed when this material item releases the resource while being in the flowchart.

Dimensions and movement

Length – The length of the material item.

Width – The width of the material item.

Height  – The height of the material item.

Initial speed – [Visible if Space type is Continuous or GIS] The speed of the material item.

Rotate animation towards movement – [Visible if Space type is Continuous or GIS] The heading of the material item.

Rotate vertically as well (along Z-axis)  – If selected, the material item shape will be headed towards the target during the material item movement.

Space and network

Select the agents you want to place in the environment - Here you can select checkboxes in the list of agents that will live in this enviroment.

Space type – The group of buttons, specifying the type of environment's space:

Continuous – Continuous space. The space dimensions are specified using the Width and Height properties. The continuous space allows the user to set and retrieve the current material item location, to move the material item with the specified speed from one location to another, etc. Location of an material item in continuous space is defined by coordinates (x,y,z) of Java type double.
Discrete – Discrete space. The space is defined with a rectangular array of cells. Cells can be fully or partially occupied by the agents (at most one agent in one cell). AnyLogic support for this kind of space includes agent distribution over the cells, moving to a neighboring cell or jumping to arbitrary cell, finding out who are the agent's neighbors, etc.
GIS – GIS space. GIS space type allows placing agents into geospatial environment defined with a GIS map.

GIS map – [Visible if GIS Space type is chosen] The name of the GIS map that defines the geospatial space for the environment.

Width – [Enabled if Continuousor Discrete Space type is chosen] The horizontal dimension of the area visualizing the space on presentation (in pixels). In discrete space, cell width is calculated by dividing the specified Width by number of Columns in the space.

Height – [Enabled if Continuous, or Discrete Space type is chosen] The vertical dimension of the area visualizing the space on presentation (in pixels). In discrete space, cell height is calculated by dividing the specified Height by number of Rows in the space.

Columns – [Enabled if Discrete Space type is chosen] The number of columns in discrete space.

Rows – [Enabled if Discrete Space type is chosen] The number of rows in discrete space.

Neighbourhood type – [Enabled if Discrete Space type is chosen] Sets a neighborhood model, that determines the way the agent neighbours are defined in the discrete space. There are two options:

Moore (8 neighbors) – The neighbors are counted in all 8 cells (to the north, south, east, west, northeast, southeast, southwest)
Euclidean (4 neighbors)  – The neighbors are counted in 4 cells (to the north, south, east, west) only.

Layout type – [Enabled if Discrete or Continuous Space type is chosen] Defines the layout type (the way agents are initially located in the environment). 
If you wish your agents to be placed according to the set layout when the model starts, check the Apply on startup checkbox to the right.
AnyLogic supports the following standard continuous layouts: 

User-defined – assumes you will take care of the agent locations yourself in e.g. Startup code of the Main object.
Random
– an agent location is chosen randomly and uniformly within the space dimensions.
Arranged – the agents are arranged within the space dimensions.
Ring – the agents are uniformly distributed on a ring whose diameter is smaller than the smallest space dimension.
Spring mass – the agents are located as a spring mass system where agents are masses and their connections are springs. This is network-dependent layout type.

Network type – [Enabled if Continuous, or Discrete Space type is chosen] The network type, defining how the agents are connected. This standard network does not mean the agents cannot have other connections. You are free to define any kind of relationships between agents and store and manage the corresponding references.
If you wish this network to be constructed when the model starts, check the Apply on startup checkbox to the right.
AnyLogic supports the following types of agent networks:
User-defined – assumes you will take care of the agent connections yourself in e.g. On startup code of the Main object.
Random – agents are connected randomly with a given average number of connections per agent.
Distance-based – any two agents are connected if distance between them is less than a given maximum (in continuous space only).
Ring lattice – agent connections form a ring where an agent is connected to a given number of closest agents.
Small world – can be considered as ring lattice where some links have been "re-wired" to long-distance agents.
Scale-free – some agents are "hubs" with a lot of connections and some are "hermits" with few connections. Scale free network is constructed according to Barabasi, A. L. and R. Albert. 1999. Emergence of scaling in random networks. Science 286(5439): 509-512. For details please refer to Wikipedia.

Connections per agent – [Enabled if Network type is Random, Small world, or Ring lattice] The average (or exact) number of connections per agent. Applies to random, ring lattice and small world networks. 

Connection range – [Enabled if Network type is Distance based] Defines the radius of the connection area for the agent. The agent will be connected to all agents, who are within a radius of defined Connection range.

Neighbour link fraction – [Enabled if Network type is Small world] Parameter for Small world network type.

M – [Enabled if Network type is Scale free] Parameter for Scale free network type: either M and M0 (start number of hubs). For details please refer to Wikipedia.

Enable steps – If selected, agent-based modeling is synchronous. Synchronous modeling assumes discrete time steps and agents (and maybe environment) executing their actions synchronously at these time steps.
By adding such synchronization you do not restrict the dynamics of your model with discrete time steps. Your agents as well as other objects are still able to schedule events, execute state transitions and run other processes - this will go in parallel with steps execution.
You can customize the step duration using the Step duration property. Environment actions are defined using the On before step and On after step properties below.

Step duration (in model time units) – [Enabled if Enable steps is selected] This property enables the user to set some custom step duration in the case of synchronous modeling (the default step duration is 1 model time unit). 

Advanced Java

Imports sectionimport statements needed for correct compilation of the class code. When Java code is generated, these statements are inserted before definition of the Java class.

Implements (comma-separated list of interfaces) – Comma-separated list of interfaces implemented by the class.

Additional class code – Arbitrary member variables, constants and functions are defined here. This code will be inserted into the class definition. You can access these class data members anywhere within this material item. The functions can be called on some material item activity; e.g., on event occurrence or on triggering statechart transition. You can place any Java code here, however, we recommend to use the Java class element instead of defining nested classes here, and use option lists instead of defining Java enumerations. 

Parameterized type – If selected, you can define generic parameters for this material item type in the Type parameter field below.

Advanced

Extends other agent  – One material item type may extend some other material item type. This feature gives you an ability to expose the functionality common for agents of different types into one place, "base material item type". All material item types that extend the same "base material item type" will share this functionality. 

Log to database - If selected, all information about material items of this type (their parameter values, statistics on movement and time spent in different states, etc.) will be saved into the model execution log (if logging is turned on in the model's Database properties). 

Create datasets for dynamic variables –  If selected, AnyLogic creates datasets for all dynamic variables (stockflow and dynamic variables), contained in this material item type and collects the well-defined number (specified in the Limit the number of data samples up to first ... items property) of latest samples of these variables in these datasets. Samples collection will start at either First update time (absolute), or at the Update date if you select Use calendar dates to define the first update time. Samples are collected with the specified Recurrence time that you can set up below.
If this option is not set, the user needs to create dataset for each dynamic variable by himself. 

Recurrence time – [Enabled if Create datasets for dynamic variables is set] Defines the recurrence time for collecting samples of dynamic variables.

Limit the number of data samples up to the first ... items – [Enabled if Create datasets for dynamic variables is set] Defines the number of samples stored in each dataset automatically created by AnyLogic for dynamic variable.

Material item dimensions

Since material items are typically handled in the physical space (they are transported by conveyors and occupy a certain space on them), the dimensions of the material items are essential to obtain valid simulation results. The size of each material item is defined by three dimensions (length, width, height), which are set to 1 meter by default. Please refer here to know how to set and adjust material item dimensions.

Generating material items of a custom type and accessing custom material item attributes

To generate the material items of a custom type you should choose this type (e.g. Box) in the New agent parameter of the corresponding Source block (the property is located in the Agent section of the block's properties). This will make the flowchart use material items of this custom type, and you will be able to explicitly address the additional functionality of this material item type in the flowchart blocks.