Muscle#

class myogen.simulator.Muscle(recruitment_thresholds, radius__mm=4.9, fiber_density__fibers_per_mm2=400, max_innervation_area_to_total_muscle_area__ratio=0.25, grid_resolution=256, autorun=False)[source]#

Bases: object

A muscle model for simulating motor unit organization and muscle fiber distribution.

The muscle model consists of:

Motor unit territories with biologically realistic size distributions
Spatially distributed innervation centers using optimal packing algorithms
Muscle fiber assignment based on proximity and self-avoidance principles

Parameters:

recruitment_thresholds (numpy.ndarray) – Array of recruitment thresholds for each motor unit. The values determine the relative sizes of motor unit territories, with larger values corresponding to larger territories. Typically ranges from -1 to 1, with the largest motor units having thresholds near 1.
radius__mm (float, default 4.9) – Radius of the muscle cross-section in millimeters. Default value corresponds to the First Dorsal Interosseous (FDI) muscle based on anatomical measurements (Jacobson et al., 1992).
fiber_density__fibers_per_mm2 (float, default 400) – Density of muscle fibers per square millimeter. This parameter controls the total number of muscle fibers in the muscle and affects the granularity of the simulation. Values typically range from 300-600 fibers/mm² for human muscles.
max_innervation_area_to_total_muscle_area__ratio (float, default 0.25) – Ratio defining the maximum territory size relative to total muscle area. A value of 0.25 means the largest motor unit can innervate up to 25% of the total muscle cross-sectional area. Must be in range (0, 1].
grid_resolution (int, default 256) – Resolution of the computational grid used for innervation electrode_grid_center distribution. Higher values provide more accurate spatial distribution but increase computational cost. Recommended range: 128-512.
autorun (bool, default False) – If True, automatically executes the complete muscle simulation pipeline: innervation electrode_grid_center distribution, muscle fiber generation, and fiber-to- motor unit assignment. If False, these steps must be called manually.

Raises:

ValueError – If max_innervation_area_to_total_muscle_area__ratio is not in (0, 1].

Notes

The muscle model uses a circular cross-section approximation, which is appropriate for many skeletal muscles. The recruitment thresholds are used as a proxy for motor unit sizes, following the size principle where larger motor units have higher recruitment thresholds.

Examples

>>> # Create a muscle with 120 motor units
>>> recruitment_thresholds = generate_mu_recruitment_thresholds(N=120)
>>> muscle = Muscle(
...     recruitment_thresholds=recruitment_thresholds,
...     radius__mm=4.9,
...     fiber_density__fibers_per_mm2=400,
...     autorun=True
... )
>>>
>>> # Access muscle fiber positions for motor unit 0
>>> fiber_positions = muscle.resulting_fiber_assignment(0)
>>> print(f"MU 0 has {len(fiber_positions)} muscle fibers")

Methods

`__init__`
`assign_mfs2mns`	Assign muscle fibers to motor neurons using biologically realistic principles.
`distribute_innervation_centers`	Distribute innervation electrode_grid_center positions using the fast marching method.
`generate_muscle_fiber_centers`	Generate muscle fiber electrode_grid_center positions using a pre-computed Voronoi distribution.
`resulting_fiber_assignment`	Get the muscle fiber positions assigned to a specific motor unit.

Attributes

`resulting_innervation_areas__mm2`	Calculate the actual innervation areas for each motor unit based on assigned fibers.
`resulting_number_of_innervated_fibers`	Calculate the actual number of muscle fibers assigned to each motor unit.

assign_mfs2mns(n_neighbours=3, conf=0.999)[source]#

Assign muscle fibers to motor neurons using biologically realistic principles.

This method implements an assignment algorithm that balances

multiple biological constraints:

Proximity: Fibers closer to innervation centers are more likely to be assigned
Territory size: Each motor unit has a target number of fibers based on its size
Self-avoidance: Neighboring fibers avoid belonging to the same motor unit
Gaussian territories: Fiber territories follow roughly Gaussian distributions

The assignment uses a probabilistic approach where each fiber is assigned based on the posterior probability computed from prior probabilities (target fiber numbers) and likelihoods (spatial clustering with Gaussian territories).

Parameters:

n_neighbours (int, default 3) – Number of neighboring fibers to consider for self-avoiding phenomena. Higher values increase intermingling between motor units but may slow computation. Typical range: 2-5.
conf (float, default 0.999) – Confidence interval that defines the relationship between innervation area and Gaussian distribution variance. Higher values create tighter, more compact territories. Should be between 0.9 and 0.999.

Returns:

Results are stored in self.assignment as an array of length n_fibers where each element indicates the motor unit index (0 to n_motor_units-1) assigned to that fiber.

Return type:

None

Raises:

ValueError – If innervation_center_positions is None. Call distribute_innervation_centers() first.

Notes

The algorithm compensates for out-of-muscle effects by calculating how much of each motor unit’s Gaussian distribution falls outside the circular muscle boundary and adjusting the in-muscle probabilities accordingly.

The self-avoidance mechanism promotes realistic intermingling by reducing the probability of assigning a fiber to a motor unit if its neighbors are already assigned to that unit.

