SerialPhase

Specify options for customizing logic phase that executes child phases sequentially

Since R2025a

Description

A SerialPhase object represents a serial logic phase in the RoadRunner scenario logic . Serial phases execute their child phases sequentially during simulation.

Creation

You can create a SerialPhase object in these ways:

• The addPhaseInParallel function creates a phase with the specified type and adds it in parallel to the specified existing phase or serial sequence of phases in the RoadRunner scenario logic. Specify the phaseType argument as "SerialPhase" to create a SerialPhase object.

• The addPhase function creates a new phase of the specified type and adds it as the last child of the specified parallel phase in the RoadRunner scenario logic. Specify the phaseType argument as "SerialPhase" to create a SerialPhase object.

Note

You cannot specify a serial phase as a child of another serial phase.

Properties

Name — Name of phase

"" (default) | string scalar | character vector

Name of the phase, specified as a string scalar or character vector.

Note

You can specify the Name property of SerialPhase in MATLAB^®, but RoadRunner Scenario does not display the Name property of serial phases in the user interface.

ChildPhases — Child phases of phase

[] (default) | array of ActorActionPhase objects | array of SystemActionPhase objects | array of ParallelPhase objects

Child phases of the phase, specified as an array of one of these types of objects:

• ActorActionPhase — Represents an actor action phase in the RoadRunner scenario logic.

• SystemActionPhase — Represents a logic phase in the RoadRunner scenario logic that executes actions without an actor.

• ParallelPhase — Represents a parallel logic phase in the RoadRunner scenario logic that executes child phases concurrently during simulation.

Note

You must specify a nonempty value for this property before you can run the simulation.

ParentPhase — Parent phase

Read-only: ParallelPhase object

This property is read-only.

Parent phase, represented as a ParallelPhase object. RoadRunner Scenario returns an empty object if this phase has no parent phase.

EndCondition — Condition to trigger phase completion

[] (default) | ActorSpeedCondition object | DurationCondition object | CollisionCondition object | PhaseStateCondition object | DistanceToActorCondition object | DistanceToPointCondition object | LongitudinalDistanceToActorCondition object

Condition to trigger phase completion, specified as one of these objects:

• ActorSpeedCondition — Represents an Actor Speed condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches the specified speed.

• DurationCondition — Represents a Duration condition in the RoadRunner scenario logic. Specifies for the associated phase to end after the specified amount of time elapses.

• CollisionCondition — Represents a Collision condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor specified by FirstActor collides with the actor specified by SecondActor.

• PhaseStateCondition — Represents a Phase State condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the referenced phase reaches the specified state.

• DistanceToActorCondition — Represents a Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor is a certain distance away from the reference actor.

• DistanceToPointCondition — Represents a Distance To Point condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor is a certain distance away from a specified point.

• LongitudinalDistanceToActorCondition — Represents a Longitudinal Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches a certain longitudinal distance from another actor.

If any actions are still executing when the condition triggers, RoadRunner Scenario ends those actions early.

FailCondition — Condition to fail scenario execution

[] (default) | ActorSpeedCondition object | DurationCondition object | CollisionCondition object | PhaseStateCondition object | DistanceToActorCondition object | DistanceToPointCondition object | LongitudinalDistanceToActorCondition object

Condition to fail scenario if triggered during phase execution, specified as one of these objects:

• ActorSpeedCondition — Represents an Actor Speed condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches the specified speed.

• DurationCondition — Represents a Duration condition in the RoadRunner scenario logic. Specifies for the associated phase to end after the specified amount of time elapses.

• CollisionCondition — Represents a Collision condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor specified by FirstActor collides with the actor specified by SecondActor.

• PhaseStateCondition — Represents a Phase State condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the referenced phase reaches the specified state.

• DistanceToActorCondition — Represents a Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when the actor is a certain distance away from the reference actor.

• DistanceToPointCondition — Represents a Distance To Point condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor is a certain distance away from a specified point.

• LongitudinalDistanceToActorCondition — Represents a Longitudinal Distance To Actor condition in the RoadRunner scenario logic. Specifies for the associated phase to end when an actor reaches a certain longitudinal distance from another actor.

Examples

Add Serial Phase to Scenario Logic

Use addPhaseInParallel to create a serial phase object for your scenario.

This example assumes that you have prior knowledge of working with RoadRunner in MATLAB. Before proceeding, follow the steps outlined in Set Up MATLAB Environment for RoadRunner Authoring Functions to set up your scenario using MATLAB functions for scenario authoring.

Add Serial Phase to Scenario Logic

Use addPhaseInSerial to add a new actor action phase, newPhase, in serial after the initial phase of the actor, and specify the Actor property as car. Then, use addAction to specify the action type of the new phase as "ChangeSpeedAction".

newPhase = addPhaseInSerial(rrLogic,initPhase,"ActorActionPhase",Insertion="after");
newPhase.Actor = car;
chSpd = addAction(newPhase,"ChangeSpeedAction");
chSpd.Speed = 30;

To create an object, srPhase, that represents a serial phase in your RoadRunner scenario, use addPhaseInParallel and specify the phaseType argument as "SerialPhase" to add a new serial phase in parallel to newPhase in the RoadRunner scenario logic. You must add the serial phase in parallel to the existing phase because serial phases cannot be children of serial phases.

srPhase = addPhaseInParallel(rrLogic,newPhase,"SerialPhase");

By default, serial phases do not contain any action phases. Use addPhase to add an actor action phase to the serial phase srPhase. Then, use addAction to specify an action type.

By specifying a serial phase as the parent phase when using the addPhase function, you can quickly add new action phases sequentially to your scenario logic without specifying their positions relative to existing phases. By default, addPhase adds the new phase to the end of the specified serial phase sequence.

actionPhase = addPhase(srPhase,"ActorActionPhase");
actionPhase.Actor = car;
chLn = addAction(actionPhase,"ChangeLaneAction");
chLn.Direction = "right";

Run the simulation by using the simulateScenario function.

simulateScenario(rrApp)

Version History

Introduced in R2025a