Containers

Icons

The icon for Containers is shown below.

Please refer to the Data Components chapter for different icons of container objects on the canvas in various scenarios.

Function

The container is a data component in dictionary type (key-value pairs) specifically designed to store resources and entities.

Key Points

Suggestions

Containers are typically used in conjunction with Container Operate components and Container Operate Connectors. It is recommended that you understand these related concepts together.

Understanding Resources

Resources stored in containers can be divided into the following two types:

• Producible/Consumable Resources

  These are homogenous items that can be utilized, exchanged, consumed, and reproduced. They support various types.

Examples

Examples include,

• Wood and minerals in a game
• Cryptocurrencies like BTC, ETH, and ERC20 tokens in DeFi
• Various fiat currencies, such as the US dollar
• Stock in system dynamics

• Reusable Resources

  These are homogenous elements that cannot be reproduced and exchanged. They have a fixed total number and can be shared. Once occupied, they need to be released before they can be used again. They also support various types.

Examples

Examples include,

• Parking spaces in a parking lot
• Process locks in programming
• Service windows in a bank
• Storage capacity limits of a block in blockchain

In summary, resources are abstract homogenous items. In the model, there are no specific objects representing resources, only the concept of category and quantity.

Understanding Resource Containers

• A Resource Container stores various types of resources as key-value pairs. The key represents the resource type and the value represents the quantity of the resource. Operations on the container are carried out based on the resource type.
• A Resource Container is essentially a unique type of Dict object. The keys in the resource container must be in String type, while the values must be in Number type.
• When defining a resource container, you need to specify the specific resource (the keys of the container) to be operated on, the initial amount (the values of the corresponding keys) of each resource, the maximum capacity of each resource, and whether the resources can have negative values. These settings will affect the outcome of resource operations.

Tip

In the DeFi field, during modeling, we usually consider user wallets and DEX liquidity pools as resource containers. Additionally, we use the name of each token as the key for these containers. This method of categorizing resources within the containers makes it simpler to manage the different token balances of EOA account addresses and smart contract addresses.

Understanding Operations on Resource Containers

Tips

The Get (Resource Out) and Put (Resource In) operations for resource containers can be understood as follows:

• For Producible/Consumable resources, Get can be understood as the extraction, consumption, payment, or outflow of a resource, while Put can be seen as the storage, production, income, or inflow of a resource, depending on how you model the container.

• For Reusable resources, Get can be understood as requesting the use of a resource, whereas Put can be interpreted as the releasing the use of a resource.

• Refer to the chapter on Container Operate components for more information.

Setup Methods

• The settings include the type (default to Resource, with support for selection in the future), batch keys, capacity, and initial amount.
• The setup methods for containers vary based on their location, whether they act as global containers, entity properties, or local containers.

As a Global Container (General settings)

If it is a Global Container, the type is currently non-selectable; only the resource container is supported.

Batch Keys Construction

• Adding an Expression Line

  • By clicking the "Add" button, an expression input box will appear.

  • The outcome is the set formed by all the expression lines.

    

• Entering a Construction Expression

  • Use the "Construction Expression" to define the potential keys for the container.

Tip

These construction expressions are not universally applicable, unlike common expressions that can be used in all input fields. Syntax such as the -> operator and the ProductJoin function are specifically designed for batch key construction and are not part of the general syntax.

When inputing construction expressions, please pay attention to the smart suggestions in the input box as shown in the image above. The basic usage is as follows:

• Enumerate: Input multiple String values directly as container keys, separating them by commas.

• Specify Range: Connect two Number values or String letter values using ">", and all values in between will serve as container keys.

• Enter a [String], and each element will function as a container key.

• Use the Tag Set directly, with each tag serving as a container key.

• Use the ProductJoin Cartesian Product Function to sequentially combine and join the elements of several lists, forming a new string. Each value will be a key for the container, as illustrated below. Refer to the detailed specifications for further information.

  

• Previewing After Construction

  You can click the preview button to observe the effect as shown in the picture above

• Effect After Construction

  There will be relevant prompts in other related settings, such as the resource type selection of the Container Operate Connectors, as shown in the picture below.

  

  

Example: Batch Keys Construction

In Web3 modeling, you might need a wallet to store various ERC20 tokens, including protocol tokens and LP tokens (e.g., "WETH-USDC"). Manually setting each one would be tedious, but using batch keys construction makes it simple.

