QuIRK Documentation

BODY creates a body object for multibody simulations.
Syntax:

  bod = body(position, attitude, 'property', value, ...)

Required arguments

  position:   initial center-of-mass position of the body
  attitude:   initial quaternion rotation from the body to
                  the inertial frame

Optional properties

  inertia dbl     3x3 inertia matrix (may be derived from
                      mass and size properties) in body frame
  shape   str     [ {sphere} | ellipsoid | ball
                      | cuboid | cube | box
                      | cylinder ]
  size    str/dbl Length, width, and height in 'XxYxZ' form,
                      for example, '4x1x2', or [X Y Z]
  mass    dbl     Body mass, in kilograms
  color   str/dbl Default color of body for plots
  vel     dbl     3x1 initial velocity vector
  omega   dbl     3x1 initial angular velocity vector in body
                      coordinates
  qdot    dbl     4x1 initial quaternion derivative
  force   @fn     Force on the body CM as a function of
                      position, attitude, velocity, angular
                      velocity, and time in INERTIAL frame
  torque  @fn     Torque about the body CM as a function of
                      position, attitude, velocity, angular
                      velocity, and time in BODY frame
  data    any     User-defined data field
  time    dbl     Time, in seconds (currently mostly unused)

See also JOINT FORCE SENSOR, MBODY.

DELETE performs clean-up actions before clearing a body from 
memory.

DIAMETER provides a quick estimate of a body's physical size.
It returns the maximum of sx, sy, and sz. Syntax:

  dia = diameter(bod)
  dia = bod.diameter

See also RESIZE.

DISPLAY handles the printout of a body object when someone
types its name without ending the line in a semicolon.

DRAW adds a graphic of a body to the current axes. The 
graphic will update as this body's properties change. Syntax:

  h = draw(body, 'property', value, ...)
  h = body.draw('property', value, ...)

  body:   body to draw

Optional properties

  color   dbl/str override color of body
  alpha   dbl     Opacity of body, range 0-1
  hold    T/F     Draw on top of current graphics if true
  snap    T/F     Graphic will not update as body changes if
                      this flag is true

  Any surfaceplot property will also work.

See also GHOST, ERASE, JOINT\DRAW, MBODY\DRAW, MBODY\GHOST,
MBODY\ANIMATE.

ENERGY returns the current kinetic energy of a body
given its current mass properties and velocity. Syntax:

  K = energy(body)
  K = body.energy

See also MOMENTUM, MBODY\ENERGY, MBODY\MOMENTUM.

ERASE clears the graphical representation of a body 
from all axes, if one exists. Syntax:

  erase(body)
  body.erase

See also DRAW.

GETFORCE returns the current force vector on a body
due to force functions, objects, and potential energy. 
Syntax:

  f = getForce(body)
  f = body.getForce

This is the same as executing: 
f = bod.force(bod.pos, bod.att, bod.time);

See also GETTORQUE.

GETTORQUE returns the current torque vector on a body
due to force functions and objects. Syntax:

  f = getTorque(body)
  f = body.getTorque

This is the same as executing: 
f = bod.torque(bod.pos, bod.att, bod.time);

See also GETFORCE.

GHOST adds a graphic of a body to the current axes 
with default opacity of 10%. Refer to DRAW for options.

If a body representation already exists, ghost sets the body
opacity to 10%

  h = ghost(body, 'property', value, ...)
  h = body.ghost('property', value, ...)

See also DRAW, MBODY\GHOST.

HIGHLIGHT paints or unpaints the edges of an already-drawn
body for easy identification.

  highlight(body, color)
  body.highlight(color)

Color defaults to white if not present as an argument. You
can use HILIGHT as a shorthand.

See also DRAW, GHOST, ERASE.

MOMENTUM returns the linear and angular momentum of a body,
with its current mass properties and velocity. Syntax:

  [p H] = momentum(bod)
  [p H] = bod.momentum

p:    3x1 linear momentum vector of body
H:    3x1 angular momentum vector of body

See also ENERGY, MBODY\ENERGY, MBODY\MOMENTUM.

