Ask

Icon

Function

The Ask component lets you find target entities, access their properties, and call their behavior.

Tips

It's an essential way for entities to interact with each other, similar to asking someone to do something or accessing their properties. This is widely used in various scenario modelings, such as:

• In DeFi, a user trading tokens on a DEX can be seen as the User Agent asking the Smart Contract Agent to execute a swap method based on the provided parameters.
• In a grassland ecosystem, a wolf hunting a sheep can be seen as the Wolf Agent asking the Sheep Agent to perform its Die built-in behavior.
• In Cellular Automata, an individual within the Cell population may ask to access the states of its neighboring cells to determine its next state.

How It Works

Find Entities

In a system with multiple entities, you need to specify the following three aspects to find the target entity (or entities), and the system will execute in order:

1. Specify the Entity Scope
2. Specify the Filter Conditions
3. Determine the Final Target

Suggestion

The process of finding the target entity is crucial to the Ask Activity. Understanding its working mechanism helps to master the use of the Ask component.

Example 1

Take a grassland ecosystem as an example. To simulate a wolf finding a sheep to prey on, the wolf might need to:

1. Specify all neighboring entities within a certain spatial radius range.
2. Use the filter to select all individuals who are sheep and whose speed is less than a certain value.
3. Finally, determine the fattest individual.

Example 2

In the field of DeFi, token trading is an example. Suppose you want to buy an X token with USDC as the principal in a DEX at the lowest possible fee. In that case, you need to use the Ask component to find the corresponding token pair individual (the DEX has been modeled as an Agent population, and each individual corresponds to a token pair pool) for the next step of calling the transaction.

1. Specify the range, which is all individuals in the DEX population.
2. Use the filter to select individuals in the DEX where the "trade pair" (entity property) is "USDC-X."
3. Determine the individual with the lowest "fee rate" (entity property).

• The system will output the list of the asked target entities; see below for output data.
• Filtering target entities is an inevitable part of the Ask component's operation. Based on this, you can choose whether or not to access its properties and call its behavior.

Access Properties

After determining the target entity, you can choose to access its properties, but only when the target entity is one object.

Call Behaviors

• After determining the target entity, you can choose to call its behaviors.

• Behaviors that can be called through the Ask component must be passive and independent processes.

• Data Passing

  If interfaces are present in the process called through the Ask component, corresponding ports will appear in the asking object. The method of data passing is described in the Process Interfaces and Data Passing chapter.

• Please note

  When multiple target entities exist, if the calling process has a port to return the output value, although every target entity will run this process to return the output value at the current Tick, only the return result of the last individual run according to the operation sequence can be obtained in the end. Of course, you can view it in combination with debugging breakpoints, and call stacks.

  Tip

  • If the called process returns a Number through the port and you want to store this value in a variable V of Value format.
  • When the target object is only one entity, if you use "Ask" to call it, the port will return this value, and you can store it in V as expected.
  • But when the target object is multiple, each object will return an output value, so the variable V responsible for receiving this value receives multiple times and finally only saves the return result of the last individual running the process. Due to the randomness of the running order, this means that the results may be different each time it runs.
  • Since the system's result chart output only reflects the status of all at the end of the current Tick, so you can't see the results of other individuals in the chart of V.
  • But you can reasonably use features within the Console, such as debugging breakpoints, call stacks, and local variables, to view the intermediate results of other individuals.
  • So for such requirements, it is recommended to use other suitable ways to model, for example, you can establish an upper-level List variable for the callee, let the called process append the output value to this List by itself, to get all the data.

Boundary Events

• Finding an entity may not always succeed. For example, the target entity might not exist at all, or the filter conditions might be set incorrectly, both of which can lead to failure. By setting a boundary event for the Ask component, you are essentially setting up a response mechanism for any potential exceptions.
• The Ask component can be used in conjunction with Error Boundary Events. This indicates that if the system fails to find any target entities, the process Trigger will immediately flow to the boundary event branch.

Setting Methods

Find Entities

Specify Entity Scope

The input field accepts expressions that return an Entity or [Entity] format value.

Example

• wolf.Individuals: All individuals in the wolf population.
• sheep.FilterEntities(self.GetNeighbors(1.5)): All sheep within a radius of 1.5 with oneself as the center.
• GetRelatives(cooperation,1): People who have a direct (radius 1) cooperative relationship (named cooperation Link object) with themselves (here you can omit the self keyword; Only Agents can act as the network nodes.)
• sheep.Individuals.copy().extend(cattle.Individuals) : All individuals in the sheep and cattle populations.

Specify Filter Conditions

• Filter entity population

  Select an existing entity object in the model from the dropdown menu for quick and specific filtering. Alternatively, you can choose 'Any Population' if filtering is not required.

