API Design - Second Draft

[iandanforth]

Design Guidelines

Why a second draft?

The initial API was not well aligned with the API for actuators in simulation libraries. The MuJoCo muscles were recently released are partialy defined by their peak force. In Box2d (the 2d physics library that Gym uses) joint motors are defined by their max torque and by additional limits. A PyMunk simple motor also allows for a max force parameter.

While a biologist or neuroscientist might think of a muscle in terms of its composition (the number of motor units) for the target audience of this library it is the functional aspect of muscles (force production) which is primary.

The second draft of the API will focus on revising the instantiation of muscles in terms of their peak force output.

StandardMuscle

The base Muscle class will continue to be in terms of motor units as this is well aligned with the physiology literature. A new top level class StandardMuscle will be implemented to provide the new force-centric API.

What kind of information will the user provide?

Setup

The primary (optional) paramater for a StandardMuscle will be max_force. This value will be interpreted as Newtons. From this value we will calculate how many motor units a muscle would have if it could generate this force. That calculation is essentially scaling up or down from the First Dorsal Interossei which is the muscle modeled by Potvin and Fuglevand.

Runtime

The primary method on a Muscle instance is step(). The main argument should be one of the following.

1. A single value between 0.0 and 1.0 representing a percentage of maximum excitation.

This item is new and is intended as a simplification of the API.

Range Note: 1.0 - will be translated into the excitation frequency which would stimulate a fully rested muscle to produce it's maximum force output. This value will be calculated internally at the time the muscle is instantiated.

2. A single float representing a stimulus input frequency which will be passed to each motor unit
3. An array of floats representing stimulus input frequencies for each motor unit. This array must have length N where N is the number of motor units in the model.

What kind of information will the API provide?

Primary - Motor unit output at a given timestep.
Secondary - Motor unit capacity at a given timestep.

What are the logical divisions in the functionality?

Outer class

OpenAI Gym compatability
    Action space definition NOTE: Maybe we shouldn't do this? Make it generic?
    Observation space definition
Input validation
State maintenance
Motor Neuron Model
Input -> Output behavior of the motor neurons
Fatigue of the motor neurons
Recovery of motor neurons
Fiber Model
Input -> Output behavior of the muscle fibers
Fatigue of the muscle fibers
Recovery of the muscle fibers

How does a user write a plugin for this library? If they can't how do they extend it?

...

[iandanforth]

Further consideration

In may ways even the max_force based API described above and currently implemented may be too complicated.

A StandardMuscle provides the fatigue model and most researchers will use a separate simulation for the generation of force. This means that the default size StandardMuscle will probably satisfy the 90% use-case.

Because these muscles are likely to be disassociated from force generation the size of the muscles may not matter too much. A new consideration is that the composition of the muscles may be more useful.

e.g. FastTwitchMuscle or SlowTwitchMuscle might be a more useful axis of variation rather than motor_unit_count or max_force.

We will need user feedback to make an informed choice.