Documentation and README comments

[Aravind-Sundararajan]

Clarify Instructions and Formatting

• Wrap code blocks properly in triple backticks with language tags.

• Use bullet points for clearer step-by-step instructions.

Installation Section Example Rewrite (an example but feel free to edit yourself):

## Installation

1. Clone this repository:
```bash
git clone https://github.com/MAD-Lab-FAU/BioMAC-Sim-Toolbox.git

2. Open MATLAB and add the src directory and its subfolders to your path:

cd(what('BioMAC-Sim-Toolbox').path);  % Only if not already in the folder
addpath(genpath('src'));
savepath;

Alternatively, you can manually add the folder:

• In MATLAB's "Current Folder" browser, navigate to the src folder.
• Right-click -> Add to Path -> Selected Folders and Subfolders.

Dependencies Section Rewrite (an example but feel free to edit yourself)

## Dependencies

- **MATLAB Compiler**: Required. On Windows, install MinGW via [these instructions](https://nl.mathworks.com/matlabcentral/answers/311290-faq-how-do-i-install-the-mingw-compiler).
- **IPOPT**: Use [mexIPOPT](https://github.com/ebertolazzi/mexIPOPT). Mac users with Apple Silicon should follow [these instructions](https://github.com/ebertolazzi/mexIPOPT/issues/24).
- **OpenSim (Optional)**: Needed for `gait3d` and `gait2d_osim` models. Supported versions: 3.3–4.5. For macOS + Apple Silicon, OpenSim is currently not supported.

Examples & Usage
Improve Flow and Formatting of Example

Break into well-titled code blocks with explanatory text:

## Using BioMAC-Sim-Toolbox

### Model Loading

```matlab
model_3d = Gait3d('gait3d_pelvis213.osim');
model_2d_osim = Gait2d_osim('gait2d.osim');
model_2dc = Gait2dc('gait2dc_par.xls');

Trajectory Optimization

Set up the optimization problem:

nNodes = 40;
problem = Collocation(model_2dc, nNodes, 'BE', 'example.log', 1);

Define variables:

% States
xmin = repmat(model_2dc.states.xmin, 1, nNodes+1);
xmax = repmat(model_2dc.states.xmax, 1, nNodes+1);
% Fix pelvis translation at initial node
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);

Add objective:

problem.addObjective(@effortTermMuscles, 1, 'equal', 3);

Add Constraints:

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);

Solve:

solver = IPOPT();
result = solver.solve(problem);

Visualize:

result.problem.writeMovie(result.X);

Highlight Limitations or Caveats

• Explicitly note that muscle-effort-only optimization yields unrealistic gait, and more objectives (e.g., stability, ground reaction forces) are often necessary.

Citation

• Make it a Proper Section with a Placeholder BibTeX Entry

## Citation

If you use BioMAC-Sim-Toolbox in your research, please cite us. A publication is under review and will be linked here soon.

Follow [Anne Koelewijn](https://www.linkedin.com/in/anne-koelewijn/) on LinkedIn or BlueSky for updates.

```bibtex
@misc{BioMACSimToolbox2025,
  author = {Koelewijn, Anne and others},
  title = {BioMAC-Sim-Toolbox: A Simulation Toolbox for Biomechanical Movement Analysis and Creation},
  year = {2025},
  note = {Manuscript in review},
  url = {https://github.com/MAD-Lab-FAU/BioMAC-Sim-Toolbox}
}

Minor Improvements

• Fix typos: e.g., "instanciated" -> "instantiated"
• Use consistent naming: "MatLab" -> "MATLAB"
• Use markdown fenced code blocks everywhere instead of indentation or inline code for multi-line examples.

This issue is part of a JOSS review.

[adkoele]

Thanks for these suggestions, they were very helpful. We have addressed them. Would you want us to tick the boxes or do you want to check yourself?

[Aravind-Sundararajan]

hello @adkoele when you think the concerns are addressed, check the boxes