Welcome to PyMuscle’s documentation!

class pymuscle.Muscle(motor_neuron_pool_model, muscle_fibers_model)[source]

A user-created Muscle object.

Used to simulate the input-output relationship between motor neuron excitation and muscle fibers contractile state over time.

Parameters:
  • motor_neuron_pool_model (Model) – The motor neuron pool implementation to use with this muscle.
  • muscle_fibers_model (Model) – The muscle fibers model implementation to use with this muscle.
  • motor_unit_count – How many motor units comprise this muscle.

Usage:

from pymuscle import (Muscle,
                      PotvinFuglevand2017MotorNeuronPool as Pool,
                      PotvinFuglevand2017MuscleFibers as Fibers)

motor_unit_count = 60
muscle = Muscle(
    Pool(motor_unit_count),
    Fibers(motor_unit_count),
)
excitation = 32.0
force = muscle.step(excitation, 1 / 50.0)
step(motor_pool_input, step_size)[source]

Advances the muscle model one step.

Parameters:
  • motor_pool_input (Union[float, ndarray]) – Either a single value or an array of values representing the excitatory input to the motor neuron pool for this muscle
  • step_size (float) – How far to advance the simulation in time for this step.
Return type:

float
class pymuscle.PotvinFuglevandMuscle(motor_unit_count, apply_central_fatigue=True, apply_peripheral_fatigue=True, pre_calc_firing_rates=False)[source]

A thin wrapper around Muscle which pre-selects the Potvin fiber and motor neuron models.

class pymuscle.Model(motor_unit_count)[source]

Base model class from which other models should inherit

step(inputs, step_size)[source]

Child classes must implement this method.

class pymuscle.PotvinFuglevand2017MotorNeuronPool(motor_unit_count, max_recruitment_threshold=50, firing_gain=1.0, min_firing_rate=8, max_firing_rate_first_unit=35, max_firing_rate_last_unit=25, pre_calc_firing_rates=False, pre_calc_resolution=0.1, pre_calc_max=70.0, derecruitment_delta=2, adaptation_magnitude=0.67, adaptation_time_constant=22.0, max_duration=20000.0, apply_fatigue=True)[source]

Encapsulates the motor neuron portion of the motor unit model.

The name of each parameter as it appears in Potvin, 2017 is in parentheses. If a parameter does not appear in the paper but does appear in the accompanying Matlab code, the variable name from the Matlab code is used in the parentheses.

Parameters:
  • motor_unit_count (int) – Number of motor units in the muscle (n)
  • max_recruitment_threshold (int) – Max excitation required by a motor unit within the pool before firing (RR)
  • firing_gain (float) – The slope of firing rate by excitation above threshold (g)
  • min_firing_rate (int) – The minimum firing rate for a motor neuron above threshold (minR)
  • max_firing_rate_first_unit (int) – Max firing rate for the first motor unit (maxR(1))
  • max_firing_rate_last_unit (int) – Max firing rate for the last motor unit (maxR(last))
  • pre_calc_firing_rates (bool) – Whether to build a dict mapping excitation levels to firing rates for each motor neuron. This can speed up simulation at the cost of additional memory.
  • pre_calc_resolution (float) – Step size for excitation levels to pre-calculate (res)
  • pre_calc_max (float) – Highest excitation value to pre-calculate
  • derecruitment_delta (int) – Absolute minimum firing rate = min_firing_rate - derecruitment_delta (d)
  • adaptation_magnitude (float) – Magnitude of adaptation for different levels of excitation.(phi)
  • adaptation_time_constant (float) – Time constant for motor neuron adaptation (tau). Default based on Revill & Fuglevand (2011)
  • max_duration (float) – Longest duration of motor unit activity that will be recorded. The default value should be >> than the time it takes to fatigue all fibers. Helps prevent unbounded values.

Todo

Make pre_calc_max a function of other values as in the matlab code. This will also require changing how we look up values if they are larger than this value.

Usage:

from pymuscle import PotvinFuglevand2017MotorNeuronPool as Pool

motor_unit_count = 60
pool = Pool(motor_unit_count)
excitation = np.full(motor_unit_count, 10.0)
step_size = 1 / 50.0
firing_rates = pool.step(excitation, step_size)
step(motor_pool_input, step_size)[source]

Advance the motor neuron pool simulation one step.

Returns firing rates on a per motor neuron basis for the given array of excitations. Takes into account fatigue over time.

Parameters:
  • excitations – Array of excitation levels to use as input to motor neurons.
  • step_size (float) – How far to advance time in this step.
Return type:

ndarray
class pymuscle.PotvinFuglevand2017MuscleFibers(motor_unit_count, max_twitch_amplitude=100, max_contraction_time=90, contraction_time_range=3, max_recruitment_threshold=50, fatigue_factor_first_unit=0.0125, max_fatigue_rate=0.0225, fatigability_range=180, contraction_time_change_ratio=0.379, apply_fatigue=True)[source]

Encapsulates the muscle fibers portions of the motor unit model.

The name of each parameter as it appears in Potvin, 2017 is in parentheses. If a parameter does not appear in the paper but does appear in the Matlab code, the variable name from the Matlab code is in parentheses.

Parameters:
  • motor_unit_count (int) – Number of motor units in the muscle (n)
  • max_twitch_amplitude (int) – Max twitch force within the pool (RP)
  • max_contraction_time (int) – [milliseconds] Maximum contraction time for a motor unit (tL)
  • contraction_time_range (int) – The scale between the fastest contraction time and the slowest (rt)
Fatigue_factor_first_unit:
 

The nominal fatigability of the first motor unit in percent / second
Fatigability_range:
 

The scale between the fatigability of the first motor unit and the last
Contraction_time_change_ratio:
 

For each percent of force lost during fatigue, what percentage should contraction increase? Based on Shields et al (1997)

Todo

The argument naming isn’t consistent. Sometimes we use ‘max’ and other times we use ‘last unit’. Can these be made consistent?

Usage:

from pymuscle import PotvinFuglevand2017MuscleFibers as Fibers

motor_unit_count = 60
fibers = Fibers(motor_unit_count)
motor_neuron_firing_rates = np.rand(motor_unit_count) * 10.0
step_size = 0.01
force = fibers.step(motor_neuron_firing_rates, step_size)
step(motor_pool_output, step_size=0.1)[source]

Advance the muscle fibers simulation one step.

Returns the total instantaneous force produced by all fibers for the given input from the motor neuron pool.

Parameters:
  • motor_pool_output (ndarray) – An array of firing rates calculated by a compatible Pool class.
  • step_size (float) – How far time has advanced in this step.
Return type:

float

Implementations of equations used in Hill-Type muscle models

Not all equations for a traditional Hill-Type model are provided here. It is expected that passive elements will be modeled by a physics simulator selected by PyMuscle users.

Also it should be noted that these equations do not take pennetation angle into account (which is common in Hill-type models). Users should check to make sure their physics simulator is handling forces correctly to provide values which vary by angle.

Indices and tables