Q is a shorthand to return the body attitude as a quaterion. 
Use like bod.att to access the body attitude. Syntax:

  quat = bod.q
  quat = q(bod)

QDOT returns the angular velocity of the body as a quaternion
derivative. Use like bod.vel to access qdot.
Syntax:

  qd = bod.qdot
  qd = qdot(bod)

RECOMPUTEINERTIA recalculates the inertia matrix of a body 
in the body frame. Call this method if you have manually 
changed any of the body size parameters (bod.mass, bod.size, 
bod.sx, etc) and want to derive the inertia matrix from the 
new parameters. Syntax:

  body = recomputeInertia(body)
  body = body.recomputeInertia

See also RESIZE, MBODY\RECOMPUTEINERTIA.

RESIZE provides a convenient shorthand way to specify the  
spatial extent of a body.

  body = resize(body, newSize)
  body = body.resize(newSize)

  newSize:    String in 'LENGTHxWIDTHxHEIGHT' format; for
                  example, '3x1x2' changes the body to length
                  3 m along the x axis, 1 m along the y axis,
                  and 2 m along the z axis. newSize can also
				  be a 3-element vector.

See also RECOMPUTEINERTIA, DIAMETER.

SOLVE, called on a body object, returns a solved mBody that
consists only of that body, with whatever force and torque
functions it includes. See MBODY/SOLVE for full syntax and
options.

A returns the instantaneous joint constraint matrix 
for the Udwadia-Kalaba equations of motion. It determines the 
matrix numerically, based on the states of the joined bodies. 
Syntax:

  A = joint.A
  A = A(joint)

See also B.

B returns the instantaneous joint constraint vector 
for the Udwadia-Kalaba equations of motion. It determines the 
vector numerically, based on the states of the joined bodies. 
Syntax:

  b = joint.b
  b = b(joint)

See also A.

DELETE performs clean-up actions before clearing a joint from 
memory.

DISPLAY handles the printout of a joint object when someone
types its name without ending the line in a semicolon.

DRAW adds a graphic of a joint to the current axes.
Syntax:

  h = draw(joint, 'property', value, ...)
  h = joint.draw('property', value, ...)

  joint:   joint to draw

Optional properties

  color   dbl/str RGB or Matlab string specifying color of joint
  snap    lgc     Graphic will not update as joint changes if
                      this flag is true

  Any line property will also work.

See also ERASE, MBODY\DRAW.

ERASE clears the graphical representation of a joint from all
axes, if one exists. Syntax:

  erase(joint)
  joint.erase

See also DRAW.

JOINT creates a joint object between bodies for multibody
simulations. Syntax:

  jnt = joint(body1, body2, 'property', value, ...)

Required arguments

  body1:  First body to join
  body2:  Second body to join or 'ground' (overwrites all
              other joint options)

Optional properties

  type    str     [ {sphere} | sph | ball
                      | revolute | rev | hinge
                      | translation | trn | prismatic | slide
                      | cylindrical | cyl
                      | fixed | fix
                      | free | fre | none
                      | custom ]
  axis    dbl     Joint axis in BODY 1 body coordinates
                      (defaults to [0 0 1])
  pt1     dbl     Joint attachment point on body 1 in body 1
                      coordinates
  pt2     dbl     Joint attachment point on body 2 in body 2
                      coordinates
  A       dbl     Nx14 constraint matrix or function handle, 
                      required for custom joint type. 
                      Overwrites joint type with 'custom'.
                      Function handles take arguments 
                     (ri,rj,qi,qj,rid,rjd,qid,qjd,ci,cj) or
                     (thisJoint, body1, body2).
  b       dbl     Nx1 constraint vector or function handle,
                      required for custom joint type.
                      Overwrites joint type with 'custom'.
                      Function handles take arguments 
                     (ri,rj,qi,qj,rid,rjd,qid,qjd,ci,cj) or
                     (thisJoint, body1, body2).
  data    any     User-defined data field

See also BODY, FORCE, SENSOR, MBODY.

NUMCONSTRAINTS returns the number of constraint equations
represented by the joint object. Note that not all of these
constraints may be linearly independent, depending on how the
constraint matrices are expressed and the current body 
states. Syntax:

  num = numConstraints(jnt)
  num = jnt.numContraints

