Data Components

Icons

Data components and their quotes are represented by different icons on the canvas under various circumstances.

Items | Types	Variables	Variable Quotes	Containers	Container Quotes
Global, Entity Individual Properties, Regular Objects
Entity Observer Properties
Process Temporary Objects			\	\
Process Interfaces
Entity Individual Built-in Properties	\		\	\
Entity Observer Built-in Properties	\		\	\

Key Points

Function

Data components, including variables and containers, are used for data storage.

Data Types

Variables support various data types (Value/List/Dict), and containers are specially used for operations involving the Dict data type.

Scope

The directly accessible area of a data object is known as its scope. This means you can place its quotes or use the object name directly in formulas within its scope.

Principle

Lower-level canvas can directly read and write data objects located on the upper-level canvas.

As Global Properties

Data objects on the root canvas have a global scope and act as global properties. As a result, they can be accessed and modified from any subordinate location within the model.

As Entity Properties

Data objects on the entity's internal canvas (outside the process) act as entity properties. These have a scope limited to the entity, which means:

• Inside the Entity, entity properties of the same objects can be directly accessed and assigned from any position.
• Outside the Entity or for different objects within entities, direct access and modification are not possible due to scope limitations. However, indirect interaction can be achieved through the following methods:
  • Graphical Modeling Access: You can use an Ask component to access the properties of a specific individual. The accessed properties can be quoted on the current canvas using ask_component_name.Entity.property_name. Note that it cannot be assigned as the component's output cannot be modified.
  • Formula Read/Write: Individual properties can be accessed and assigned using single_entity_object.property_name.
  • Additionally, outside the scope, you can indirectly access current values by passing data through process interfaces.

Example

Agent1 accesses Agent2's two properties, x and y, both initially set to 0, using both the Ask component and a formula. Agent1 then increments both properties by 10.

• Individual and Observer Properties
  • An entity has individual properties and observer properties. Whether a property belongs to the observer or the individual depends on the Belong to setting on its properties panel.
  • Observer properties have a scope that covers the entire population, meaning any individual within the entity can directly read and write to observer properties.
  • Individual properties have a scope that are limited to that specific individual, meaning that the observer cannot directly access individual properties, and neither can other individuals.
  • For individual properties, each individual within the entity has its own separate instance. It's important to note that these instances don't have the same scope.

Example

For example, if there are two individuals in the sheep population, Sheep1 and Sheep2, for their Age properties, Sheep1's Age cannot be directly read or written by Sheep2. Instead, Sheep2 needs to use Sheep1.Age in the formula, or use the Ask component to access Sheep1's Age property and even call its method to modify the Age property.

Process Local Data Objects

