Publish Ready-to-Run Actor Behaviors for Reuse and Simulation Performance

This topic explains how to generate ready-to-run actor behaviors using the publishActor function, as well as general considerations when creating ready-to-run packages. For more information about simulating RoadRunner scenarios with MATLAB® and Simulink®, see Overview of Simulating RoadRunner Scenarios with MATLAB and Simulink.

You can generate ready-to-run actor behaviors from your Simulink models using RoadRunner scenario blocks or MATLAB System (Simulink) blocks. Using ready-to-run packages as your actor behaviors enables you to associate the same behavior with multiple actors in your scenario, modify behavior parameters locally for each actor, and improve simulation performance. This topic uses a simple Simulink model to explain the workflow. You can follow similar steps for other behaviors that use MATLAB System blocks by opening the example and using the mUpdateXDirectionWithMATLABSys.slx model.

This topic assumes that you have:

  • Simulink and Simulink Coder™ licenses.

  • A RoadRunner license, and the product is installed. For more information, see Install and Activate RoadRunner (RoadRunner).

  • A RoadRunner Scenario license, and the product is installed.

  • A RoadRunner project folder named MyRoadRunnerProject. For more information, see RoadRunner Project and Scene System (RoadRunner).

  • The RoadRunner scene file SceneWithMutipleLanes.rrscene and scenario file LaneswithMultipleActors.rrscenario in your project MyRoadRunnerProject. You can access these files in your working folder after you open the example in this topic.

Open Simulink Model for Moving Actors

This example uses:

Open Live Script

Open mUpdateXDirection. This is a simple Simulink model with RoadRunner Scenario Reader, RoadRunner Scenario Writer, and RoadRunner Scenario block and the UpdatePose_along_X_Axis component.

In this model:

  • A Receive (Simulink) block converts messages from RoadRunner Scenario Reader block to bus signals.

  • UpdatePose_along_X_Axis component processes the signals.

  • The signals from UpdatePose_along_X_Axis component are converted to messages using a Send (Simulink) block.

  • The messages are communicated with RoadRunner scenario using RoadRunner Scenario Writer block.

rrscenario-actormove-topmodel.png

UpdatePose_along_X_Axis component processes the Pose element of the BusActorRuntime bus signal by updating the x-direction displacement of the actor. SpeedFactor parameter defines the magnitude of the displacement.

rrscenario-actormove-component.png

In the model, the SpeedFactor parameter is configured to be a tunable parameter by RoadRunner. The steps for this configuration are identical to the case when you expose a model argument as a tunable parameter on the Model block at each level of the model hierarchy. For more information, see Configure Instance-Specific Values for Block Parameters in a Referenced Model (Simulink).

rrscenario-actormove-speedfactor-check.png

Generate Ready-to-Run Package from the Simulink Behavior Model

This section describes the steps to create the LaneswithMultipleActors.rrscenario RoadRunner scenario file in your example. To create this scenario, use the publishActor function to generate ready-to-run actor behaviors from the Simulink model. The section also shows how to associate the behavior with two vehicles in LaneswithMultipleActors.rrscenario.

  1. Use this code to generate the package for your behavior model. This command publishes mUpdateXDirection as a ready-to-run package and creates an mUpdateXDirection.zip file in your current directory.

    Simulink.publish.publishActor('mUpdateXDirection',PackageType='ReadyToRun')

  2. In RoadRunner, open LaneswithMultipleActors.rrscenario and in the Library Browser, select the Behaviors folder.

  3. To create a new behavior, right-click an empty space in the list of behaviors, pause on New, then select Behavior. Enter a name for your new behavior, such as MyNewBehavior. This animation shows how to complete these steps.

    Animation showing navigating to Behaviors folder in Library Browser, right clicking and selecting New then Behavior to create a behavior, and naming the behavior "MyNewBehavior".

  4. On the Attributes pane, set Platform to MATLAB/Simulink. Specify File Name as mUpdateXDirection.zip.

    Platform is chosen as MATLAB/Simulink and the File Name is mUpdateXDirection.zip

  5. Select Add Parameter, and add SpeedFactor as a parameter.

    The SpeedFactor parameter is added to the behavior

  6. Associate the behavior MyNewBehavior with the two vehicles in your scenario. For more information, see Overview of Simulating RoadRunner Scenarios with MATLAB and Simulink.

    The behavior is attached to the two vehicles in the scenario a blue sedan and a white sedan

  7. From the Logic editor, select the Sedan action phase, and add a Change Behavior Parameter action that sets the value of SpeedFactor parameter for each actor in your model. For this example, in LaneswithMultipleActors.rrscenario scenario, the white sedan Sedan has a SpeedFactor value of 1, and the blue sedan Sedan2 has a SpeedFactor value of 2.

    SpeedFactor parameter is modified for both sedan vehicles.