See also A, B.

DELETE performs clean-up actions before clearing a sensor 
from memory.

DISPLAY handles the printout of a sensor object when someone
types its name without ending the line in a semicolon.

DRAW adds a graphic of a sensor to the current axes. Sensors
appear as colored triangles; empty when untriggered and
filled when triggered. The master of the sensor family points
upwards. Syntax:

  h = draw(sensor)
  h = sensor.draw

Optional properties

  color   dbl/str Color of sensor
  snap    T/F     Graphic will not update as body changes if
                      this flag is true

See also ERASE, MBODY\DRAW.

ERASE clears the graphical representation of a sensor from
all axes, if one exists. Syntax:

  erase(sen)

See also DRAW, MBODY\ERASE.

SENSOR creates a family of sensors for use in multibody
simulations. When two sensors in the same family get within a
specified radius of one another, they can trigger the
simulation to halt. See the "sense" option of MBODY/SOLVE.
Syntax:

  sen = sensor(radius, mBody, mPosition, ...
                  sBody1, sPosition1, ..., flag)
  sen = sensor(radius, mBody, mPosition, ...
                  {sBody1, sPosition1, ...}, flag)

  sen = sensor(radius, {mBody1, mPosition1, ...}, ...
                  sBody1, sPosition1, ..., flag)
  sen = sensor(radius, {mBody1, mPosition1, ...}, ...
                  {sBody1, sPosition1, ...}, flag)

Required arguments

  body_i:     Bodies on which to place sensors
  position_i: Position of sensor from body_i CM position, in
                  body_i's body coordinates

  If you give the sensor constructor a list of bodies and
  positions, or a body/position pair and then a cell array of
  body/position pairs, then the FIRST body becomes the master 
  and all others become slaves. (First syntax shown above.)

  If you provide the sensor constructor with a cell array of
  body/position pairs BEFORE either a list of body/position
  pairs or a list in a call array, then all the bodies in the
  first cell array become masters and all other become
  slaves. (Second syntax shown above.)

  You must list at least one body with at least one
  corresponding position. (If you include only one
  body/position pair, the sensor will never trigger.)

Optional arguments

  radius  Separation between sensors in this family
              before they trigger (default = 0.1)
  'any'   If this flag is present at the end of the argument
              list, then the sensor group will operate in
              "any" mode. It will trigger when ANY sensor
              gets near any other sensor. (Default mode.)
  'm/s'   If this flag is present at the end of the argument
              list, then the sensor group will operate in
              "master/slave" mode. It will trigger when any
              master sensor gets near any slave sensor.
              (This mode evaluates faster.)

Typically, the sensor has to be tripped for two ODE timesteps
in order to halt the simulation. Tweak the radius to achieve
this.

See also TRIGGER, MBODY, MBODY/SOLVE, BODY, JOINT, FORCE.

TRIGGER queries a family of sensors to see if they have been
tripped by proximity to one another and updates their trigger
state. Syntax:

  [switched num minRange] = sensor.trigger(suppress)
  [switched num minRange] = trigger(sensor, suppress)

switched is true whenever a valid member of the sensor family
comes within proximity, measured by sensor.radius, of another
valid member of the sensor family. switched is false if the
number of sensor family members in proximity decreases or
remains the same during the call to sensor.trigger. 

num is the number of valid sensor family members within
sensor.radius of each other on the call to sensor.trigger.

The minRange output contains the minimum range between
sensors when trigger was called, minus the sensor's radius
value. It is a smooth, more well-behaved function than
switched and num for some applications.

Validity is determined by the mode of the the sensor family:

  - In 'm/s' mode, any MASTER sensor will trigger any SLAVE
    sensor. Masters cannot trigger other masters and slaves
    cannot trigger other slaves.
  - In 'any' mode, ANY sensor will trigger any SLAVE sensor.
    Master sensors never trigger each other.

Trigger will then call the function listed in the sensor's
triggerfn property, which should be a function handle that
takes the triggered sensor as an argument.