• Suppose you have a Tag Set named ERC20, as illustrated in the left image below. If you want the container to serve as a wallet that can hold balances of various ERC20 tokens, you can set up a construction expression, as shown in the middle image. Clicking the preview button displays the constructed keys, as seen in the right image.
• You might find some keys unnecessary, like "COMP-COMP", but it's not a problem as it doesn't affect the simulation.

• Note: Constructing batch keys for the container doesn't mean the system will initialize all key-value pairs at runtime. This process merely predefines the rules without actually creating them. The system instantiates them under the following circumstances:
  • The initial amount of resources is defined in the container's Detail configuration.
  • The initial amount of resources is defined in Individual Properties Settings for Agent Individuals.
  • During the modeling process, you can use formulas to assign values to specific resource keys within designated containers or read them.
  • Also, during modeling, use the Container Operate component to get and put specified resources within the containers.

Capacity Limits

• This represents the default storage limit of various resources in the container.
• If selected, the container has no capacity limit.
• If deselected, the input box below will light up, where you can enter any expression that returns a non-negative Number. A negative value indicates there is no limit.

Can the Initial Amount Be Negative?

Selecting "negative" indicates that the quantity of resources in the container can be negative. Deselecting it means that the quantity cannot be negative.

Tips

How can resources be negative?

• There will never be a situation where the extraction is insufficient.
• It is usually used when you don't care about the total amount of a certain resource, and only need to consider the change in balance.
• For example, in the DeFi field, you have a trader Agent who makes profits by buying low and selling high in USDC. He has a resource container as a wallet. You only care about the total profit situation when the simulation ends. In fact, you don't need to give him a large initial USDC amount as principal, and after the final value statistics, consider the difference with the initial value to measure the income. Instead, set the initial amount of USDC in the wallet to 0, and set the container to be negative, so the final income is the balance-if it is a loss, it is negative, if it is a profit, it is positive.
• In system dynamics modeling, for example, stocks (resource containers) can be set to be negative.

Example

Consider a resource container where the resource quantity can be negative. The initial value of resource a is 10. Then you get 1 out of resource a at every 'Tick'. After 20 'Ticks', the remaining value of resource a will be -10.

Tips

• The container's capacity limit and whether it allows negative values are only enforced during operations; formula assignments do not directly trigger these limits.
• For example, you can use a formula to modify the resource quantity in a container, such as Container.a = 100, even if the capacity limit for that resource is 50. The modification will succeed, but the capacity check will only occur during the next operation. For instance, if 10 more units are added, the system will throw an error indicating that the container's capacity limit has been exceeded.

Default Initial Amount

• Input box: Enter an expression that returns a number. If you select "negative", you can enter a negative value.
• Please note: This is the default value. If you have constructed batch keys before, then each resource defaults to this initial value.

Initialization Detail Configuration

The detail configuration will override the default value set in the above unified settings. Click the detail configuration button to pop up the configuration interface. From left to right, the settings are as follows:

• Specify the resource (Container Keys)
• Decide whether the capacity limit is infinite. If deselect "infinite", set the upper limit for each resource.
• Input initial amount expressions
• Set whether the resource can have a negative value.

As an Entity Property

• When containers are inside entities, they serve as entity properties.
• The container settings and initial values follow the same mechanism as the global container described above.
• "Belong to" Settin (as shown above): Choose whether the container belongs to the individual or the observer.
• When it serves as an agent property, it also supports the personalized configuration of each individual's container. Detailed information can be found in the Agents chapter.

As a Process Local Container

• The container settings and initial values are the same as for global containers.
• Type Selection: Container interfaces or common containers.

Container Interfaces

• The lifespan of a container interface is dependent on an external Trigger process. It does not have a register mechanism.

• Once set as a container interface, the corresponding ports will be displayed in the outline of the local process, as well as in the outline of the components that call or ask to call this process, and the port symbol is "R".

• Unlike variables, containers can only pass objects. That is, a container object can only be passed using a State Connector that connects ports. It is not possible to pass a container object via an expression as a parameter on the properties panel of the object where the port is located.

  

Common Containers

Like those containers that act as global variables or entity properties, common containers also have a permanent lifespan and lack a registration mechanism. Their setup method remains the same.

Example

Example: System Dynamics Stock Transfer

The Flow process transfers 1 WETH from the Stock 1 container to the Stock 2 container every Tick.