/cocofest

Cocofest is an optimal control python package for functional electrical stimulation models

Primary LanguagePythonMIT LicenseMIT

COCOFEST

Cocofest : Custom Optimal Control Optimization for Functional Electrical STimulation, is an optimal control program (OCP) package for functional electrical stimulation (FES). It is based on the bioptim framework for the optimal control construction. Bioptim uses biorbd a biomechanics library and benefits from the powerful algorithmic diff provided by CasADi. To solve the OCP, the robust solver Ipopt has been implemented.

Status

Type Status
License License
Code coverage codecov
Code climate

Table of Contents

How to install Cocofest

Available FES models

Create your own FES OCP

Examples

Other functionalities

Citing

How to install

Currently, no anaconda installation is available. The installation must be done from the sources. Cloning the repository is the first step to be able to use the package.

Dependencies

Cocofest relies on several libraries. Follows the steps to install everything you need to use Cocofest.
First, you need to create a new conda environment

conda create -n YOUR_ENV_NAME python=3.10

Then, activate the environment

conda activate YOUR_ENV_NAME

This step will allow you to install the dependencies in the environment much quicker

conda install -cconda-forge conda-libmamba-solver

After, install the dependencies

conda install numpy matplotlib pytest casadi biorbd pyorerun -cconda-forge --solver=libmamba

Finally, install the bioptim setup.py file located in your cocofest/external/bioptim folder

cd <path_up_to_cocofest_file>/external/bioptim
python setup.py install

You are now ready to use Cocofest!

Available FES models

The available FES models are likely to increase so stay tune.

Ding2003

Ding, J., Wexler, A. S., & Binder-Macleod, S. A. (2003). Mathematical models for fatigue minimization during functional electrical stimulation. Journal of Electromyography and Kinesiology, 13(6), 575-588.

Ding2007

Ding, J., Chou, L. W., Kesar, T. M., Lee, S. C., Johnston, T. E., Wexler, A. S., & Binder‐Macleod, S. A. (2007). Mathematical model that predicts the force–intensity and force–frequency relationships after spinal cord injuries. Muscle & Nerve: Official Journal of the American Association of Electrodiagnostic Medicine, 36(2), 214-222.

Hmed2018

Hmed, A. B., Bakir, T., Sakly, A., & Binczak, S. (2018, July). A new mathematical force model that predicts the force-pulse amplitude relationship of human skeletal muscle. In 2018 40th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 3485-3488). IEEE.

Create your own FES OCP

You can create your own FES OCP by following the steps below:

  1. Create a new python file
  2. Import the desired model from Cocofest (e.g. Ding2003) and the fes_ocp class
from cocofest import DingModelFrequency, OcpFes
  1. Create your own optimal control problem by adding the stimulation pulse number, the number of shooting points, the final simulation time, the objective function (for this example, the force at the end of the simulation must be the closest to 100N), the minimum and maximum time between two stimulation pulse, the time bimapping (If True, will act like a frequency at constant pulse interval).
ocp = OcpFes().prepare_ocp(...,
                         n_stim=10,
                         n_shooting=20,
                         ...,)
  1. Solve you OCP
result = ocp.solve()

Examples

You can find all the available examples in the examples file.

Musculoskeletal model driven by FES models

The following example is a musculoskeletal model driven by the Ding2007 FES model. The objective function is to reach a 90° forearm position and 0° arm position at the movement end. The stimulation last 1s and the stimulation frequency is 10Hz. The optimized parameter are each stimulation pulse width.

Other functionalities

Initital value problem

You can also compute the models form initial value problem. For that, use the IvpFes class to build the computed problem.

from cocofest import IvpFes, DingModelFrequencyWithFatigue

fes_parameters = {"model": DingModelFrequencyWithFatigue(), "n_stim": 10}
ivp_parameters = {"n_shooting": 20, "final_time": 1}

ivp = IvpFes(fes_parameters, ivp_parameters)

result, time = ivp.integrate()

Summation truncation

The summation truncation is an integer parameter that can be added to the model. It will truncate the stimulation apparition list used for the calcium summation. The integer number defines the stimulation number to keep prior this summation calculation (e.g only the 5 past stimulation will be included).

ocp = OcpFes().prepare_ocp(model=DingModelFrequency(sum_stim_truncation=5))

Citing

Cocofest is not yet published in a journal. But if you use Cocofest in your research, please kindly cite this zenodo link 10.5281/zenodo.10427934.

Acknowledgements

The software development was supported by Ingénierie de technologies interactives en réadaptation INTER #160 OptiStim. The Cocofest logo has been design by MaxMV