Give a non-false value for 'suppress' if you want the sensor
to skip evaluation of the triggerfn.

See also MBODY\SOLVE.

FORCE creates an inter-body force object for multibody
simulations. Syntax:

  fc = force(body1, body2, forceFn, torqueFn, frame)

Required inputs

  body1:      First body to join; force object exerts F,T on
                  this body
  body2:      Second body to join; force object exerts -F,-T
                  on this body
  forceFn:    Function handle that returns force on body1
                  (body2 experiences reaction -force). Should
                  take arguments (body1, body2, time).
  torqueFn:   Function handle that returns torque on body1
                  (body2 experiences reaction -torque).
                  Should take arguments (body1, body2, time).
  frame:      choose one of the following:
                  0, 'N', 'inertial' (default)
                  1, 'B1', 'body1'
                  2, 'B2', 'body2'

See also SPRING, BODY, JOINT, SENSOR, MBODY.

DISPLAY handles the printout of a force object when someone
types its name without ending the line in a semicolon.

GETFORCE returns the current force vector of the force
object, applied to body 1.

See also GETTORQUE.

GETTORQUE returns the current torque vector of the force
object, applied to body 1.

See also GETFORCE.

SPRING creates spring-damper force object for multibody
simulations. Syntax:

  spr = spring(body1, body2, K, C, length, frame)

  body1: 	First body to join
  body2: 	Second body to join
  K:  	Linear stiffness value or matrix. Choose one:
            	- Scalar radial stiffness value
              Not yet implemented:
            	- 2-elem vector of translation stiffness, torsion stiffness
            	- 3x3 translation stiffness matrix
            	- 6x6 stiffness matrix
  C:   	Linear damping value or matrix. Choose one:
           	- Scalar relative damping value
              Not yet implemented:
            	- 2-elem vector of translation damping, torsion damping
            	- 3x3 translation damping matrix
            	- 6x6 damping matrix
  length: Equilibrium length of spring. Choose one:
              - Scalar equilibrium distance
              Not yet implemented:
              - 3-elem translation equilibrium vector
              - 6-elem transtation and rotation equilibrium vector
  frame:	Relevant if stiffness or damping has been given as a 
              matrix. Choose one of the following:
              - 0, 'N', 'inertial' (default)
              - 1, 'B1', 'body1'
            	- 2, 'B2', 'body2'

See also FORCE.

ADD puts more bodies, joints, etc into the multibody system.
If the system has previously been solved, add assumes that
the new objects should be added at the most recent time in
the system state history. Use SETNOW or RESET before adding
if this is not the case. Syntax:

  mbody = add(mbody, body, joint, force, ...)
  mbody = mbody.add(body, sensor, joint, ...)

You can list any number of body, sensor, force, and joint
objects, in any order. If you add joints, forces, or sensors 
that refer to the bodies you add, then the bodies should be
listed first.

See also REMOVE, SETTIME, SETNOW, RESET.

ANIMATE animates the motion of a solved multibody system
in the current axes. Syntax:

  animate(mBody, 'property', value, ...)
  mBody.animate('property', value, ...)

Required arguments

  mBody:   multibody system to animate

Optional properties

  tspan   int     Time vector at which to start and stop the
                      animation: [start stop]
  speed   dbl     Playback speed of the animation, with 1
                      being real-time (default). Zero, Inf,
                      or NaN will result in the animation
                      playing at maximum speed (slower where
                      there are more integration points, etc)
  color   dbl/str RGB or Matlab string specifying color of
                      bodies (overrides body colors)
  alpha   dbl     Opacity of bodies, range 0-1
  axis    dbl/str Any input you would typically give to the
                      MATLAB axis command, applied to every
                      frame of the animation. E.g. 'normal',
                      'equal', or a 6-element axis limit
                      vector. Default is 'equal'.
  lit     T/F     Light bodies if true
  hold    T/F     Draw on top of current graphics if true
  bg      dbl/str Override background color of figure and
                      axes
  filename        If present, save movie with indicated file
                      name in working directory. Extention
                      defaults to avi (don't include '.avi'
                      in filename).

  Any surfaceplot property will also work.

