Merge branch 'main' of https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox

Author: adkoele

.github/workflows/draft-pdf.yml

@@ -0,0 +1,24 @@
+name: Draft PDF
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v4
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper.pdf

.github/workflows/main.yml

@@ -6,7 +6,7 @@ name: Doxygen Action
 # events but only for the master branch
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
 
 
 
@@ -26,14 +26,34 @@ jobs:
       uses: mattnotmitt/[email protected]
       with:
         # Path to Doxyfile
-        doxyfile-path: "./docs/Doxygen/Doxyfile" # default is ./Doxyfile
+        doxyfile-path: "./Doxyfile" # default is ./Doxyfile
         # Working directory
         working-directory: "./docs/Doxygen" # default is .
 
-    - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
+    - name: Upload static files as artifact
+      id: deployment
+      uses: actions/upload-pages-artifact@v3 # or specific "vX.X.X" version tag for this action
       with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        # Default Doxyfile build documentation to html directory. 
-        # Change the directory if changes in Doxyfile
-        publish_dir: ./docs/Doxygen/html
+        path: ./docs/Doxygen/Doxygen_HTML
+
+    # Deployment job
+  deploy:
+    # Add a dependency to the build job
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+        # Specify runner + deployment step
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this action

README.md

@@ -1,4 +1,4 @@
-Instruction to start using the toolbox
+Instruction to start using the BioMAC-Sim-Toolbox. Extended documentation can be found here: https://mad-lab-fau.github.io/BioMAC-Sim-Toolbox/
 
 1. Make sure that you have compiler installed. For instructions, see here: https://nl.mathworks.com/matlabcentral/answers/311290-faq-how-do-i-install-the-mingw-compiler
 2. Install IPOPT. For example, you can install it by installing the following version through the Add-On Explorer in MATLAB: https://github.com/ebertolazzi/mexIPOPT. To do so, go to the "Apps" tab, click "Get More Apps" in top left to open the Add-On Explorer, then search for "IPOPT" and click "Add" on the top right. 
@@ -8,4 +8,4 @@ Instruction to start using the toolbox
 
 If you are using a newer Apple Silicon Mac, please take a look at the following to get mexIPOPT running: https://github.com/ebertolazzi/mexIPOPT/issues/24
 
-If you would like to compile on different systems on the same machine, you need to manually delete the .o files after building the model files to ensure that you can build on the other system.
+If you would like to compile on different systems on the same machine, you need to manually delete the .o files after building the model files to ensure that you can build on the other system.

docs/Doxygen/pages/mainpage.dox

@@ -9,7 +9,7 @@
  *
  */
 
-/** @mainpage  Welcome to the documentation of the biomechanical simulation toolbox. 
+/** @mainpage  Welcome to the documentation of the biomechanical motion analasys and creation (BioMAC) simulation toolbox. 
  * @image html  running.png
  This toolbox was created by researchers from the <a href="https://www.mad.tf.fau.de/">Machine Learning and Data Analytics</a> Lab and the <a href="https://www.asm.tf.fau.de/en/startseite/research/biomac/">Biomechanical Motion Analysis and Creation Group</a> at Friedrich-Alexander-Universit&auml;t Erlangen-N&uuml;rnberg in Erlangen, Germany and by researchers from the former Parker-Hannifin Laboratory for Human Motion and Control at Cleveland State University, Cleveland, Ohio, USA.
 */ 

paper.bib

@@ -100,6 +100,17 @@ @article{koelewijn:2022
   publisher={IEEE}
 }
 