• These are data objects placed on the canvas within a process.
• Their scope is limited to within the process (including subprocesses). They cannot be accessed by external or parent processes (such as the model's root canvas).
• Outside their scope, if an external process needs to access the intermediate state of a passive process triggered by a specific event, you can indirectly access the value at that time by passing data through process interfaces. The passive process can assign and save its state to an interface, allowing subsequent external computations to access the corresponding port to obtain the final state at that time. This includes three scenarios:
  • For a parent process, use sub_process.port_name.
  • For the Call component, use call_component_name.port_name.
  • For the Ask component (ask to call), use ask_component_name.port_name.

Clearly, the value accessed is related to the trigger that initiated the process, ensured by the register mechanism.

Modeling Usage

For Graphical Modeling

• For instance, data objects or their quotes can be connected to process ports by State Connectors for passing data objects, and containers are connected to container operate objects by Container Operate Connectors. For more details, refer to the corresponding sections for each element.
• Quotes pointing to data objects are fully equivalent to the original objects and can be used in graphical modeling.

For Expressions

• Use appropriate names to construct expressions or formulas.
• Directly use names when within scope in any scenario.
• For entity properties, use dot syntax object.property_name for reading and writing when outside the scope as described in the Scope section above.
• You can also use thedata_object.methodformat to call data type methods, as explained in the Detailed Specifications.

Tips

• As the formula can directly use the names of data objects and process objects, it's important to consider the issue of duplicate names.
• When elements share the same name, the input field's object recognition priority is outlined in the Compute chapter. Additionally, the system will provide model warnings for your reference.

Working Mechanism

Initialization

At the time of model initialization, the system adheres to the following priority order:

1. Global objects
2. Entity properties
3. Local objects

Thus, the data components in the later order can use expressions about the data objects in the earlier order when configuring initial values. For example, a global variable X can be used to set the initial value of an Agent's property variable as 2X.

Tips

Based on the above rules,

• Entity properties can be initialized using expressions about global variables.
• The number of Agent populations cannot be initialized using global variables due to the same hierarchy.
• Local variables within an entity process can be initialized using expressions about entity properties and global variables.
• Parameters in the start event of an active process can utilize expressions of their superior variables.

Types of Process Local Data Objects

• Local objects can be categorized as interfaces, regular objects, and temporary objects (variables only).
• Once set as an interface, the corresponding ports will be displayed in the outline of the process, as well as in the outline of the components that call or ask to call this process.
• The method of data passing of process ports is detailed in the Process Interfaces and Data Passing chapter.

Lifespan and Register Mechanism

• The duration from the creation to the destruction of a data object is called its lifespan.
• The binding of the storage state of a data object with the process Trigger is called the register mechanism, i.e., the data object stores the state value separately for each Trigger for subsequent calculations triggered by it.
• The working mechanisms of data objects of different types and different hierarchical scopes are not exactly the same and can be divided into the following two categories:

Regular Objects

• Permanent lifespan, no register mechanism.
• Includes global objects, entity properties, common variables of local processes, and containers of non-process interfaces, i.e., all situations except the following temporary objects.

Temporary Objects

• Temporary Variables of the Process
  • Lifespan: It is created when the start event of the process creates a Trigger and is destroyed when the Trigger reaches the end event.
  • Register: Temporary variables store values corresponding to each Trigger. Any computation triggered by the process can directly access these values using temp_variable_name.
• Container Interfaces
  • Since the corresponding ports can only pass data objects via State Connectors, the interface objects are independent of the process Trigger. This means they do not have register within the process, and their lifespan is also independent of the process.
  • Within the process, these interfaces can be directly accessed through expressions using container_name. They can also connect to Container Operate Connectors for container operations or connect to State Connectors to pass data to subordinate process ports.
  • The corresponding ports cannot be accessed using formulas to retrieve their state.
• Variable Interfaces
  • When the corresponding port passes values in parameter form, the lifespan and register of this variable interface are based on the local Trigger within the process, functioning similarly to temporary variables in the process. The port state is stored based on the (ask) call Trigger.
  • When the corresponding port is [connected via a State Connector to pass external variable objects](/docs/system-simulation/process-components/process-interfaces-and-data-passing#pass-data-objects-via-state Connectors), the variable interface object does not have a register, and its lifespan is independent of the current process. Within the process where the interface is located, it can be directly accessed through expressions using variable_interface_name, or it can be connected via a State Connector to pass to subordinate process ports, where the corresponding port cannot use formulas to access the state.

Model Example: Understanding Register

Please run the model in a step-by-step manner and pay attention to the Show variable value at the 5th and 10th Ticks.

The start event generates a Trigger at the 1st Tick. The Trigger assigns the current Tick (1) to the temporary variable TempVar in the first Compute component, goes up the branch after the trigger filter gateway, and should trigger the Compute component to assign TempVarto the Show common variable after a delay of 9 Ticks. So the Show value is 1 at the 10th Tick.

The start event generates the second Trigger at the 3rd Tick. The Trigger assigns the current Tick (3) to the temporary variable TempVar in the first calculation, goes down the branch after the triggerfilter gateway, and should trigger the Compute component to assign TempVar to the Show common variable after a delay of only 2 Ticks. So the Show value is 3 at the 5th Tick.

It is precisely because TempVar has a register mechanism that stores the values 1 and 3 for the two Triggers at that time. Therefore, from the Show variable (which does not have a register mechanism), you see the two values arrive in reverse order. Otherwise, you should see Show as 3 at both the 5th and 10th Ticks.

How to use Data Components in your model

Creating a Data Object

• Drag and drop data components onto the canvas to create a data object.
• Depending on the data type, the canvas it's placed on, sub-type settings, etc., the displayed icon may vary as explained in the previous "Icons" section.

Style Control

• Clicking on an object will display a style control bar.
• For additional details on changing colors, adding descriptions, and more, refer to the Modeling Guide chapter.
• Switching Object Mode: The first button on the control bar can switch the object shape to a monitor.

Monitor

• The monitor will display the currently stored value of the data object in real time.
• When the data object is a property of an entity, it will present the values of all entities in the Dict type.