See also DRAW, GHOST, TRACE, ERASE, BODY\DRAW.

CHECKCOLLISIONS performs a weak test for collisions on an 
mBody system. It tests the distance between each pair of 
bodies against the sum of the minimum sizes (sx, sy, and sz) 
of those two bodies. Syntax:

  collided = checkCollisions(mBody)
  collided = mBody.checkCollisions

CHECKORPHANS sees if there are any sensors or joints with a
body that is not a member of this multibody system, and
prints the names of those objects if they exist. Syntax:

  checkOrphans(mbody)
  mbody.checkOrphans

See also REMOVE, ADD.

CM returns the center-of-mass position of the mBody.
Syntax:

  cmPos = mBody.cm

DELETE performs clean-up actions before clearing an mBody
from memory.

DISPLAY handles the printout of an mBody object when someone
types its name without ending the line in a semicolon.

DRAW adds a graphical representation of a multibody system to
the current axes. The graphics will update as this mBody's
properties change. Syntax:

  h = draw(mBody, 'property', value, ...)
  h = mBody.draw('property', value, ...)

Required arguments

  mBody:   multibody system to draw

Optional properties

  time    int     Index in time vector at which to draw
                      the system. If not specified, draws
                      each body at last specified time.
  state   dbl     State vector at which to draw the mBody.
                      This should be a vector with either
                      7*numBodies or 14*numBodies elements.
                      (Velocity states will be ignored.)
  color   dbl/str RGB or Matlab string specifying color of
                      bodies.
  alpha   dbl     Opacity of bodies, range 0-1.
  hold    T/F     Draw on top of current graphics if true.
  lit     T/F     Light the mBody graphic.
  snap    T/F     Graphic will not update as mBody changes if
                      this flag is true. Good for making many
                      plots at intermediate steps.
  filename        If present, uses print2im to save image 
                      with indicated file name in working 
                      directory. If no extension, defaults to
                      png.

  Any surface property will also work.

See also GHOST, ERASE, ANIMATE, TRACE, BODY\DRAW.

ENERGY returns the current kinetic energy of a multibody
system and potential energy if the mBody object has a
potential energy function. Syntax:

  [K U] = energy(mBody)
  [K U] = mBody.energy

See also PLOTENERGY, MOMENTUM, PLOTMOMENTUM, BODY\ENERGY.

ERASE clears the graphical representation of a mBody from all
axes, if one exists. Syntax:

  erase(mBody)
  mBody.erase

See also DRAW.

FINDEQ locates the equilibrium state of a multibody system
to the precision of mBody.thresh. It proceeds from the
current state of the mBody and simulates until the system
reaches equilibrium. Then it restores the previous state
information of the mBody. Syntax:

  x0 = mbod.findeq('property', value, ...)
  x0 = findeq(mbod, 'property', value, ...)

x0 is the full system state at equilibrium.

Optional arguments:

  mode    'v'/'f' Choose 'v' to have findeq stop searching
                      when the system has zero velocity.
                      Choose 'f' to stop when the system
                      experiences zero force along virtual
                      displacements. 'f' by default.
  chunk   dbl     Length of time each sub-simulation should
                      go for. Smaller chunks are slower
                      overall, but more robust. Defaults to 5
                      seconds.
  tLim    dbl     Limit on how far findeq should simulate
                      before giving up. Defaults to Inf.
  debug   T/F     If true, produces a plot of system energy
                      at each attempt to find equilibrium.
					  
Any other input goes to mBody/solve.

See also SOLVE.

GHOST adds a graphical representation of a multibody system
to the current axes with default opacity of 10%. This is good
for seeing through systems of many bodies. Refer to DRAW for
a list of full options.

  h = ghost(mBody, 'property', value, ...)
  h = mBody.ghost('property', value, ...)

See also DRAW, ERASE, ANIMATE, TRACE.

MBODY creates a multibody object for simulations. Syntax:

  mbod = mBody(bodies, ..., joints, ..., sensors, ...,
                  forces, ..., 'property', value, ...)

List bodies, joints, forces, and sensors, in any order, 
followed by property/value pairs.