+@article{Geyer:2010,
+  title={A muscle-reflex model that encodes principles of legged mechanics produces human walking dynamics and muscle activities},
+  author={Geyer, Hartmut and Herr, Hugh},
+  journal={IEEE Transactions on neural systems and rehabilitation engineering},
+  volume={18},
+  number={3},
+  pages={263--273},
+  year={2010},
+  publisher={IEEE}
+}
+
 @article{Wachter:2006,
   title={On the implementation of an interior-point filter line-search algorithm for large-scale nonlinear programming},
   author={W{\"a}chter, A and Biegler, LT},

paper.md

@@ -1,5 +1,5 @@
 ---
-title: 'BioMAC-Sim-Toolbox: A MATLAB toolbox for human movement simulation and analysis'
+title: 'BioMAC-Sim-Toolbox: A MATLAB toolbox for biomechanical motion analysis and creation through simulation'
 tags:
   - MATLAB
   - Biomechanics
@@ -54,14 +54,14 @@ forward shooting can be used to investigate neural control of gait.
 Movements of humans and other animals are extremely versatile, while our efficiency is unmatched by human-made 
 machines without having accurate or efficient controllers. Therefore, a better understanding of human movement can have a large impact for persons with movement disabilities, sports performance optimization, and design of human-made devices. Movement simulations are a key tool for creating this understanding.
 On the one hand, we can use so-called predictive simulations [@ackermann:2010; @falisse:2019;@koelewijn:2018] to investigate unseen movements by replicating the optimization in the central nervous system [@zarrugh:1974] in a computer optimization.
-On the other hand, we can use so-called reconstructive simulations to estimate variables that cannot or were not measured directly by minimizing a data tracking error [@dorschky:2019a;@nitschke:2023;@nitschke:2024]. Such wide-spread measurements and their biomechanical analysis are vital to be able to 
+On the other hand, we can use so-called reconstructive simulations to estimate variables that cannot or were not measured directly by minimizing a data tracking error [@dorscky:2019a;@nitschke:2023;@nitschke:2024]. Such wide-spread measurements and their biomechanical analysis are vital to be able to 
 reach this understanding of human movement.
 
 Here, we present `BioMAC-Sim-Toolbox`, a MATLAB toolbox that can be used to create simulations of human movement 
 and analyse human movements. The main functionality of the toolbox is that it solves trajectory optimization problems, or optimal control problems, for human musculoskeletal dynamics models. These dynamics models combine multibody 
 dynamics to model the movements of the skeleton with muscle dynamics models to model the dynamics of muscular 
 contraction and activation. In the trajectory optimization problem, the muscle stimulations are found that minimize an objective. This objective generally includes terms to minimize muscular effort and to minimize a tracking error
-with respect to measured movement data [@koelewijn:2016;@dorschky:2019a;@dorschky:2019b;@koelewijn:2022;@nitschke:2023;@nitschke:2024], but different other objectives have been implemented as well, such as 
+with respect to measured movement data [@koelewijn:2016;@dorscky:2019a;@dorschky:2019b;@koelewijn:2022;@nitschke:2023;@nitschke:2024], but different other objectives have been implemented as well, such as 
 minimization of metabolic energy expenditure [@koelewijn:2018]. The optimization problem can be described mathematically as follows:
 
 $$ \underset{\mathbf{x}(0),\mathbf{u}(t), v, T} {\text{minimize}} \quad J(\mathbf{x}, \mathbf{u}) =  \sum_{j=1}^{N_W} W_{j} \int_{t=0}^T c_{j}(x(t),u(t)) \mathrm{d} t + c_f(x(T),u(T)) $$
@@ -80,9 +80,9 @@ For walking and running, we include a periodicity constraint to the full gait cy
 
 $$ \mathbf{x}(T) = \mathbf{x}(0) + v T \mathbf{x}_{hor} \quad \text{(periodicity)} $$
 
-So far, we have created the problem class "Collocation", which creates a trajectory optimization problem using 
+So far, we have created the problem class 'Collocation', which creates a trajectory optimization problem using 
 direct collocation [@betts:2010]. In direct collocation, the numerical integration of the differential equations that represent 
-the dynamics are solved as equality constraints during the optimization. To do so, collocation nodes, or time nodes 
+the dynamics are solved as equality constraints during the optimization. To do so, collocation nodes, or time nodes, 
 need to be predefined, and the integration method should be selected. We have currently implemented a backward Euler and
 a midpoint Euler integration method. Backward Euler has shown to be most stable and has been used for publications. A 
 direct collocation approach creates a large-scale nonlinear optimization problem, for which the derivatives of the 
@@ -100,48 +100,35 @@ $$ \mathbf{x}(N+1) = \mathbf{x}(0) + v T \mathbf{x}_{hor} \quad \text{(periodici
 
 for $N$ collocation points $i$.
 
-Problems can be solved using the solvers that are implemented in the class "solver". So far, we have implemented IPOPT [@wachter:2006] to solve the resulting optimization problem. This algorithm can solve optimal control problems transcribed with direct collocation in less than 10 minutes for a 2D model [@koelewijn:2016; @koelewijn:2022] and less than one hour for a 3D model [@nitschke:2020]. Different solvers could easily be integrated into this solver class.
+Problems can be solved using the solvers that are implemented in the class 'solver'. So far, we have implemented IPOPT [@Wachter:2006] to solve the resulting optimization problem. This algorithm can solve optimal control problems transcribed with direct collocation in less than 10 minutes for a 2D model [@koelewijn:2016; @koelewijn:2022] and less than one hour for a 3D model [@nitschke:2020]. Different solvers could easily be integrated into this solver class.
 
-As most analysis is specific to the problem type, most code for analysis can be found in the respective problem class. For example, metabolic cost requires an integration over time, which is dependent on the problem type that is being used. In addition, general methods, e.g., to calculate a correlation or root mean squared error between two variables, or to write results into an OpenSim file format, can be found in the function "HelperFunctions folder". 
+As most analysis is specific to the problem type, most code for analysis can be found in the respective problem class. For example, metabolic cost requires an integration over time, which is dependent on the problem type that is being used. In addition, general methods, e.g., to calculate a correlation or root mean squared error between two variables, or to write results into an OpenSim file format, can be found in the function 'HelperFunctions' folder. 
 
 We have implemented different human dynamics models. All implemented models are musculoskeletal models, but they can 
 also be used as skeletal models, such that the input is generated using joint moments instead of muscle stimulations. 
-We have implemented a 3D model version (gait3d) and two 2D model versions in c, which are compiled as mex functions. The model dynamics can be tested using the test cases coded in the "tests" folder. The 3D model and one 2D model (gait2d_osim) are loaded from OpenSim, but use our own muscle dynamics model, which is described in [@nitschke:2020],
-while the other (gait2dc) is used in our own previous work [@koelewijn:2016; @koelewijn:2022; @dorschky:2019a; @dorschky:2019b].
-The model parameters are defined in the .osim file for the OpenSim models, and defined in an Excel file for model gait2dc (gait2dc_par.xlsx). The models can be personalized by directly adjusting the parameters in the .osim model or Excel file, such that, for example, OpenSim scaling can be used [@seth:2011]. They can also still be adjusted in MATLAB, for example to investigate virtual participants [@dorschky:2019a][@koelewijn:2022]. The model dynamics are explained further for gait2dc [@koelewijn:2022; @dorschky:2019a; @dorschky:2019b], for gait3d [@nitschke:2020]. The gait2d_osim model has not yet been used in publications. It is based on the gait10dof18musc.osim model, and can be loaded in two ways: the original version, called gait10dof18musc, and a version with the lumbar joint locked, called gait2d_osim.
+We have implemented a 3D model version (gait3d) and two 2D model versions in c, which are compiled as mex functions. The model dynamics can be tested using the test cases coded in the 'tests' folder. The 3D model and one 2D model (gait2d_osim) are loaded from OpenSim, but use our own muscle dynamics model, which is described in [@nitschke:2020],
+while the other (gait2dc) is used in our own previous work [@koelewijn:2016; @koelewijn:2022; @dorscky:2019a; @dorschky:2019b].
+The model parameters are defined in the .osim file for the OpenSim models, and defined in an Excel file for model gait2dc (gait2dc_par.xlsx). The models can be personalized by directly adjusting the parameters in the .osim model or Excel file, such that, for example, OpenSim scaling can be used [@seth:2011]. They can also still be adjusted in MATLAB, for example to investigate virtual participants [@dorscky:2019a; @koelewijn:2022]. The model dynamics are explained further for gait2dc [@koelewijn:2022; @dorscky:2019a; @dorschky:2019b], for gait3d [@nitschke:2020]. The gait2d_osim model has not yet been used in publications. It is based on the gait10dof18musc.osim model, and can be loaded in two ways: the original version, called gait10dof18musc, and a version with the lumbar joint locked, called gait2d_osim.
 
 We have included several examples in the folder 'ExampleScripts' to highlight the applications of the model and help 
 future users get started with the code. We have added two introduction examples, one for 2D simulations (script2D.m) and one for 
-3D simulations (script3D), which is based on [@nitschke:2020]. The goal of these introductory examples is to show how the toolbox works, and
+3D simulations (script3D), which is based on @nitschke:2020. The goal of these introductory examples is to show how the toolbox works, and
 highlight different options in the implementation. We have added an application in the folder 'Treadmill' to show an example use
 of the 'gait2d_osim' model, combined with an implementation of a treadmill. Based on previous 
 publications, we have added three additional applications. The code in the folder 'IMU2D' shows how simulations can be 
 created that reconstruct inertial sensor movement, and is based on the publications by @dorscky:2019a and @dorschkynitschke:2024.
 The code in the folder 'ExoPaper' shows how simulations can be used to make predictions, in this 
-case of walking with an exoskeleton, based on the paper by @koelewijn:2022. The code in MarkerTracking3D is an 
+case of walking with an exoskeleton, based on the paper by @koelewijn:2022. The code in 'MarkerTracking3D' is an 
 example of how simulations can be created by tracking marker and ground reaction force data, based on the publication by 
 @nitschke:2024.
 
 Currently, the toolbox can be used to solve trajectory optimization problems to solve predictive and reconstructive simulations. We have implemented code to track marker positions, joint angles, translations, ground reaction forces, accelerations, angular velocities, movement duration, and movement speed. We have further implemented objectives to minimize muscular effort, metabolic cost, squared torque, joint accelerations, passive joint moments, ground reaction force impact, and head stability. By combining these different objectives, many different types of simulations can be generated and the movement kinematics and kinetics investigated.
 
 In future, the toolbox can be expanded. New problem classes can be defined, for example for inverse 
-kinematics and inverse dynamics, or to solve muscle activations and stimulations statically or dynamically. Furthermore, a single shooting approach can be implemented, which would allow for models with discontinuous dynamics or control to be investigated, such as a reflex model [@geyer:2010]. 
-
-# Figures
-
-Figures can be included like this:
-![Caption for example figure.\label{fig:example}](figure.png)
-and referenced from text using \autoref{fig:example}.
-
-Figure sizes can be customized by adding an optional second parameter:
-![Caption for example figure.](figure.png){ width=20% }
+kinematics and inverse dynamics, or to solve muscle activations and stimulations statically or dynamically. Furthermore, a single shooting approach can be implemented, which would allow for models with discontinuous dynamics or control to be investigated, such as a reflex model [@Geyer:2010]. 
 
 # Acknowledgements
 
-We acknowledge contributions from Marko Ackermann, Dieter Heinrich, Maria Eleni Athanasiadou, Chuyi Wang, Christopher Löffelmann, Linus Hötzel, Utkarsha Shukla, Tobias Luckfiel, Heiko Schlarb. The development of the BioMAC-Sim-Toolbox was supported by adidas AG and by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) through Project-ID442419336, SFB 1483 - EmpkinS and through Project-ID520189992
-
-# TODOS
-- Check mu in 2D normal and 3D contact model
-- Ask Markus to add about the _osim model
+We acknowledge contributions from Marko Ackermann, Dieter Heinrich, Maria Eleni Athanasiadou, Chuyi Wang, Christopher Löffelmann, Linus Hötzel, Utkarsha Shukla, Arne Kuederle, Tobias Luckfiel, Heiko Schlarb. The development of the BioMAC-Sim-Toolbox was supported by adidas AG and by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) through Project-ID442419336, SFB 1483 - EmpkinS and through Project-ID520189992
 
 # References