Simulate the Scenario and Observe the Actor Behavior

This section uses LaneswithMultipleActors.rrscenario scenario file from the example, and describes the steps to simulate the scenario.

  1. Specify the path to your RoadRunner installation folder using these commands, replacing MyInstallationFolder with the path to your RoadRunner installation. You need to run the commands in this step only the first time you are setting up the connection between RoadRunner and your MATLAB installation.

    RRInstallationFolder = "MyInstallationFolder";
s = settings;
s.roadrunner.application.InstallationFolder.PersonalValue = RRInstallationFolder; 
s.roadrunner.application.InstallationFolder.TemporaryValue = RRInstallationFolder;

    Note

    Specify the full path to the folder containing the AppRoadRunner.exe executable. The default location of this executable on Windows® is C:\Program Files\RoadRunner R2022b\bin\win64, where C:\Program Files\RoadRunner R2022b is your RoadRunner installation folder. The folder could be different on your computer.

  2. To MyRoadRunnerProject from MATLAB, use this command.

    rrApp = roadrunner('MyProjectLocation');

  3. Open LaneswithMultipleActors.rrscenario scenario file.

    openScenario(rrApp,'LaneswithMultipleActors.rrscenario');

  4. Create the simulation object to control the simulation from MATLAB. 

    rrSim = createSimulation(rrApp);

  5. Start the simulation from the command line.

    set(rrSim, 'SimulationCommand','Start');

    Observe the difference in vehicle behavior because of the SpeedFactor parameter.

    The blue sedan is ahead of the white sedan based on the SpeedFactor parameter

General Considerations for Generating Ready-to-Run Actor Behaviors

Consider these factors when you generate ready-to-run actor behaviors from Simulink models using RoadRunner scenario blocks or MATLAB System blocks:

  • To generate ready-to-run actor behaviors, you must use a fixed-step solver for your model.

  • To generate a behavior for a MATLAB System object™ you must use a MATLAB System block and a RoadRunner Scenario block. Open the mUpdateXDirectionWithMATLABSys.slx model, which uses a MATLAB System block with the hUpdatePoseAlongX.m System object file.

    1. Based on your RoadRunner Scenario Reader block configuration, the block outputs a specific bus, such as BusActorRuntime. To see the bus data type, on the Debug tab, select Information Overlays, enable Bus Data Type, and update your model.

      Bus data type BusActorRuntime appears on the message line.

    2. To process this data in a MATLAB System block, use the Simulink.ActorSimulation.load function to learn bus type and the elements of the bus. For example:

      Simulink.ActorSimulation.load("BusActorRuntime");

    3. To generate code for your ready-to-run actor behavior using a MATLAB System block, you must provide a default struct data to your bus. For example, hUpdatePoseAlongX.m uses the Simulink.ActorSimulation.createMATLABStruct function to provide struct data for BusActorRuntime.

      function out = stepImpl(obj,u)
 
        % Construct default output struct
        out = Simulink.ActorSimulation.createMATLABStruct('BusActorRuntime');

        % Get ActorID
        actorSim = Simulink.ScenarioSimulation.find( ...
             'ActorSimulation','SystemObject',obj);
        actorID = getAttribute(actorSim,"ID");

        if ~isempty(u)
            pose = u(end).Pose;
            velocity = u(end).Velocity;
            displacement = velocity*obj.stepSize*obj.SpeedFactor;
    
            % Update pose
            pose(1,4) = pose(1,4) + displacement(1); % x
    
            % Update output
            out.Pose = pose;
            out.Velocity = velocity;
            out.ActorID = castIntToFi(actorID);
        end

    end

Consider these factors when you generate ready-to-run actor behaviors from MATLAB System object actor behaviors.

  • If you incorporated the getAttribute function of the ActorSimulation object, or the getAttribute function of the ActorModel object, then do not use the numel function to count the number of elements in the arrays returned by these functions. Instead, check for structure fields of array elements that specifically count the number of other array elements. For example, see the NumBulbConfiguration field of the SignalConfiguration structure in the TrafficSignalRuntime structure.

  • If you used the getAction function to read a path action, then the maximum number of path points you can read is 500.

See Also

| | |

Topics