Optional properties

  damping dbl     Damping coefficient to apply to all bodies.
  force   @fn     Force on ALL body centers of mass as a
                      function of position, attitude,
                      velocity, angular velocity, and time.
                      Adds to individual body forces. E.g.,
                      'force', @(x,q,v,w,t) ( -4*x - 2.5*v )
                      is a simple spring-damper. Force
                      matrices should be in INERTIAL frame.
  torque  @fn     Torque about ALL body centers of mass as a
                      function of position, attitude,
                      velocity, angular velocity, and time.
                      Adds to individual body forces. Torque
                      matrices should be in BODY frame.
  U       @fn     Potential energy function applied to the
                      entire system, which then experiences a
                      force -grad(U), as a function of either
                      (position, time) or a body object.
  thresh  dbl     Threshhold on equilibrium detection in
                      integration (defaults to 3e-3).
  data    any     User-defined data field

See also BODY, JOINT, FORCE, SENSOR.

MOMENTUM returns the current linear and angular momentum of a
multibody system. Syntax:

  [p H] = momentum(mBody)
  [p H] = mBody.momentum

p:    total linear momentum vector of mBody
H:    total angular momentum vector of mBody

See also ENERGY, PLOTMOMENTUM, BODY\MOMENTUM.

OVERWRITESTATE copies a new matrix into the state history of
the multibody system. To be safe, you should only do this
with a state extracted from a multibody system with the same
number of bodies (or, preferably, the same bodies).

  mBody = overwriteState(mBody, t, x)
  mBody = mBody.overwriteState(t, x)

Required arguments

  t:  Time vector.
  x:  State vector history. This should be a matrix with
          14*numBodies rows in the form
              [body1Pos; body1Quat; ...;
                  body1Vel; body1QDeriv; ...],
          and length(t) columns.

If you just want to display the multibody system at a
particular state, but don't want to overwrite the state
history, try using mBody.draw('state', x).

See also RESET, SETTIME, SETNOW, SOLVE.

PLOTENERGY displays a plot of the total kinetic energy of a
multibody system. It is most useful after the system has been
solved. If the mBody has a potential energy function, the
value of that function is also plotted. Syntax:

  [K U] = plotEnergy(mBody)
  [K U] = mBody.plotEnergy

K and U are vectors with one entry per element of the time
vector kept in mBody.t.

See also PLOTPOWER, PLOTMOMENTUM, ENERGY, BODY\ENERGY.

PLOTMOMENTUM displays a plot of the linear and angular
momentum magnitudes of a multibody system. It is most useful
after the system has been solved. Syntax:

  [p H] = plotMomentum(mBody)
  [p H] = mBody.plotMomentum

p and H are vectors with one entry per element of the time
vector kept in mBody.t.

See also PLOTENERGY, MOMENTUM, BODY\MOMENTUM.

PLOTPOWER displays a plot of the total power applied to a
multibody system. It is most useful after the system has been
solved. Syntax:

  P = plotPower(mBody)
  P = mBody.plotPower

P is a vector with one entry per element of the time vector
kept in mBody.t.

See also PLOTENERGY, PLOTMOMENTUM, ENERGY, BODY\ENERGY.

RECOMPUTEINERTIA recalculates the inertia matrix of all
bodies in their body frames. Call this method if you have
manually changed any of the body size parameters (bod.mass,
bod.size, bod.sx, etc) and want to derive the inertia
matrices from the new parameters. Syntax:

  mbody = recomputeInertia(mbody)
  mbody = mbody.recomputeInertia

See also BODY\RECOMPUTEINERTIA, BODY\RESIZE.

REMOVE takes bodies, joints, etc. out of the multibody
system. If the system has previously been solved, it assumes
that the objects should be removed at the most recent time
in the system state history. Use SETNOW or RESET before
removing if this is not the case. Syntax:

  mbody = remove(mbody, body, joint, sensor, ...)
  mbody = mbody.remove(body, sensor, joint, ...)

You can list any number of body, sensor, and joint objects,
in any order. Be careful when removing objects with
dependencies that you do not leave any orphans (for example,
removing one body connected to a joint without removing the
joint). After removing objects, remove will automatically
perform an orphan check.

