pycapacity.human module

Overview

This is a python module which implements different human performance metrics based on their musculoskeletal models

acceleration polytope and ellipsoid
velocity (manipulability) polytope and ellipsoid
force polytope and ellipsoid
joint torque polytope

pycapacity.human.acceleration_ellipsoid(J, M, N, F_max)[source]

Human musculoskeletal acceleration ellipsoid calculation (dynamic manipulability ellipsoid)

\[E_a = \{\ddot{x}~ |~ \ddot{x} = JM^{-1}NF, \quad ||W^{-1}F|| \leq 1\}\]

where

\[W=diag(F_{max})\]

Parameters:

J – matrix jacobian
M – matrix inertia
N – moment arm matrix
F_max – maximal muscular forces

Returns:

ellipsoid object with the following attributes radii, axes

Return type:

ellipsoid(Ellipsoid)

pycapacity.human.acceleration_polytope(J, N, M, F_min, F_max, tol=1e-05, options=None)[source]

A function calculating the polytopes of achievable accelerations based on the jacobian matrix J, moment arm matrix N and mass matrix M

\[P_{a} = \{ \ddot{x} ~ | ~ \ddot{x} = JM^{-1}NF, \quad F_{min} \leq F \leq F_{max}\}\]

Based on the hyper_plane_shifting_method algorithm (default) or the iterative_convex_hull_method algorithm (options[‘algorithm’] = ‘ichm’).

Parameters:

J – jacobian matrix
N – moment arm matrix
M – mass matrix
F_min – minimal muscular forces (passive forces or 0)
F_max – maximal isometric forces
tolerance – tolerance for the polytope calculation
options – dictionary of options for the polytope calculation (currently supported options are calculate_faces and algorithm)

Returns:

polytope object with the following attributes vertices, half-plane representation H, d, (and face_indices and faces if option calculate_faces is set to True)

Return type:

poly(Polytope)

pycapacity.human.force_ellipsoid(J, N, F_max)[source]

Human musculoskeletal force ellipsoid calculation

\[E_f = \{f~ |~ NF = J^Tf,\quad ||W^{-1}F|| \leq 1\}\]

where

\[W=diag(F_{max})\]

Parameters:

J – matrix jacobian
N – moment arm matrix
F_max – maximal muscular forces

Returns:

ellipsoid object with the following attributes radii, axes

Return type:

ellipsoid(Ellipsoid)

pycapacity.human.force_polytope(J, N, F_min, F_max, tol, torque_bias=None, options=None)[source]

A function calculating the polytopes of achievable forces based on the jacobian matrix J and moment arm matrix N

\[P_{f} = \{ f ~ | ~ J^Tf = NF, \quad F_{min} \leq F \leq F_{max}\}\]

optionally an additional bias \(\tau_{bias}\) can be added

\[P_{f} = \{ f ~ | ~ J^Tf = NF + \tau_{bias}, \quad F_{min} \leq F \leq F_{max}\}\]

Based on the iterative_convex_hull_method algorithm.

Parameters:

J – jacobian matrix
N – moment arm matrix
F_min – minimal muscular forces (passive forces or 0)
F_max – maximal isometric forces
tolerance – tolerance for the polytope calculation
torque_bias – torque bias optional (gravity or movement or applied forces ….)
options – dictionary of options for the polytope calculation (currently only calculate_faces is supported)

Returns:

polytope object with the following attributes vertices, torque vertices torque_vertices, muscle force vertices muscle_force_vertices, half-plane representation H, d, (and face_indices and faces if option calculate_faces is set to True)

Return type:

polytope(Polytope)

pycapacity.human.joint_torques_polytope(N, F_min, F_max, tol=1e-05, options=None)[source]

A function calculating the polytopes of achievable joint torques based on the moment arm matrix N :

\[P_{t} = \{ \tau ~ | ~ \tau= NF, \quad F_{min} \leq F \leq F_{max}\}\]

Based on the hyper_plane_shifting_method algorithm.

