Find and Extract Entities in SimEvents Models

You can find entities in a SimEvents^® model by using an Entity Find block. The block searches and finds entities that use a particular resource from a Resource Pool block and acquire it through a Resource Acquirer block.

You can use the Entity Find block for these applications.

Model a supply chain to monitor perishable items and update the inventory records. For instance, you can modify the price of an item when it is closer to its expiration date.
Model timers and perform actions on products based on timers.
Model recall of products from a supply chain. You can reroute recalled products back to the supply chain after repair.

Finding and Examining Entities

The Entity Find block helps you find and examine entities at their location. In this example, the block finds entities that are tagged with a Resource1 resource from the Resource Pool block. Then, an additional filtering condition helps to further filter the found entities.

Add an Entity Generator block, Resource Pool block, Resource Acquirer block, Entity Server block, and Entity Terminator block.
The top model represents the flow of entities that acquires a Resource1 resource.
In the Entity Terminator block, output the Number of entities arrived, a statistic and connect to a scope.
Add an Entity Find block. Output the Number of entities found, f statistic and connect it to a scope.
By default, the block finds entities with the Resource1 tag.
Add another Entity Generator block and label it Trigger Entity Generator. Connect it to the input port of the Entity Find block. In the block, change the Entity type name to Trigger and Entity priority to 100.
Every time the Trigger Entity Generator generates a trigger entity, the Entity Find block is triggered to find entities.
Note
The entities in the model have priority 300 and the priority of the trigger entity is set to 100 to make trigger entities higher priority in the event calendar. This prevents the termination of the entities before they are found by the Entity Find block.
Simulate the model and observe that the number of terminated entities is 10, which is equal to the number of found entities by the Entity Find block. Every generated entity acquires a Resource1 tag and there is no blocking of entities in the model.
The Entity Find block finds entities with the Resource1 resource for every generated trigger entity.
In the Entity Generator Block Parameters dialog box, in the Generate action field, add this code.
```
entity.Attribute1 = randi([1,2]);
```
The entities are generated with a random Attribute1 value 1 or 2.
In the Entity Find Block Parameters dialog box, select the Additional filtering condition check box. Add this code to replace any existing code and to set the filtering condition.
```
match = isequal(trigger.Attribute1, entity.Attribute1);
```
The block finds the entities that acquire the Resource1 tag when the match is true. That is, the Attribute1 value of an entity is equal to the trigger entity Attribute1 value.
In the Trigger Entity Generator, observe that the Attribute1 value is 1.
Simulate the model, observe that the number of found entities decreased to 3 because entities with the Attribute1 value 2 are filtered out by the additional matching condition.
The trigger entity Attribute1 value is 1. The block finds entities that acquire Resource1 tag and have the Attribute1 value 1.

Extracting Found Entities

You can use the Entity Find block to find entities and extract them from their location to reroute. In this example, 3 entities found in the previous example are extracted from the system to be terminated.

To open the model, see Extract Found Entities Example.

In the Entity Find Block Parameters dialog box, select the Extract found entities check box.
Observe that a new output port appears at the Entity Find block for the extracted entities.
Connect the output of the Entity Find block to a new Entity Terminator1 block.
Output the Number of entities extracted, ex statistic from the Entity Server block and connect it to a scope.
Visualize the number of extracted entities from the server.
Output the Number of entities arrived, a statistic from the Entity Terminator1 block and connect it to a scope.
The statistic is used to observe the number of found and extracted entities from the system.
Simulate the model. Observe that the Number of entities extracted, ex is 3.
Observe that 3 found entities are extracted from the Entity Server block and terminated in the Entity Terminator1 block.
As a result, 7 entities arrive at the Entity Terminator block in the model.

Changing Found Entity Attributes

You can change the attributes of the found entities at their location or with extraction.

Change the attributes of found entities at their location by entering MATLAB^® code in the OnFound action field of the OnFound event action. For more information about events and event actions, see Events and Event Actions.
Change the attributes of found and extracted entities when they enter, exit, or are blocked by the Entity Find block. Enter MATLAB code in the Entry action, Exit action, and Blocked action, field of the Event actions tab.

Triggering Entity Find Block with Event Actions

You can trigger the Entity Find block with event actions. In this example, the Entity Find block is triggered when an entity enters the Entity Server block. Modify the previous example by removing the Trigger Entity Generator and by adding the Entity Output Switch, Entity Server1, Entity Terminator2 and Scope blocks to the model and connect them as shown.

To open the model, see Trigger Entity Find Example.

In the Entity Output Switch block, set the Switching criterion to Equiprobable.
Entities flow through the Entity Server and Entity Server1 blocks with equal probability.
Replace the Trigger Entity Generator block by a Simulink Function block to trigger Entity Find block. On the Simulink Function block, double-click the function signature and enter Trigger(u).
In the Simulink Function block, add the Message Send block and connect it to an Out1 block.