See also ADD, SETTIME, SETNOW, RESET, CHECKORPHANS.

RESET brings a multibody system back to its initial state.
Use before adding/removing objects and re-solving. Syntax:

  mbody = reset(mbody)
  mbody = mbody.reset

Both commands produce the same result as mbody.settime(1)
followed by mbody.setnow.

See also SETTIME, SETNOW, SOLVE.

SETNOW clears the state history of a multibody system and
tells it that the current state of each object is the current
state of the system. Use after adding/removing/editing 
objects and before re-solving. Syntax:

  mbody = setnow(mbody)
  mbody = mbody.setnow

Be careful not to confuse this command with SETTIME without
arguments.

See also SOLVE, RESET, SETTIME.

SETTIME brings a multibody system to its state at a
particular time value. Syntax:

  mbody = settime(mbody, time)
  mbody = mbody.settime(time)

Optional arguments:

  time:	Index into time vector. Defaults to end.

See also RESET, SETNOW.

SOLVE calculates the state time history of a multibody system
using the Udwadia-Kalaba equations of motion. You must call
solve on a multibody system before animating it. Syntax:

  mbody = solve(mbody, tspan, property, value, odeOpts)
  mbody = mbody.solve(tspan, property, value, odeOpts)

Once solved, the mBody object will retain its state history
for further plotting commands, interrogation of its energy
and momentum, and further manipulation. However, some
manipulations of the mBody object or its constituent
components will require re-solving the mBody.

Required arguments

  tspan:	ODE45 timespan vector, [start end] or [start:end]

Optional properties

  sense   T/F,int Set this property to true to have the
                      simulation terminate if any sensors
                      trigger. Specify an integer to have the
                      simulation terminate if that number of
                      sensors trigger.
  stop    str     State conditions on which to terminate
                      solution. You may supply the 'stop'
                      keyword multiple times to specify more
                      than one condition. Available options:
                      'velocity'  Stop solution when the 
                                  bodies have near-zero
                                  velocity.
                      'force'     Stop solution when the 
                                  bodies have near-zero force
                                  applied in the direction of
                                  virtual displacements.
                      'collision' Stop when checkCollisions 
                                  returns true.
                      numeric     Stop integration after the 
                                  specified number of seconds
                                  (real time).
  solver  str     Follow this property with a string
                      containing the name of any ode solver,
                      for example 'ode45' or 'ode15s'.
                      (Use 'ode4f' and a vector of explicit
                      time steps for fixed-step integration.)
  tidy    T/F     Set this property to true to instruct
                      solve to perform extra tidying-up
                      operations on the system state as it
                      integrates (slower, but produces
                      cleaner, more robust integration). Good
                      for long solutions.
  msg     str    Set to 'none' to prevent solve from
                      printing output messages. Defaults to
                      'full'.
  odeOpts	struct  ode45 options structure from odeset
                      (e.g. odeset('OutputFcn', @odeplot) )

See also RESET, SETTIME, SETNOW, ANIMATE, PLOTENERGY,
PLOTMOMENTUM, UNSOLVE.

TRACE ghosts a graphical representation of a multibody system
through its motion with default opacity of 10%, and opacity
of 50% in its final configuration. Syntax:

  trace(mBody, 'property', value, ...)
  mBody.trace('property', value, ...)

  mBody:   multibody system to trace

Optional properties

  tspan   int     Indices in time vector at which to start
                      and stop the animation: [start stop]
  steps   int     Number of intermediate steps to illustrate
  color   dbl/str RGB or Matlab string specifying color of body
  alpha   dbl     Override opacity of body

See also DRAW, ERASE, ANIMATE, TRACE.

VIRTUALDISP returns the virtual displacement vectors of the
mBody at its current state. These are the directions in which
the system can move (at the current time). Syntax:

  w = mbod.virtualDisp

VIRTUALWORK returns the total virtual work on the mBody at
its current state. It is a measure of how much force is
acting on the mBody in directions that are compatible with
the system constraints. Syntax:

  W = mbod.virtualWork