Parameters:

N – moment arm matrix
F_min – minimal muscular forces (passive forces or 0)
F_max – maximal isometric forces
tolerance – tolerance for the polytope calculation
options – dictionary of options for the polytope calculation (currently only calculate_faces is supported)

Returns:

polytope object with the following attributes vertices, half-plane representation H, d, (and face_indices and faces if option calculate_faces is set to True)

Return type:

poly(Polytope)

pycapacity.human.torque_to_muscle_force(N, F_min, F_max, tau, options='lp')[source]

A function calculating muscle forces needed to create the joint torques tau. It uses either the linear programming or quadratic programming, set with the options parameter.

The quadratic programming problem is formulated as:

\[F = \text{arg}\min_F ||F||^2 \quad s.t. \quad N^TF = \tau, \quad F_{min} \leq F \leq F_{max}\]

The linear programming problem is formulated as:

\[F = \text{arg}\min_F \sum_i \frac{1}{F_{max,i} - F_{min,i}}F_i \quad s.t. \quad N^TF = \tau, \quad F_{min} \leq F \leq F_{max}\]

Parameters:

N – moment arm matrix
F_min – minimal muscular forces (passive forces or 0)
F_max – maximal isometric forces
tau – joint torque
options – dictionary of options (currently supported solver type to use: lp - linear programming (default), qp - quadratic programming)

Returns:

list of muscle forces

Return type:

F(list)

pycapacity.human.velocity_ellipsoid(J, N, dl_max)[source]

Human musculoskeletal velocity ellipsoid calculation

\[E_f = \{\dot{x}~ |~ J\dot{q} = \dot{x},~ L\dot{q} = \dot{l} \quad ||W^{-1}\dot{l}|| \leq 1\}\]

where

\[W=diag(\dot{l}_{max})\]

Parameters:

J – position jacobian
N – moment arm matrix (\(N = -L^T\), where \(L\) is the muscle length jacobian)
dl_max – maximal joint velocities

Returns:

ellipsoid object with the following attributes radii, axes

Return type:

ellipsoid(Ellipsoid)

pycapacity.human.velocity_polytope(J, N=None, dl_min=None, dl_max=None, dq_max=None, dq_min=None, tol=1e-05, options=None)[source]

A function calculating the polytopes of achievable velocity based on the jacobian matrix J and moment arm matrix N

If only muscle contraction velocity limits are given

\[P_{v,\dot{l}} = \{ \dot{x} ~ | ~ L\dot{q} = \dot{l},~~ J\dot{q} = \dot{x}, \quad \dot{l}_{min} \leq \dot{l} \leq \dot{l}_{max}\}\]

If only joint velocity limits are given

\[P_{v,\dot{q}} = \{ \dot{x} ~ | ~ J\dot{q} = \dot{x}, \quad \dot{q}_{min} \leq \dot{q} \leq \dot{q}_{max}\}\]

If both are provided the function will calculate

\[P_{v,\dot{l}} = \{ \dot{x} ~ | ~ J\dot{q} = \dot{x}, \quad \dot{q}_{min} \leq \dot{q} \leq \dot{q}_{max}, ~~ \dot{l}_{max} \leq L\dot{q} \leq \dot{l}_{max}\}\]

Based on the iterative_convex_hull_method algorithm.

Parameters:

J – jacobian matrix
N – moment arm matrix \(L = -N^T\)
dl_min – minimal achievable muscle contraction velocity
dl_max – maximal achievable muscle contraction velocity
dq_min – minimal achievable joint velocity
dq_max – maximal achievable joint velocity
tol – tolerance for the polytope calculation
options – dictionary of options for the polytope calculation (currently only calculate_faces is supported)

Returns:

polytope object with the following attributes vertices, joint velocity vertices dq_vertices and muscle elongation vertices dl_vertices, half-plane representation H, d, (and face_indices and faces if option calculate_faces is set to True)

Return type:

polytope(Polytope)