SimMechanics

mech_stateVectorMgr

Display and set the machine state with a state vector manager

Synopsis

You must call mech_stateVectorMgr with one argument, the pathname or handle of any block in the machine whose state you want:

• MachineState = mech_stateVectorMgr('pathname')
  MachineState = mech_stateVectorMgr('handle')
  

You obtain the pathname and handle with the Simulink gcb and gcbh commands.

You can also call mech_stateVectorMgr with an indirect call to the block pathname or handle. Select one of the SimMechanics blocks in the machine and enter one of these commands:

• MachineState = mech_stateVectorMgr(gcb)
  MachineState = mech_stateVectorMgr(gcbh)
  

The command mech_stateVectorMgr returns an object MachineState.

The state manager object includes only the state of a machine made of SimMechanics blocks. Simulink associates the machine to one of the machine's Ground blocks.

Description

The state of the machine is its kinematic state.

The kinematic state consists of all the linear/angular positions and velocities of all degrees of freedom (DoFs) in the machine:

• Prismatic and revolute joint primitives each have two state components, a position and a velocity.
• Spherical joint primitives each have eight state components, a quaternion and a quaternion derivative.
• Point-Curve Constraints each have one predictor state component, the arc parameter velocity of the point along the curve.
• If the joint primitive is motion actuated with a Joint Actuator block, that joint primitive loses its state components.
• The weld primitive W also has no state.

The total number of state components is

N = 2*(# of prismatics + # of revolutes) + 8*(# of sphericals)
    + (# of Point-Curve Constraints),

not including any motion-actuated joint primitives.

Input Arguments

There is one input argument. The argument must be a SimMechanics block's full pathname or handle, or an indirect call to the pathname or handle using the commands gcb or gcbh.

The input block name or handle must refer to a SimMechanics block. The state manager created by the command references the machine to which this block belongs. The full path name starts with the model name and continues through any subsystem hierarchy:

• pathname = modelname/subsystem1/etc.../blockname
  

You can obtain the pathname or handle of any block by selecting that block in a window and entering gcb or gcbh at the command line.

You can combine these steps into one step with an indirect pathname or handle call. Select a SimMechanics block in the model window and enter either command:

• mech_stateVectorMgr(gcb)
  mech_stateVectorMgr(gcbh)
  

instead.

Output Arguments

The output of mech_stateVectorMgr is an object MachineState of class MECH.StateVectorMgr.

A machine is a connected set of SimMechanics blocks. Each machine must have at least one Ground block. Simulink chooses one of the Ground blocks as the machine root. The state vector manager object refers to this root as a proxy for the whole machine.

The MachineState object has four properties.

Property	Variable Type	Content
MachineState.MachineName	string	'modelname/subsystem1/etc.../rootgroundblock'
MachineState.X	1-by-N real array	[ 0 0 ... 0 ]
MachineState.BlockStates	array of N block state managers	Joint primitives and Point-Curve Constraints
MachineState.StateNames	cell array of N strings	Names of joint primitives and Point-Curve Constraints

Entering the mech_stateVectorMgr command or querying the entire object returns a summary of the object contents by property.

The MachineState.X property does not show the actual machine state, but only indicates the number of state components.

The block state managers of BlockStates are arranged in the array by class: MECH.RPJointStateMgr, MECH.SJointStateMgr, and MECH.PointCurveStateMgr.

Querying the State Manager Object

Once you define a MachineState object, you can query the properties individually by entering full property name:

• MachineState.MachineName
  MachineState.X
  

Examples

Some examples illustrate the use of the state vector manager.

State Vector Manager Example: One Primitive

Open the model mech_spen in the Demos library. Select one of the SimMechanics blocks and enter

• machinestate = mech_stateVectorMgr(gcb)
  

at the command line. The command returns

machinestate =

    MECH.StateVectorMgr

MachineName: 'mech_spen/Ground'

X: [0 0]

BlockStates: [1x1 MECH.RPJointStateMgr]

StateNames: {2x1 cell}

The first line in the object is the class and the last four are the properties. The model mech_spen contains one Joint block (a Revolute), with two states (angle and angular velocity).

Now query individual properties. Entering machinestate.machinename returns

• mech_spen/Ground
  

referring to the one Ground block in the model. Entering machinestate.X returns

• 0     0
  

indicating a two-component state vector (N = 2).

Entering machinestate.blockstates returns

    MECH.RPJointStateMgr

BlockName: 'Revolute'

Primitive: 'R1'

Position: 0

PositionUnits: 'rad'

Velocity: 0

VelocityUnits: 'rad/s'

FixedAtT_0: 'off'

There are one Joint and no Point-Curve Constraints, and the Joint is a Revolute. So there is only one state manager of class MECH.RPJointStateMgr. This property gives detailed Joint information: block name, primitive name, position and velocity values and units, and the presence or absence of initial condition actuators.

Entering machinestate.statenames returns

'Revolute:R1:Position'

'Revolute:R1:Velocity'

the names of the Joint block, the joint primitive, and the states.

State Vector Manager Example: Multiple Primitives

Construct an unnamed model with Ground and Body blocks connected by a Telescoping Joint. Then select one of the blocks and enter machinestate = mech_stateVectorMgr(gcb) at the command line. Simulink returns

machinestate =

    MECH.StateVectorMgr

MachineName: 'untitled/Ground'

X: [0 0 0 0 0 0 0 0 0 0]

BlockStates: [2x1 MECH.BlockStateMgr]

StateNames: {10x1 cell}

The unnamed model is still associated with its Ground block. There are two primitives, a spherical and a prismatic, and hence 10 components in the state vector. To see those primitive names, enter machinestate.statenames to obtain

'Telescoping:S:Quaternion:1'

'Telescoping:S:Quaternion:2'

'Telescoping:S:Quaternion:3'

'Telescoping:S:Quaternion:4'

'Telescoping:P1:Position'

'Telescoping:S:Quaternion_dot:1'

'Telescoping:S:Quaternion_dot:2'

'Telescoping:S:Quaternion_dot:3'

'Telescoping:S:Quaternion_dot:4'

'Telescoping:P1:Velocity'

The quaternion and the prismatic position make the first five components, while the quaternion derivative and prismatic velocity make the last five.

See Also

Point-Curve Constraint, Prismatic, Revolute, Spherical

See Counting Degrees of Freedom.

See Trimming Mechanical Systems and Linearizing SimMechanics Models.

In Simulink, see gcb, gcbh, gcs.

SimMechanics Command Reference

Glossary