• Custom filter condition expression

  

  • Click the "Add Filter Condition" button to add an input box to enter the condition expression.
  • An and/or relationship can be selected between all expressions.
  • The expressions are used to filter all current target individuals. They should be relevant to the current target individual objects. The default keyword is Entity, but it can be customized. The expressions should return a Boolean value. Typically, we use condition expressions related to Entity.property_name to filter based on the entity's properties.
  • The system will match all target individuals one by one for each expression calculation result, finally retaining those that return True, to get the target object.
  Tips

  • Filter is essentially equivalent to the Map(filter_method,[entity_object]) function. The filter method is a condition expression, and the entity object is a list of entities already within the scope. The Map function applies the filter method to each object in the list, yielding a result in [bool] format. The target object is then determined based on this result.
  • During modeling, a common filter method is to check if an object has a specific property. For instance, Entity.Color == "red" can be used to identify entity individuals with the Color property set to red.

Determining the Final Object

Tips

• After going through the previous two steps, we've identified individuals that are within our scope and satisfy our filter conditions.
• However, the task is not over as we need to specify the final output requirements. For instance, do we need individuals or a list of collections? If it's a collection, how many do we need? Which ones are required? How do we determine which ones are needed?
• Hence, it is crucial to determine the final object.

• Determine output form

  Choose between Single or Set, which corresponds to the return target entity format being either Entity or [Entity].

• Selection method

  Use the dropdown menu to select the method for obtaining the final objects.

  • All

    Select all entities; no further setup is required.

    

  • Random

    

    • For a single individual, it randomly selects one with no further setup required. For a set, you need to specify the Number (expression) to be selected.
    • The expression should return a natural number in Number type.

  • Max (Maximum)

    • Select the entity with the maximum calculated value based on the provided sorting expression.

      

    • Select Number

      • If you choose generating an entity set, it's also required to input an initial amount (similar to Random Method).
      • If the quantity of individuals meeting the conditions is less than the set number, all individuals will be selected.

    • Sort By

      • Upon choosing Max, you need to enter an expression in the "Sort By" input box.
      • The expression should relate to the target entity's properties, formatted as Entity.property_name, and it should return a Number type.

  • Min (Minimum)

    Selects the entity with the minimum calculated value based on the provided sorting expression. The usage is the same as the "Max" method.

  • Median

    Selects the entity with the median calculated value based on the provided sorting expression. The usage is the same as the "Max" method.

  • Sum Limit

    • Select entities based on the summed results from the provided "Sum By" expression, ensuring the total doesn't exceed the given "limit value." The system will randomly pick individual entities within this range, accumulating the results of the expression calculations until the limit value is exceeded.

      

    • Number (Upper Limit)

      • Input an expression that returns a Number.

    • Sum By

      • Input a calculation expression about the target entity property (formatted as Entity.property_name) that can return a Number type.

Example of Sum Limit

A driver of a vehicle with a maximum load of 140 can select packages weighing 60, 70, and 80 for loading.

Selecting the Ask Types

Choose the types of Find Entities, Access Properties, and Call Behaviors.

Find Entities

No further configuration is required.

Access Properties

This option is only available when there is a single selected object.

• Add Property

  Clicking the Add Property button will bring up a dropdown list box. You can select the target property from this list. Multiple properties can be accessed in a single Ask.

• Add Quote to the canvas

  Clicking the button on the right will automatically add a Quote to the current property near the ask component on the canvas for easier modeling.

  

  

  Tip

  You can also drag and drop an empty Quote component onto the same canvas, then select the property that you want to access as the quoted target. This method also offers a simple way to incorporate quotes into your canvas.

Call Behavior

• Setup Methods

  • Select behavior: Choose the target behavior from the dropdown list box.

  • Jump to the original entity: There's a navigation button to the right of the dropdown list box. Clicking this button will focus the current canvas view on the target object.

    

• Notes

  • A single ask can only call one behavior.

  • The called behavior must be the target entity's passive and independent process.

  • The component's shape on the canvas changes to a rectangle, similar to the Call component's, and its usage is identical.

    

  • If the called process has a port, the relevant chapter details the data passing through ports.

The Ask Component Has Data Output

1. For the found entity objects,

   • They are formatted as either Entity or [Entity].
   • Access them in the formula following this component's action as This.Entity.
   • They can also be accessed in the expression of subsequent objects within this process as ask_component_name.Entity.

2. For the accessed properties,

   • Access the properties in the formula following this component's action as This.property_name.
   • The properties can also be accessed in the expression of subsequent objects within this process as ask_component_name.property_name.

3. For the called Port data,

   • This follows a similar approach to the Call component, so it is not detailed here.

For the above three scenarios, the system's priority in recognizing formulas or expressions 2 and 3 (these two will not appear simultaneously) is higher than 1.

Example

Model Example

• Two DeFi users are buying WETH tokens and selling WBTC tokens from a constant product AMM DEX, respectively. The DEX has two individuals responsible for two types of token pairs.
• The initial situation of the DEX's two token pair pools is shown in the figure below.
• After the transaction, the price of WETH rises due to buying, while the price of WBTC falls due to selling.