API Design - First Draft

[iandanforth]

Design Guidelines

1. Look at the API from the eyes of a naive user

The most important thing is to have empathy with your primary target audience and constantly ask yourself what makes most sense for them in their perspective. This applies to everything, from the first moments reading the README.md examples to the corner-case use cases of the API. The Principle of Least Surprise applies strongly here.

2. Define the purpose and level of abstraction of your library

What problem does it solve?

It enables a more accurate and dynamic model of the relationship between control signals and force output. It manages the stateful, time-dependent relationship between control signals and changes to motor units. This can be coupled with a simulation of the muscle body to capture the full control signal to force output relationship.

What is the level of abstraction?

The collection of motor units which form a muscle.

What problems does it not solve?

• Simulating the muscle body.
• Proprioception / feedback

3. Tradeoffs always exist, but unimportant disadvantages also exist

What are the major tradeoffs?

Accuracy vs Speed.

The goal is to capture the complexity of the problem that biological creatures are faced with, while being fast enough that useful interesting research can be done quickly.

Pros

More accurate.
More dynamic.

Cons

Slower than a purely linear relationship.
Complexity might not be needed.

4. Make the correct way easy, make the wrong way possible

Keep the library user comfortable in using your library in the right way, while making him cautious in using the library in the wrong way.

4.1. Short names

4.2. Common words

4.3. Long names for 'incorrect' way of doing things.

e.g. dangerouslySetInnerHTML

5. Be always mindful of the types

• Mock out types in initial design

So, write the type signatures.

What kind of composability strategy you are using?

OOP

6. Cooperate with the host language

a.k.a. stay Pythonic

7. Be open to feedback

Guidelines by Andre Statlz

[iandanforth]

What kind of information will the user provide?

Setup

• The composition of a given muscle
• Any variation on the properties of a motor unit

Runtime

• Excitation input to motor neurons

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?

They should be able to swap in alternative motor neuron models and fiber models.

[iandanforth]

If you had to write this as a series of pure functions what would it look like?

Model properties

• ???

Property containers

• motor_neuron_intrinsics
• fiber_intrinsics

motor_neuron_intrinsics = gen_motor_neuron_intrinsics(
    motor_neuron_model_prop_1,
    ...,
    motor_neuron_model_prop_n,
    motor_neuron_count
)

fiber_intrinsics = gen_fiber_intrinsics(
    fiber_model_prop_1,
    ...,
    fiber_model_prop_n,
    motor_neuron_count
)

State containers

• motor_neuron_input
• motor_neuron_fatigue
• motor_neuron_output_history

motor_neuron_output = calc_motor_neuron_output(
    step_size, 
    motor_neuron_intrinsics, 
    motor_neuron_fatigue, 
    motor_neuron_input
)

motor_neuron_output_history = update_motor_neuron_output_history(
    motor_neuron_output_history,
    motor_neuron_output
)

motor_neuron_fatigue = calc_motor_neuron_fatigue(
    step_size, 
    motor_neuron_intrinsics, 
    motor_neuron_fatigue, 
    motor_neuron_output_history
)

State containers

• fiber_fatigue
• fiber_output_history

fiber_output = calc_fiber_output(
    step_size, 
    fiber_intrinsics,
    fiber_fatigue,
    motor_neuron_output
)

fiber_output_history = update_fiber_output_history(
    fiber_output_history,
    fiber_output
)
fiber_fatigue = calc_fiber_fatigue(
    step_size, 
    fiber_intrinsics,
    fiber_fatigue,
    fiber_output_history
)
fiber_fatigue = calc_fiber_recovery(
    step_size, 
    fiber_intrinsics,
    fiber_fatigue,
    fiber_output_history
)

[iandanforth]

See First Draft of API Design

This mocks out three classes:

1. Muscle - The high level user interface to the library
2. MotorNeuronPoolModel - The API for the Potvin model components which concern the motor neurons
3. MuscleFiberModel - The API for the Potvin model components which concern the muscle fibers

It also has a pseudo-code implementation for what calling step() on a muscle does to advance the state of the simulation.