=============================
MbdLoads (hwx.inspire.motion)
=============================

Loads (forces, torques, accelerations) from an MbdAnalysis that are
applied to a part (parts if in a Rigid Group or ground) at specified
time steps.

The forces will sum to 0 at each time step.  They are used to create
load cases for Inspire FE Optimize & Analyze.

Generate loads for part using the current MbdAnalysis
loads = MbdLoads (part)

Filter loads to contain peak force time steps between 1 and 10 seconds
peaks = loads.timeSlice(1, 10).peaks ()

Add in every 5 time steps
loads = loads[::5] + peaks

Generate load cases, write to csv
loads.createLoadCases ()
loads.writeCsv ('test.csv')

--------------
Public Methods
--------------

  +------------------------------------------------------------------------------------------------------------------+
  | analyzePart_ (self, sumAtRegion=False, params={}, runOptions={})                                                 |
  +------------------------------------------------------------------------------------------------------------------+
  | copy_ (self, items=None)                                                                                         |
  +------------------------------------------------------------------------------------------------------------------+
  | countLoadCases_ (self, **kwds)                                                                                   |
  +------------------------------------------------------------------------------------------------------------------+
  | createLoadCases_ (self, deactivateRest=False, **kwds)                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | evenlySpaced_ (self, numSamples, includeBounds=True)                                                             |
  +------------------------------------------------------------------------------------------------------------------+
  | filter_ (self, filter)                                                                                           |
  +------------------------------------------------------------------------------------------------------------------+
  | getChannels_ (self, load, components)                                                                            |
  +------------------------------------------------------------------------------------------------------------------+
  | optimizePart_ (self, sumAtRegion=False, params={}, runOptions={})                                                |
  +------------------------------------------------------------------------------------------------------------------+
  | peaks_ (self, peaksPerComp=5, components='FX FY FZ FM TX TY TZ TM', forceThreshold=1e-05, torqueThreshold=0.001) |
  +------------------------------------------------------------------------------------------------------------------+
  | timeSlice_ (self, start=None, end=None)                                                                          |
  +------------------------------------------------------------------------------------------------------------------+
  | writeCsv_ (self, file, wrtDesignPos=False)                                                                       |
  +------------------------------------------------------------------------------------------------------------------+

--------------
Method Details
--------------

.. _analyzePart:
.. method:: analyzePart(self, sumAtRegion=False, params={}, runOptions={})

Run an OptiStructAnalysis using loads.

:param sumAtRegion: use a Summed at Contact Region representation of the
                 contact forces instead of the individual contact forces themselves.
:type sumAtRegion: bool
:param params: See OptiStructAnalysis.Params.
:type params: dict
:param runOptions: See OptiStructAnalysis.RunOptions.
:type runOptions: dict

:returns: The synthesis with results.
:rtype: OptiStructAnalysis


.. _copy:
.. method:: copy(self, items=None)

Create a copy of self containing the passed items

.. _countLoadCases:
.. method:: countLoadCases(self, **kwds)

How many load cases will be created
so we can warn the user if there are a lot

.. _createLoadCases:
.. method:: createLoadCases(self, deactivateRest=False, **kwds)

Create inspire LoadCases out of the load data.


.. _evenlySpaced:
.. method:: evenlySpaced(self, numSamples, includeBounds=True)

Returns a filtered set of loads.
Try to evenly space the output steps
There should not be any contact frames

includeBounds == False will give evenly spaced time steps, but
may or not not include the start/end time

includeBounds == True will include the start/end time but loads will not
not be exactly evenly if the numSamples does not divide evenly into
the number of timeSteps.  In this case we try to get as evenly spaced
as possible

.. _filter:
.. method:: filter(self, filter)

Filter time steps using filter function

.. _getChannels:
.. method:: getChannels(self, load, components)

Get run data for a load at every timeStep

.. _optimizePart:
.. method:: optimizePart(self, sumAtRegion=False, params={}, runOptions={})

Run a TopologyOptimization using loads.

:param sumAtRegion: use a Summed at Contact Region representation of the
                 contact forces instead of the individual contact forces themselves.
:type sumAtRegion: bool
:param params: See TopologyOptimization.Params.
:type params: dict
:param runOptions: See TopologyOptimization.RunOptions.
:type runOptions: dict

:returns: The synthesis with results.
:rtype: TopologyOptimization


.. _peaks:
.. method:: peaks(self, peaksPerComp=5, components='FX FY FZ FM TX TY TZ TM', forceThreshold=1e-05, torqueThreshold=0.001)

Returns a filtered set of loads.  For each joint, 'peaksPerComp' peaks
are gathered per requested component.  The consolidated list of these
values are returned removing duplicates.

The values at the start and end times are considered peaks since they
might be a min/max value.

Peaks whose absolute value is < forceThreshold / torqueThreshold
(in base units) are ignored

.. _timeSlice:
.. method:: timeSlice(self, start=None, end=None)

Get all time steps between a start and end time inclusive

.. _writeCsv:
.. method:: writeCsv(self, file, wrtDesignPos=False)

Write loads to csv file

wrtDesignPos Means force / torque directions will be transformed to the
          parts model position.