Metadata-Version: 2.1
Name: pymuscle
Version: 0.0.3
Summary: A motor unit based model of skeletal muscle and fatigue
Home-page: https://github.com/iandanforth/pymuscle
Author: Ian Danforth
Author-email: iandanforth@gmail.com
License: MIT
Description: 
        # PyMuscle
        PyMuscle provides a motor unit based model of skeletal muscle. It simulates the
        relationship between excitatory input and motor-unit output as well as fatigue 
        over time.
        
        It is compatible with [OpenAI Gym](https://gym.openai.com) environments and is 
        intended to be useful for researchers in the machine learning community.
        
        PyMuscle can be used to enhance the realism of motor control for simulated 
        agents. To get you started we provide a [toy example project](https://github.com/iandanforth/pymuscle/tree/master/examples) 
        which uses PyMuscle in a simulation of arm curl and extension.
        
        Out of the box we provide a motor neuron pool model and a muscle fiber model
        based on "A motor unit-based model of muscle fatigue" 
        ([Potvin and Fuglevand, 2017](http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005581)).
        If you use this library as part of your research please cite that paper.
        
        ## More about PyMuscle
        
        Motor control in biological creatures is complex. PyMuscle allows you to capture
        some of that complexity while remaining [performant](#performance). It provides 
        greater detail than sending torque values to simulated motors-as-joints but 
        less detail (and computational cost) than a full biochemical model.
        
        PyMuscle is not tied to a particular physics library and can be used with a 
        variety of muscle body simulations. PyMuscle focuses on the relationship between 
        control signals (excitatory inputs to motor neurons) and per-motor-unit output.
        
        Motor unit output is dimensionless but can be interpreted as force. It can also
        be used as a proxy for the contractile state of muscle bodies in the physics
        sim of your choice.
        
        # Background
        
        ## Motor Units
        <p align="center"><img width="80%" src="docs/src/images/motor-unit-diagram.png" /></p>
        
        
        A motor unit is the combination of a motor neuron and the muscle fibers to which
        the neuron makes connections. Skeletal muscles are made up of many muscle fibers. 
        For a given motor unit a single motor neuron will have an axon that branches
        and innervates a subset of the fibers in a muscle. Muscle fibers usually
        belong to only one motor unit.
        
        Muscles may have anywhere from a few dozen to thousands of motor units. The
        human arm, for example, has 30 some muscles and is innervated by [approximately 35,000 axons](https://onlinelibrary.wiley.com/doi/abs/10.1002/ana.25018)
        from motor neurons. 
        
        The brain controls muscles by sending signals to motor units and receiving
        signals from mechanoreceptors embedded in muscles and the skin. In animals all
        the motor units an animal will ever have are present from birth and learning to 
        produce smooth coordinated motion through control of those units is a significant 
        part of the developmental process.
        
        ## Control
        
        Motor units are recruited in an orderly fashion to produce varying levels of 
        muscle force. 
        
        The cell bodies of motor neurons for a given muscle cluster together in the 
        spinal cord in what are known as motor neuron pools, columns, or nuclei. 
        Generally motor neurons in a pool can be thought of as all getting the same 
        activation inputs. This input is the combination of dozens if not hundreds of 
        separate inputs from interneurons and upper motor neurons carrying signals from
        the brain and mechanoreceptors in the body.
        
        In a voluntary contraction of a muscle, say in curling your arm, the input
        to the motor neuron pool for the bicep muscle will ramp up, recruiting more
        and more motor units, starting from the weakest motor units to stronger ones.
        
        Over time motor neurons and muscle fibers can't produce the same level of force 
        for the same level of activation input. This is called fatigue. The brain must
        compensate for the fatigue if it wants to maintain a given force or perform
        the same action again and again in the same way.
        
        # Installation
        
        ### *** PyMuscle is under development. Please do not install yet. ***
        
        ## Requirements
        
        Python 3
        
        
        ## Install
        
        ```
        pip install pymuscle
        ```
        
        # Getting Started
        
        ### Familiar with OpenAI's Gym?
        
        Try out the [example project](https://github.com/iandanforth/pymuscle/tree/master/examples)
        
        ### Minimal example 
        
        The Muscle class provides the primary API for the library. A Muscle can be
        heavily customized but here we use the default values. A default Muscle
        contains 120 motor units with a distribution of strengths, recruitment 
        thresholds, and fatigue properties as used in the experiments of Potvin and 
        Fuglevand, 2017.
        
        ```python
        
        import numpy as np
        from pymuscle import PotvinMuscle as Muscle
        from pymuscle.vis import PotvinChart
        
        step_size = 1 / 50.0  # 50 frames per second
        muscle = Muscle(step_size=step_size)
        
        sim_duration = 60  # seconds
        total_steps = int(sim_duration / step_size)
        outputs = []
        capacities = []
        for _ in range(total_steps):
            excitation = np.random.uniform()
            # Update the simulation
            output = muscle.step(excitation, step_size)
            # Inspect the state of the muscle
            output = muscle.state.motor_units.output  # A per-motor-unit output value
            capacity = muscle.state.motor_units.capacity  # Max output per unit which decreases with fatigue
        
            print(output)
            print(capacity)
        
        # Visualize the behavior of the motor units over time
        chart = PotvinChart(
            step_size=step_size,
            motor_unit_outputs=outputs,
            motor_unit_capacities=capacities
        )
        chart.display()
        ```
        
        This will open a browser window with the produced chart. It should look like this:
        
        <p align="center"><img width="80%" src="docs/src/images/minimal-example-chart.png" /></p>
        
        # Versioning Plan
        
        PyMuscle is in a pre-alpha state. Expect regular breaking changes.
        
        We expect to stabilize the API for 1.0 and introduce breaking changes only
        during major releases.
        
        This library tries to provide empirically plausible behavior. As new research is
        released or uncovered we will update the underlying model. Non-bug-fix changes
        that would alter the output of the library will be integrated in major releases.
        
        If you know of results you believe should be integrated please let us know. See 
        the [Contributing](#contributing) section.
        
        # Contributing
        
        We encourage you to contribute! Specifically we'd love to hear about and feature
        projects using PyMuscle.
        
        For all issues please search the [existing issues](https://github.com/iandanforth/pymuscle/issues) before submitting.
        
        - [Bug Reports](https://github.com/iandanforth/pymuscle/issues/new?template=bug_report.md)
        - [Enhancement requests](https://github.com/iandanforth/pymuscle/issues/new?template=feature_request.md)
        - [Suggest research](https://github.com/iandanforth/pymuscle/issues/new?template=research-submission.md) that can better inform the model
        
        _Before_ opening a pull request please:
        
        - See if there is an open ticket for this issue
            - If the ticket is tagged 'Help Needed' comment to note that you intend to work on this issue
            - If the ticket is *not* tagged, comment that you would like to work on the issue
                - We will then discuss the priority, timing and expectations around the issue.
        - If there is no open ticket, create one
            - We prefer to discuss the implications of changes before you write code! 
        
        
        ## Development
        
        If you want to help develop the PyMuscle library itself the following may help.
        
        Clone this repository
        
        ```
        git clone git@github.com:iandanforth/pymuscle.git
        cd pymuscle
        ```
        
        Install [pipenv](https://docs.pipenv.org/). (The modern combination of pip and 
        virtual environments.)
        
        ```
        pip install pipenv
        ```
        
        If this throws a permissions error you will need to to run this with 'sudo'
        
        ```
        sudo pip install pipenv
        ```
        
        Install dependencies and start a clean python environment
        
        ```
        pipenv install
        pipenv shell
        ```
        
        To exit this python environment
        
        ```
        exit
        ```
        
        or close your terminal and start a new one.
        
        # Performance
        
        PyMuscle aims to be fast. We use Numpy to get fast vector computation. PyMuscle
        is currently a single-process but may be extended to multi-process systems in 
        the future and GPU computation through the integration of [PyTorch](https://pytorch.org/).
        
        # Limitations
        
        ## Scope
        
        PyMuscle is concerned with inputs to motor unit neurons, the outputs of those
        motor units, and the changes to that system over time. It does not model the
        dynamics of the muscle body itself or the impact of dynamic motion on this
        motor unit input/output relationship.
        
        ## Recovery
        
        Potvin and Fuglevand 2017 explicitly models fatigue but *not* recovery. PyMuscle
        implements a simple inversion of the fatigue rules for recovery but this is not
        empirically grounded. We eagerly await the updated model from Potvin which will
        included a model of recovery.
        
        ## Proprioception
        
        This library does not directly provide any feedback signals for control. The
        example project shows how to integrate PyMuscle with a physics simulation to
        get simulated output forces and stretch and strain values derived from the
        state of the simulated muscle body. (In the example this is a damped spring
        but a Hill-type, or more complex model could also be used.)
        
        Fatigue could be used as a feedback signal but this will need to be calculated
        from the states of the motor units.
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.6.0
Description-Content-Type: text/markdown
