From ecfc5a601913afc47c2202d7577e47ff8966d1b0 Mon Sep 17 00:00:00 2001 From: scam_goudi <91130768+gambimar@users.noreply.github.com> Date: Tue, 10 Dec 2024 16:05:08 +0100 Subject: [PATCH 1/4] Update README.md --- README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 107 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 53ff96b..f8ec8c3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,110 @@ -Instruction to start using the BioMAC-Sim-Toolbox. Extended documentation can be found here: https://mad-lab-fau.github.io/BioMAC-Sim-Toolbox/ +# BioMAC-Sim-Toolbox: The Simulation Toolbox for Biomechanical Movement Analysis and Creation -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. -3. When using the model gait3d, or gait2d_osim, it is recommended to install OpenSim from https://simtk.org/frs/?group_id=91. We currently support versions 3.3, 4.0, 4.1, 4.3, and 4.5. We have included .mat files that allow you to use the base models and those used in the ExampleScripts without an OpenSim installation. In that case, you should not recalculate the moment arms, which requires OpenSim -4. Add all folders and subfolders from "src" to the path. In the "Current Folder Browser", navigate to the folder where "src" is located. Right click, go to "add to path" and click "selected folders and subfolders". -5. To run any of the introduction scripts, make sure that the folder "ExampleScripts" is also on your MATLAB path. The folders that are named starting with a + will then also be part of the path. +## Installation -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 +### BioMAC-Sim-Toolbox -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. +First, clone this repository. Then, open MatLab, navigate to the folder where the BioMAC-Sim-Toolbox is located and add all folders and subfolders from "src" to the path: +```matlab +cd(what('BioMAC-Sim-Toolbox').path); % If not already in the BioMAC-Sim-Toolbox folder +addpath(genpath('src')); +savepath; +``` +Alternatively, you can manually add the toolbox to the path by going to the "Current Folder Browser" and navigate to the folder where "src" is located. Right click, go to "add to path" and click "selected folders and subfolders". + +When calling a model for the first time, it will be compiled automatically. 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. + +### Dependencies + +**Compilers** + +First, make sure that MatLab Compiler is installed. For **Windows**, mingw is needed. For instructions, see here: https://nl.mathworks.com/matlabcentral/answers/311290-faq-how-do-i-install-the-mingw-compiler. For Linux/MacOS, gcc should be installed by default. + +**IPOPT** + +We recommend using the obtaining the following version through the Add-On Explorer in MATLAB: https://github.com/ebertolazzi/mexIPOPT. For Mac Users using Apple Silicon native MatLab versions, follow these instructions: https://github.com/ebertolazzi/mexIPOPT/issues/24 + +**OpenSim** (optional) + +When using the model gait3d, or gait2d_osim, it is recommended to install OpenSim and its MatLab API from https://simtk.org/frs/?group_id=91. We currently support versions 3.3, 4.0, 4.1, 4.3, and 4.5. For Mac Users using Apple Silicon native MatLab versions, OpenSim is not supported currently. + +You can use the model gait3d, or gait2d_osim, without an OpenSim installation: We have included .mat files that allow you to use the base models and those used in the ExampleScripts without an OpenSim installation. In that case, you should not recalculate the moment arms, which requires OpenSim. + +## Using BioMAC-Sim-Toolbox + +This is an instruction to start using the BioMAC-Sim-Toolbox. Extended documentation can be found here: https://mad-lab-fau.github.io/BioMAC-Sim-Toolbox/ + +### Models +The BioMAC-Sim-Toolbox contains three standard models: OpenSim-based `Gait2d_osim` and `gait3d`, as well as `gait2dc`, which is defined by a spreadsheet. A model can be instanciated using its definition file: +```matlab +model_3d = Gait3d('gait3d_pelvis213.osim'); %or +model_2d_osim = Gait2d_osim('gait2d.osim'); %or +model_2dc = Gait2dc('gait2dc_par.xls'); +``` + +### Trajectory Optimization +In this example, a `Collocation` object is created for a simulation of 40 Nodes duration and backward Euler integration: + +```matlab +nNodes = 40; Euler = 'BE'; logfile = 'example.log'; plotLog = 1; +problem = Collocation(model_2dc, nNodes, Euler, logfile, plotLog); +``` +Next, we define which variables we want to optimize: states and controls. For all, we use the default lower and upper bounds that our model provides. +Our target is a simulation at 3.5m/s, therefore, we fix the speed and set the duration loosely to an interval between 0.2s and 2s. +```matlab +xmin = repmat(model_2dc.states.xmin, 1, nNodes+1); +xmax = repmat(model_2dc.states.xmax, 1, nNodes+1); +xmax(model_2dc.extractState('q', 'pelvis_tx'), 1) = 0; +xmin(model_2dc.extractState('q', 'pelvis_tx'), 1) = 0; +problem.addOptimVar('states', xmin, xmax); +problem.addOptimVar('controls',repmat(model_2dc.controls.xmin,1,nNodes+1), repmat(model_2dc.controls.xmax,1,nNodes+1)); +problem.addOptimVar('dur',0.2, 2); +problem.addOptimVar('speed',3.5,3.5); +``` + +Then, we supply the initial guess to our problem. For simplicity, we set the initial guess to 'mid', which is the middle between upper and lower bound. Setting a good initial guess can speed up the simulation, see the ExampleScripts. +```matlab +problem.makeinitialguess('mid'); +``` + +**Objectives** +In this simple example, we only optimize for muscle effort, therefore we set the weight to 1. An objective can be added the following way: +```matlab +Weffort = 1; +weightsType = 'equal'; +exponent = 3; +problem.addObjective(@effortTermMuscles, Weffort, weightsType, exponent); +``` + +**Constraints** +In our example, we make use of `@dynamicConstraints` for dynamically consistent output. We also set `@periodicityConstraint` for half-gait-cycle periodicity. +```matlab +problem.addConstraint(@dynamicConstraints,repmat(model_2dc.constraints.fmin,1,nNodes),repmat(model_2dc.constraints.fmax,1,nNodes)) +problem.addConstraint(@periodicityConstraint,zeros(model_2dc.nStates+model_2dc.nControls,1),zeros(model_2dc.nStates+model_2dc.nControls,1),1) +``` + +**Calling IPOPT** +By adding objectives and constrained, the problem is now defined and can be solved using IPOPT in our default settings: +```matlab +solver = IPOPT(); +result = solver.solve(problem); +``` + +**Inspecting Results** +To show a video of the resulting motion, call the `Collocation.writeMovie` function. +```matlab +result.problem.writeMovie(result.X); +``` +Note that the output of this example isn't quite realistic, as muscle effort alone is not sufficient to describe walking or running. + +The above example is a simplified version of `script2D`, and we created introduction examples for all models in the toolbox: +- **gait2dc**: `IntroductionExamples.script2D` +- **gait2d_osim**: `Treadmill.script2D` +- **gait3d**: `IntroductionExamples.script3D` + +To run any of the introduction scripts, make sure that the folder "ExampleScripts" is also on your MATLAB path. The folders that are named starting with a + will then also be part of the path. + + +## Citation + +If you are using our toolbox in your research, we would be glad for a citation. Our _paper_ is still under review, we will update the citation. Follow us on ... for updates. From 920dded60b76eaea014345123003e682002b2985 Mon Sep 17 00:00:00 2001 From: Anne Koelewijn Date: Tue, 10 Dec 2024 16:13:27 +0100 Subject: [PATCH 2/4] Update README.md Some typos and extension --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f8ec8c3..c9e24b4 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ First, make sure that MatLab Compiler is installed. For **Windows**, mingw is ne **IPOPT** -We recommend using the obtaining the following version through the Add-On Explorer in MATLAB: https://github.com/ebertolazzi/mexIPOPT. For Mac Users using Apple Silicon native MatLab versions, follow these instructions: https://github.com/ebertolazzi/mexIPOPT/issues/24 +We recommend using the following version which can be obtained through the Add-On Explorer in MATLAB: https://github.com/ebertolazzi/mexIPOPT. For Mac Users using Apple Silicon native MatLab versions, follow these instructions: https://github.com/ebertolazzi/mexIPOPT/issues/24 **OpenSim** (optional) @@ -107,4 +107,4 @@ To run any of the introduction scripts, make sure that the folder "ExampleScript ## Citation -If you are using our toolbox in your research, we would be glad for a citation. Our _paper_ is still under review, we will update the citation. Follow us on ... for updates. +If you are using our toolbox in your research, we would be glad for a citation. Our _paper_ is still under review, we will update the citation as soon as it is available. Follow Anne Koelewijn on BlueSky or LinkedIn for updates. From bb256e8c2264e5a56535488f89e936338274543b Mon Sep 17 00:00:00 2001 From: scam_goudi <91130768+gambimar@users.noreply.github.com> Date: Thu, 16 Jan 2025 17:40:11 +0100 Subject: [PATCH 3/4] Add contributing statement --- CONTRIBUTING.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6c6a616 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,136 @@ + +# Contributing to BioMAC-Sim-Toolbox + +First off, thanks for taking the time to contribute! + +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉 + +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: +> - Star the project +> - Tweet about it +> - Refer this project in your project's readme +> - Mention the project at local meetups and tell your friends/colleagues + + +## Table of Contents + +- [I Have a Question](#i-have-a-question) + - [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Your First Code Contribution](#your-first-code-contribution) + - [Improving The Documentation](#improving-the-documentation) +- [Styleguides](#styleguides) + - [Commit Messages](#commit-messages) +- [Join The Project Team](#join-the-project-team) + + + +## I Have a Question + +> If you want to ask a question, we assume that you have read the available [Documentation](https://mad-lab-fau.github.io/BioMAC-Sim-Toolbox/). + +Before you ask a question, it is best to search for existing [Issues](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first. + +If you then still feel the need to ask a question and need clarification, we recommend the following: + +- Open an [Issue](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/issues/new). +- Provide as much context as you can about what you're running into. +- Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant. + +We will then take care of the issue as soon as possible. + + + +## I Want To Contribute + +Before contributing, please check our [coding guidelines](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/tree/main/docs/Coding_Guidelines.md). + +> ### Legal Notice +> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project licence. + +### Reporting Bugs + + +#### Before Submitting a Bug Report + +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](https://mad-lab-fau.github.io/BioMAC-Sim-Toolbox/). If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/issues?q=label%3Abug). +- Also make sure to search the internet (including Stack Overflow) to see if users outside of the GitHub community have discussed the issue. +- Collect information about the bug: + - Stack trace (Traceback) + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) + - Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant. + - Possibly your input and the output + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? + + +#### How Do I Submit a Good Bug Report? + +> You must never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to <>. + + +We use GitHub issues to track bugs and errors. If you run into an issue with the project: + +- Open an [Issue](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. +- Provide the information you collected in the previous section. + +Once it's filed: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced. +- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution). + + + + +### Suggesting Enhancements + +This section guides you through submitting an enhancement suggestion for BioMAC-Sim-Toolbox, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions. + + +#### Before Submitting an Enhancement + +- Make sure that you are using the latest version. +- Read the [documentation](https://mad-lab-fau.github.io/BioMAC-Sim-Toolbox/) and [coding guidelines](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/tree/main/docs/Coding_Guidelines.md) carefully and find out if the functionality is already covered, maybe by an individual configuration. +- Perform a [search](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. +- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library. + + +#### How Do I Submit a Good Enhancement Suggestion? + +Enhancement suggestions are tracked as [GitHub issues](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/issues). + +- Use a **clear and descriptive title** for the issue to identify the suggestion. +- Provide a **step-by-step description of the suggested enhancement** in as many details as possible. +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you. +- You may want to **include screenshots or screen recordings** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [LICEcap](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and the built-in [screen recorder in GNOME](https://help.gnome.org/users/gnome-help/stable/screen-shot-record.html.en) or [SimpleScreenRecorder](https://github.com/MaartenBaert/ssr) on Linux. +- **Explain why this enhancement would be useful** to most BioMAC-Sim-Toolbox users. You may also want to point out the other projects that solved it better and which could serve as inspiration. + + + + +## Guidelines +For any code-contribution, please follow our [guidelines](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/tree/main/docs/Coding_Guidelines.md) for code formatting and documentation. + + +## Attribution +This guide is based on the [contributing.md](https://contributing.md/generator)! From 72f61861a96e15700475a1bec5188ed36cb3d876 Mon Sep 17 00:00:00 2001 From: scam_goudi <91130768+gambimar@users.noreply.github.com> Date: Thu, 16 Jan 2025 17:40:48 +0100 Subject: [PATCH 4/4] Uploaded coding guidelines --- docs/Coding_Guidelines.md | 446 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 446 insertions(+) create mode 100644 docs/Coding_Guidelines.md diff --git a/docs/Coding_Guidelines.md b/docs/Coding_Guidelines.md new file mode 100644 index 0000000..5af66fd --- /dev/null +++ b/docs/Coding_Guidelines.md @@ -0,0 +1,446 @@ +# BioMAC-Sim-Toolbox: Coding Guidelines + +This coding guidelines explain applied naming conventions and implementation principles. At the moment not all guidelines were applied in the code. Feel free to change and improve the code ;) + +## Folders and Files +The folder structure of the protect is currently the following: + +```` +|-- project home directory +| |-- docs +| | |-- Doxygen +| | |-- files +| |-- src +| | |-- HelperFunctions +| | |-- model +| | | |-- gait2dc +| | | | |-- ... +| | | |-- gait2d_osim +| | | | |-- ... +| | | |-- gait3d +| | | | |-- ... +| | | |-- Model.m +| | |-- problem +| | | |-- @Collocation +| | | |-- Problem.m +| | | |-- ... +| | |-- result +| | | |-- ... +| | |-- scripts +| | | |-- ... +| | |-- solver +| | | |-- IPOPT.m +| | | |-- Solver.m +| | |-- tests +| | | |-- Gait2dcTest.m +| | | |-- gait3dTest.m +| | | |-- ModelTest.m +| | | |-- ... +| | |-- Toolboxes +| | |-- trackingData +| | | |-- @TrackingData +| | |-- ... +| |-- ... +```` + + +In Matlab, classes can have a own class folder named `@`. This folder contains the file defining the model class (e.g.: Gait2dc.m) and other functions of this class (e.g.: simuAccGyro.m). This other functions have to be declared in the class file but the content is implemented in a separate file. + + +## Classes +- Starting with uppercase +- E.g.: `Model`, `Problem`, `Collocation`, ... + +## Functions +- Starting with lowercase +- New word starts with uppercase +- `initModel()`, `initMex()`, `solve()`, ... +- Exception: Constructors + +## Properties +- Starting with lowercase +- Numbers: + - `n` + - E.g.: Number of `dofs` is `nDofs` +- Single index: + - Used in loops + - `i` + - E.g.: + ```matlab + for iDof = 1 : obj.nDofs + disp(num2str(iDof)); + end + ``` +- Multiple indices in an array: + - Parameter + - `idx` + - E.g.: `idxArmdof` +- Hidden properties: + - Used to save the content of dependent variables + - `h` + - E.g.: `hidxArmdof` for `idxArmdof` +- Constants: + - Uppercase + - E.g.: `GRAVITY` in the Gait3d-Class + +## Default Values +- Should be set in property definition: + ```matlab + properties (SetObservable, AbortSet, SetAccess = protected) + %> Bodyheight in m (default: 1.80) + bodyheight = 1.80 + end + ``` +- Or it should be set in the constructor: + ```matlab + function [obj] = IPOPT() + % Set default options for termination + obj.solverOptions.tol = 0.0002; % Desired convergence tolerance + obj.solverOptions.max_iter = 4000; % Maximum number of iterations + % ... + end + ``` +- Do not change them in the code! +- Use setter function to change the value after object creation. If needed, write an own setter function. + +## Inheritance +- Use inheritance instead of changing the functionality of the basic class. +- E.g.: + ```` + handle + |--Model + |-- Gait2dc + |-- Gait3d + |-- Gait2d_osim + ```` + +# How to Use Git Within this Project +First of all use git with all it's advantages. You can find a good introduction (with links to good tutorials) and a good tutorial for advanced users here: +[Git-Tutorial](https://www.atlassian.com/git/tutorials) + + +## Access +Our project can be found in the MaD GitHub which is hosted on our own server: [Git repository](https://github.com/mad-lab-fau/BioMAC-Sim-Toolbox/tree/main) + +## Commits + +Please, commit each atomic change and do not combine several changes in one commit. An atomic change is for example a change in a calculation, or a bug fix. + +The commit message should contain this important points: + +- One summary line (corresponds to a header in the webview) +- What you changed (not code-wise, but content-wise) +- Why you changed this +- If there were some changes in usage etc. + +## Issues and Milestones +Use issues to discuss about a specific topic. It offers a perfect possibility to keep track on the discussion or to come back at a later point in time. + +Issues can be assigned to milestones. A milestone could be a publication or the implementation of a new feature. + +## Line Endings +Git handles line endings differently on each operation system. To avoid differences produced by line endings please set up your git: + +- On Windows: `git config --global core.autocrlf true` +- On Linux/Mac: `git config --global core.autocrlf input` + +# How to Document with Doxygen +The new Gait3d-project is documented using [Doxygen](http://www.stack.nl/~dimitri/doxygen/). + +It will use all files in the folder src for documentation. + +## Doxygen and Matlab +The perl script m2cpp.pl is used to extract comments from Matlab .m files. (http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab) + +## Installation on Windows +- Install Doxygen, e.g. from [Sourceforge](http://sourceforge.net/projects/doxygen/) +- Run cmd as administrator and type: + ```bash + assoc .pl=PerlScript + ftype PerlScript=C:\Program Files\MATLAB\R2014b\sys\perl\win32\bin\perl.exe %1 %* + ``` + Note: You need to replace the perl path accordingly, which can be found by e.g. typing `which perl` in the command window (MinGW/Cygwin). Perl is installed with e.g. Matlab. This should allow to run a perl script by typing `*.pl` instead of `perl *.pl`. + + If this does not work, you have to make changes in the windows registry. Open "regedit" by searching it in the windows start menu. + + Open HKEY_CLASSES_ROOT $\rightarrow$ Applications $\rightarrow$ perl.exe $\rightarrow$ shell $\rightarrow$ open $\rightarrow$ command and add + `\%*` + to the value. + E.g. change the value from + ```bash + "C:\Program Files\MATLAB\R2014b\sys\perl\win32\bin\perl.exe" "%1" + ``` + to + ```bash + "C:\Program Files\MATLAB\R2014b\sys\perl\win32\bin\perl.exe" "%1" %* + ``` + + The location in the windows registry could be different. +- Delete the first line of m2cpp.pl file, i.e. delete + ```bash + #!/usr/bin/perl.exe + ``` + +## Installation on UNIX (including Mac OS X) +- Install Doxygen, e.g. from [Sourceforge](http://sourceforge.net/projects/doxygen/) +- Set variable PERL\_PATH in Doxyfile, which can be found by typing `which perl` in the command window, e.g. `PERL_PATH = /usr/bin/perl` +- Change the first line of m2cpp.pl file to your perl path and delete `.exe`: + ```bash + #!/usr/bin/perl + ``` + +## Usage +- If you are using Doxygen on a Linux machine you have to adapt the file docs/Doxygen/Doxyfile. There you have to replace + ```bash + FILTER_PATTERNS = *m=m2cpp.pl + ``` + with + ```bash + FILTER_PATTERNS = *.m="perl m2cpp.pl" + ``` + Please do not commit this changes. +- Open the command-line interface, change directory to the folder docs/Doxygen and run: + ```bash + doxygen Doxyfile + ``` +- Open html documentation: docs $\rightarrow$ Doxygen $\rightarrow$ Doxygen\_HTML $\rightarrow$ index.html + +# How to Document + +In Matlab files, Doxygen will evaluate only lines starting with `%>`. +Each command starts with `@`. +If you type file, class or function names they will be linked to the respective description. + +## Each File +Each file (classes, functions, etc.) should contain first a header describing really shortly the content, the authors and the date: + +```matlab +%==================================================================== +%> @file @Gait2dc/Gait2dc.m +%> @brief Matlab class describing the Gait2dc model +%> +%> @author Ton, Eva, Marlies, Anne +%> @date October, 2017 +%===================================================================== +``` + +This brief description will be shown in the tab "Files". +A click on it will show the full information. + +## Classes +Before each class definition: +```matlab +%====================================================================== +%> @brief The class describes the Gait2dc model +%> @details +%> - The lower body is modeled in the sagittal plane. +%> - The model is configured using an excel file. This code relies on the +%> structure of this file (hardcoded indices for each section in the file). +%> Please don't change the structure. Thus the order of the table entries +%> should not be changed!!! +%> - For the list with the CPs, additional CPs can be added. +%===================================================================== + +classdef Gait2dc < Model + %... +end +``` +\medskip +This should contain at least a +- short description marked with `@brief`and starting with an uppercase and +- detailed description marked with `@details` and starting in a new line with an uppercase. + +## Properties +The description of each property must be above the property declaration: +```matlab +properties (SetObservable, AbortSet) + %> Array with lambda values (default: [0.01 0.1]) (1x2) + lambda = [0.01 0.1] + %> Gravity in y in m/(s^2) + gravity +end +```` +This description should start with uppercase and should contain +- data type (e.g.: struct, string, array, etc.), +- a description, +- used default value, +- unit, +- size specified in brackets (use variables to define it!). + +## Functions +Before each function definition: +```matlab +%====================================================================== +%> @brief Function returning muscle forces for the system in state x +%> +%> @details +%> This function calls the mex file of gait2dc.c: +%> [forces] = gait2dc('Muscleforces', x); +%> +%> @param obj Gait2dc class object +%> @param x State of the model (obj.nStates x 1) +%> +%> @retval forces Muscle forces (in N) (obj.nMus x 1) +%====================================================================== +function [muscleForces] = getMuscleforces(obj, x) + ... +end +``` +\medskip +This description should contain +- a brief description marked with `@brief` + - one line + - starting with uppercase in the same line +- a detailed description marked with `@details` + - can be multiple lines and paragraphs + - starting with uppercase in the next line +- all function and return parameters marked with `@param` and `@retval`. + - The formatting is not preserved but recommended for readability in the matlab file. + - The description should start with an uppercase and should contain + - data type (e.g.: struct, string, array, etc.), + - a description, + - used default value, + - unit, + - size specified in brackets (use variables to define it!). + - Mark optional parameters with `(optional)` at the beginning of the description. + +## Functions in Separate Files +If a function is save in a separate file, there should be no Doxygen comment above the declaration in the class file. Doxygen would link this to the wrong function. + +```matlab +% Declared function to simulate acceleration and gyroscope signals +[s, ds_dq, ds_dqd, ds_dqdd] = simuAccGyro(obj, data, q, qd, qdd) +``` + +In the file containing the implementation, a file header as well as a function header must be used: +```matlab +%====================================================================== +%> @file @Gait2dc/simuAccGyro.m +%> @brief Gait2dc function to simulate acceleration and gyroscope signals +%> @details +%> Details: Gait2dc::simuAccGyro() +%> +%> @author Ton, Eva, Iris, Ann-Kristin, Marlies +%> @date July, 2017 +%====================================================================== + +%====================================================================== +%> @brief Function to simulate acceleration and gyroscope signals +%> @details +%> Do not change the "obj" or "data" struct in this function! This will allow +%> Matlab to "pass by reference" and avoid function call overhead. +%> +%> @param obj Gait2dc object +%> @param data Struct containing the accelerometer and gyroscope data +%> @param q Generalized coordinates (obj.nDofs x 1) +%> @param qd First derivatives of generalized coordinates (obj.nDofs x 1) +%> @param qdd Second derivatives of generalized coordinates (obj.nDofs x 1) +%> +%> @retval s Simulated sensor signals (data.nVars.all x 1) +%> @retval ds_dq Sparse Jacobian ds/dq (data.nVars.all x obj.nDofs) +%> @retval ds_dqd Sparse Jacobian ds/dqd (data.nVars.all x obj.nDofs) +%> @retval ds_dqdd Sparse Jacobian ds/dqdd (data.nVars.all x obj.nDofs) +%====================================================================== +function [s, ds_dq, ds_dqd, ds_dqdd] = simuAccGyro(obj, data, q, qd, qdd) + ... +end +``` + +The brief file description should state the class the method belongs to. Furthermore, the class should be directly linked in the detailed file description. In this way, you have in the file description the direct link to the function description. + +For + +For a correct assignment, it is recommended to add `@public`, `@protected`, or `@private` after the brief description of the function. This was not done in the example shown above. Consequently Doxygen marked simuAccGyro() as protected even if it was implemented as public function. + +## Abstract Functions +Doxygen recognized abstract functions only if you put it in a specific method-block: + +```matlab +methods (Abstract) + % ====================================================================== + %> @brief Abstract function to show model as stick figure + % ====================================================================== + showStick(obj,x) +end +``` + +## TODOs +You can found the todo list in the tab "Related Pages". There is a todo list for everybody of us and a general todo list. + +This are the commands to use the lists: +- General todo list: `@todo` +- Named todo list: `@todo` + + +It is important to write the todos into the header of a class or a function. Otherwise it will not be linked to the correct content! + +Example: +```matlab +%====================================================================== +%> @brief Function defining the state table +%> +%> @details +%> Table lists type, name, xmin, xmax and xneutral +%> +%> @todo +%> Variables of contact points of neutral position shouldn't be zero. +%> +%> @param obj Gait2dc class object +%====================================================================== +function update_states(obj) + ... +end +``` + +Even if there is a functionality in Doxygen to report bugs, bugs should be listed in the issues of the git repository. + +## Formatting +- White space is not preserved. +- A new line in Matlab does not mean a new line in the documentation. + - Use `/n` to enforce a new line. + - Use a blank line to start a new paragraph. + ```matlab + %> @details + %> First paragraph + %> + %> Second paragraph + ``` +- Code snippets: + - To show usage of the function. + - E.g.: + ```matlab + %====================================================================== + %> @brief Test class to test the class Gait2dc + %> + %> @details + %> - run single test: + %> @code + %> testCase = Gait2dcTest; + %> res = run(testCase, 'derivativetest_Dynamics'); + %> @endcode + %> - run all tests: + %> @code + %> Tests = matlab.unittest.TestSuite.fromClass(?Gait2dcTest); + %> res = run(Tests); + %> @endcode + %====================================================================== + classdef Gait2dcTest < ModelTest + ... + end + ``` +- Lists + - Useful for structs. + - https://www.stack.nl/~dimitri/doxygen/manual/lists.html: + - "By putting a number of column-aligned minus (-) signs at the start of a line, a bullet list will automatically be generated. Instead of the minus sign also plus (+) or asterisk (*) can be used." + - "Numbered lists can also be generated by using a minus followed by a hash or by using a number followed by a dot." + - E.g.: + ```matlab + %> Struct containing initialization parameters with the fields: + %> - flag: Boolean showing if the model is initialized. + %> - Nf: Number of functions returned by the Dynamics function. + %> - fmin: Lower bounds for dynamics residuals f. + %> - fmax: Upper bounds for dynamics residuals f. + ``` +- HTML Commands + - For example for Greek letters. + - E.g.: `φ`