mech_stateVectorMgr

Create machine state vector manager object

Syntax

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

Description

MachineState = mech_stateVectorMgr('pathname') returns a data structure of MECH.StateVectorMgr class, starting from the path name of any SimMechanics™ block in the machine whose state you want.

MachineState = mech_stateVectorMgr('handle') returns a data structure of MECH.StateVectorMgr class, the handle of any SimMechanics block in the machine whose state you want.

MachineState = mech_stateVectorMgr(gcb) returns a data structure of MECH.StateVectorMgr class, starting with an indirect call to the block path name of a selected SimMechanics block in your machine.

MachineState = mech_stateVectorMgr(gcbh) returns a data structure of MECH.StateVectorMgr class, starting with an indirect call to the block handle of a selected SimMechanics block in your machine.

The data structure returned by mech_stateVectorMgr exposes the structure of the machine's mechanical state vector.

Input Arguments

mech_stateVectorMgr accepts one input.

pathname

A SimMechanics block's full path name or handle, or an indirect call to the path name or handle.

  • Specify the full path name starting with the model name and continuing through any subsystem hierarchy: pathname = modelname/subsystem1/etc.../blockname.

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

  • Combine the previous steps into one with an indirect path name or handle call. Select a SimMechanics block in the model window and enter the function passing gcb or gcbh as the input.

Output Arguments

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

The returned object has four properties, fixed by the machine structure and naming.

MachineState.MachineName

A string specifying the path to the root Ground block: 'modelname/subsystem1/etc.../rootgroundblock'.

MachineState.X

A 1-by-N real array with value [ 0 0 ... 0 ]. The length of the vector indicates the number of state components.

You can change the values of this array's components, but these values do not propagate to the model.

MachineState.BlockStates

An array of N block state managers, containing the Joint primitive and Point-Curve Constraint states. These managers 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

MachineState.StateNames

A cell array of N strings, containing the names of joint primitives and Point-Curve Constraints. This structure's strings are grouped and ordered in the same way that the block state managers of BlockStates are.

Querying the Mechanical State Vector

Entering the mech_stateVectorMgr function or querying the entire object returns a summary of the object by property. Once you create a state vector manager object, you can query these 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.

Changing Values of Mechanical States

This data structure does not contain 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. Consult mech_get_states, mech_runtime_states, mech_set_states, and mech_transfer_states about changing a model's mechanical state vector values.

Examples

Mechanical State Vector with One Primitive

Open the example model mech_spenmech_spen, select a SimMechanics block, and enter:

machinestate = mech_stateVectorMgr(gcb)

at the command line. The function 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. For example, enter machinestate.machinename. The structure returns

mech_spen/Ground

referring to the one Ground block in the model.

Enter machinestate.X. The structure returns a two-component state vector (N = 2, position and velocity):

0     0

Enter machinestate.blockstates. The structure returns

MECH.RPJointStateMgr
        BlockName: 'Revolute'
        Primitive: 'R1'
         Position: 0
    PositionUnits: 'rad'
         Velocity: 0
    VelocityUnits: 'rad/s'
       FixedAtT_0: 'off'

There is 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.

Enter machinestate.statenames. The structure 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.

More About

expand all

Machines

A machine is a connected set of SimMechanics blocks.

Mechanical State Vector and Simulink State Vector

The data structure returned by mech_stateVectorMgr includes only the states of a machine made of SimMechanics blocks.

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

Algorithms

Counting Machine State Vector Components

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

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

The machine state consists of translational and angular positions and velocities of these degrees of freedom (DoFs) in the machine:

  • If uncut, prismatic and revolute joint primitives each contribute two state components, a position and a velocity.

  • If uncut, spherical joint primitives each contribute 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 contribute one predictor state component, the arc parameter velocity of the point along the curve.

Some Joint Primitives Not Counted for Mechanical States

  • The joint primitives of a cut Joint in a closed loop are not counted in the machine state.

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

  • The weld primitive contributes no machine state components.

Distinguishing Independent States and Degrees of Freedom

Not all the machine states have to represent independent DoFs.

Closed Loops and Dependent States

The number of independent DoFs is reduced by:

  • Constraint and Driver blocks, which must occur in closed loops

  • Additional constraints arising from cut joints in closed loops

In such cases, some of the machine states are dependent.

Open Topology, Constraint-Free Machines

If the machine contains no closed loops, and thus no cuts, Constraints, or Drivers, the machine states and independent DoFs are identical.

Was this topic helpful?