SimMechanics™

mech_stateVectorMgr - Create machine state vector manager object

Syntax

mech_stateVectorMgr

Synopsis

mech_stateVectorMgr returns a data structure of MECH.StateVectorMgr class. It does not return actual state values. You can subsequently assign values to the states in this object, but these values do not propagate to your model. That requires changing the mechanical part of the model's Simulink^® state vector.

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

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

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)

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

Description

Excluding any motion-actuated joint primitives, the total number of mechanical state components is

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

The machine state consists of all the translational and 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.

• A joint primitive actuated by a Joint Initial Condition Actuator (JICA) is counted like other joint primitives. Because the JICA externally specifies such a primitive's initial position and velocity, the primitive has an active FixedAtT_0 flag.

• Point-Curve Constraints each have one predictor state component, the arc parameter velocity of the point along the curve.

Joint Primitives Not Counted As Degrees of Freedom

• If the joint primitive is motion actuated with a Joint Actuator block, that joint primitive is not counted in the machine state components.

• The weld primitive contributes no state components.

Input Arguments

There is one input argument, a SimMechanics block's full pathname or handle, or an indirect call to the pathname or handle using the commands gcb or gcbh. The full path name starts with the model name and continues through any subsystem hierarchy:

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

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

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

mech_stateVectorMgr(gcb)
mech_stateVectorMgr(gcbh)

Output Arguments

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. This root serves as a proxy for the whole machine.

The output of mech_stateVectorMgr is an object of the MECH.StateVectorMgr class associated with a particular machine.

The returned object has four properties. Three are fixed by the machine structure and naming. You can change the values in the fourth, X, but these values do not propagate to the model. Consult See Also following for more about changing a model's mechanical state vector values.

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

• The MachineState.X property indicates the number of state components.

• The block state managers of BlockStates are structures, arranged in the array by class: MECH.RPJointStateMgr, MECH.SJointStateMgr, and MECH.PointCurveStateMgr. The components of each manager contain:

  • The joint block and prismatic, revolute, and spherical primitive names

  • The position and velocity values and units

  • The FixedAtT_0 flag indicating if the primitive is actuated with initial conditions

• StateNames is a structure of state name strings. They are grouped and ordered in the same way that the block state managers of BlockStates are.

  SimMechanics names the mechanical states in a model. Simulink recognizes and uses these SimMechanics state names.

Using the State Manager Object

Once you create a state vector manager object, you can query the properties individually by entering the full property name:

MachineState.MachineName
MachineState.X

The state vector manager object is a singleton. If you create the object in A, then reassigning B = A makes A and B point to each other, not independent copies. Changing B automatically changes A and vice versa.

Examples

Some examples illustrate the use of the state vector manager.

Mechanical State Vector with One Primitive

Open the demo model mech_spen. Select a SimMechanics block 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).

Query individual properties. Entering machinestate.machinename returns

mech_spen/Ground

referring to the one Ground block in the model. Entering machinestate.X returns a two-component state vector (N = 2, position and velocity).

0     0

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 (a Revolute) and no Point-Curve Constraints, 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 absence of initial condition actuators.

Entering machinestate.statenames returns the names of the Joint block, the joint primitive, and the states.

'Revolute:R1:Position'
'Revolute:R1:Velocity'

Mechanical State Vector with 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 associated with its Ground block and has a spherical and a prismatic primitive, 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

To change actual mechanical state values, consult these commands: mech_get_states, mech_runtime_states, mech_set_states, mech_transfer_states

Point-Curve Constraint, Prismatic, Revolute, Spherical

See the Representing Motion chapter.

See Counting Degrees of Freedom.

See Trimming Mechanical Models and Linearizing Mechanical Models.

In Simulink, see gcb, gcbh, gcs.

mech_set_states

mech_transfer_states