Examples

>>> muscle.assign_mfs2mns(n_neighbours=4, conf=0.995)
>>> assignments = muscle.assignment
>>> print(f"Fiber 0 belongs to motor unit {assignments[0]}")

distribute_innervation_centers()[source]#

Distribute innervation electrode_grid_center positions using the fast marching method.

This method implements an optimal packing algorithm to distribute motor unit innervation centers within the circular muscle cross-section. The algorithm uses the Fast Marching Method to ensure that each new innervation electrode_grid_center is placed at the location that maximizes the minimum distance to all previously placed centers.

Returns:: Results are stored in self.innervation_center_positions as an array of shape (n_motor_units, 2) containing [x, y] coordinates in mm.
Return type:: None

Notes

This method must be called before generate_muscle_fiber_centers() and assign_mfs2mns(). The resulting distribution approximates the optimal packing problem for circles, leading to realistic motor unit territory arrangements.

generate_muscle_fiber_centers()[source]#

Generate muscle fiber electrode_grid_center positions using a pre-computed Voronoi distribution.

This method creates the spatial distribution of muscle fiber centers within the circular muscle cross-section. The distribution is based on a Voronoi tessellation pattern that mimics the natural packing of muscle fibers observed in histological studies.

Returns:

Results are stored in the following attributes:

self.mf_centers: Array of shape (n_fibers, 2) with fiber positions [x, y] in mm
self.number_of_muscle_fibers: Total number of muscle fibers
self.muscle_border: Array of border points for visualization

Return type:

None

Notes

This method should be called after distribute_innervation_centers() and before assign_mfs2mns(). The Voronoi-based distribution provides more realistic fiber spacing compared to regular grids or purely random distributions.

The reference dataset (‘voronoi_pi1e5.csv’) contains 100,000 pre-computed Voronoi cell centers optimized for circular domains, ensuring efficient and consistent fiber distributions across simulations.

resulting_fiber_assignment(mu)[source]#

Get the muscle fiber positions assigned to a specific motor unit.

Parameters:

mu (int) – Motor unit index (0-based). Must be less than the total number of motor units.

Returns:

Array of shape (n_assigned_fibers, 2) containing the [x, y] coordinates (in mm) of all muscle fibers assigned to the specified motor unit. If no fibers are assigned to the motor unit, returns an empty array.

Return type:

numpy.ndarray

Raises:

IndexError – If mu is outside the valid range [0, n_motor_units-1].
AttributeError – If the muscle fiber assignment has not been completed yet.

Examples

>>> fiber_positions = muscle.resulting_fiber_assignment(0)
>>> print(f"Motor unit 0 has {len(fiber_positions)} fibers")
>>> print(f"First fiber position: x={fiber_positions[0,0]:.2f}, y={fiber_positions[0,1]:.2f}")

Notes

This method should only be called after assign_mfs2mns() has been executed. The returned coordinates are in the muscle’s coordinate system with the origin at the muscle electrode_grid_center.

property resulting_innervation_areas__mm2: ndarray#

Calculate the actual innervation areas for each motor unit based on assigned fibers.

The innervation area is computed as the area of a circle that encompasses all muscle fibers assigned to a motor unit, centered on the motor unit’s innervation electrode_grid_center. This provides a measure of the spatial extent of each motor unit territory.

Returns:: Array of length n_motor_units containing the innervation area (in mm²) for each motor unit. Areas are calculated as π × r², where r is the maximum distance from the innervation electrode_grid_center to any assigned fiber.
Return type:: numpy.ndarray
Raises:: AttributeError – If innervation_center_positions is None or assignment has not been completed.

Examples

>>> actual_areas = muscle.resulting_innervation_areas__mm2
>>> desired_areas = muscle.desired_innervation_areas__mm2
>>> for i, (actual, desired) in enumerate(zip(actual_areas, desired_areas)):
...     print(f"MU {i}: desired {desired:.2f} mm², actual {actual:.2f} mm²")

Notes

The resulting areas may differ from desired areas due to the discrete nature of fiber assignment and the constraint of the circular muscle boundary. Motor units near the muscle periphery may have smaller actual areas than desired due to boundary effects.

property resulting_number_of_innervated_fibers: ndarray#

Calculate the actual number of muscle fibers assigned to each motor unit.

This property returns the final fiber counts after the assignment process, which may differ slightly from the desired counts due to the stochastic assignment algorithm and discrete fiber distribution.

Returns:: Array of length n_motor_units where each element represents the actual number of muscle fibers assigned to the corresponding motor unit. The sum of all elements equals the total number of muscle fibers.
Return type:: numpy.ndarray

Examples

>>> actual_counts = muscle.resulting_number_of_innervated_fibers
>>> desired_counts = muscle.desired_number_of_innervated_fibers
>>> print(f"Motor unit 0: desired {desired_counts[0]}, actual {actual_counts[0]}")

Notes

This property can be used to assess how well the assignment algorithm achieved the target fiber distribution. Large deviations may indicate the need to adjust assignment parameters or increase grid resolution.

Muscle#

This Page