The Trigger(u) function call generates a message to trigger the Entity Find block every time an entity enters the Entity Server1 block.
In the Entity Server block, in the Entry action field, enter this code.
```
Trigger(double(1));
```
Every entity entry calls the Trigger(u) function in the Simulink Function block that triggers the Entity Find block.
In the Entity Find block, select the Additional filtering condition check box. Enter this code.
```
match = isequal(2, entity.Attribute1);
```
Found entities have the Attribute1 value 2.
Simulate the model. Observe the scope that displays the extracted and terminated entities when the Entity Find block is triggered by the entity entry to the Entity Server block.

Building a Firewall and an Email Server

You can use the Entity Find block to monitor multiple blocks in a model to examine or extract entities and modify entity attributes.

This example represents an email server with a firewall to track, monitor, and discard harmful emails before they reach the user. In the model, emails arrive from the Internet through an Entity Generator block. In the Firewall component, emails are classified as harmful for instant discarding, suspicious for monitoring, or safe based on their source. Harmful emails are tagged with a DiscardTag resource from the Resource Pool block and instantly discarded from the system. Suspicious emails are tagged with MonitorTag and tracked throughout the system for suspicious activity. If a suspicious activity is detected, the email is discarded before it reaches the user. Safe emails are not monitored or discarded.

To open the model, see Email Monitoring Example.

Build Firewall and Email Server Components

Add an Entity Generator block. In the block, set the Entity type name to Email and attach two attributes as Source and Suspicious with initial value 0.
Add an Entity Server block. In the block, select the Event actions tab, and in the Entry action field enter this code.
```
entity.Source = randi([1,3]);
```
The Source attribute value is randomly generated and it is 1 for a suspicious, 2 for a safe, and 3 for a harmful email source.
Add an Entity Output Switch block. In the block, set the Number of output ports to 3, the Switching criterion to From attribute, and the Switch attribute name to Source.
Add two Resource Pool blocks and set their Resource name parameters to MonitorTag and DiscardTag.
Add a Resource Acquirer block labeled Tag Emails for Monitoring. In the block, select MonitorTag as Selected Resources.
Add another Resource Acquirer block labeled Tag Emails for Instant Discard. In the block, select DiscardTag as Selected Resources
Add an Entity Input Switch block. In the block, set the Number of input ports to 3.
Add an Entity Store block. In the block, select the Event actions tab, and in the Entry action field enter this code.
```
InstantDiscard(1);
entity.Suspicious = randi([1,2]);
```
Add an Entity Queue block. In the block, select the Event actions tab, and in the Entry action field enter this code.
```
entity.Suspicious = randi([1,2]);
```
The Suspicious attribute of an email changes in the entry. If the Suspicious attribute value is 2, the email is extracted and terminated. This represents the randomly observed suspicious activity in the system.
Add another Entity Server block. In the block, set the Service time value to 3, select the Event actions tab, in the Entry action field, enter this code.
```
entity.Suspicious = randi([1,2]);
```
Add an Entity Terminator block labeled Emails Read by User, and connect all the blocks as shown in the model.

Monitor and Discard Emails with Entity Find Block

Add a Simulink Function block.
1. Double-click the function signature on the Simulink Function block and enter InstantDiscard(u).
2. Double-click the Simulink Function block. Add a Message Send block and an Out1 block.
In the parent model, add an Entity Find block. In the block, set Resource to DiscardTag and select Extract found entities check box.
Any email entry calls the InstantDiscard() function and triggers the Entity Find block to find and discard harmful emails.
Add another Entity Terminator block labeled Instantly Discarded Emails.
Add another Entity Find block. In the block, set the Resource to MonitorTag and select the Extract found entities and the Additional filtering condition check boxes. In the Matching condition field, enter this code.
```
match = isequal(trigger.Attribute1, entity.Suspicious);
```
Add another Entity Generator block labeled Entity Generator1. In the block, set the Period to 5, the Entity priority to 100, the Entity type name to Trigger, and the Attribute Initial Value to 2.
Add another Entity Terminator block labeled Monitored and Discarded Emails. Connect all the blocks as shown in the model.
Output the Number of entities arrived, a statistic from all of the Entity Terminator blocks, and connect them to the Scope blocks for visualization.
Increase the simulation time to 50 and simulate the model. Observe the emails that are instantly discarded or discarded after monitoring.

Observe the emails that reach the user after the filtering.
Optionally, visualize the number of extracted emails from any block in the model. For instance, in the Email Queue, select the Number of entities extracted, ex statistic and connect to a scope. Observe that six emails are extracted from the queue.