Constrained lateral pinch model

This folder contains a modified batch script derived from the original ARMS hand and wrist model workflow by McFarland et al. The original optimization framework was preserved, while the script was adapted to:
(1) execute 50 repeated optimization runs,
(2) save the optimal activation vectors and objective values,
(3) re-run forward-dynamics simulations using the optimal activations,
(4) record optimization and forward simulation times, and
(5) use relative paths for portability.

The musculoskeletal model is based on:
McFarland DC, Binder-Markey BI, Nichols JA, Wohlman SJ, de Bruin M, Murray WM.
A Musculoskeletal Model of the Hand and Wrist Capable of Simulating Functional Tasks.
IEEE Transactions on Biomedical Engineering, 2023.

Users must cite the original ARMS model publication when using this material.

---------------------------------------------------------------------

Folder structure:

- model/:
    Contains the OpenSim model file (Pinch_Model.osim) and the Geometry folder.

- templates/:
    Contains template files required for simulations:
    Controls.sto and setup.xml.

- output/:
    Automatically generated folder where simulation results are stored.

---------------------------------------------------------------------

Requirements:

- MATLAB (tested with R2023a or later)
- OpenSim (version compatible with the ARMS model)

---------------------------------------------------------------------

Execution:

1. Open MATLAB.
2. Navigate to this folder.
3. Run the script:
       run_constrained_pinch_batch

All paths are defined relative to the script location. The script will automatically generate the output/ folder and store all simulation results there.

---------------------------------------------------------------------

Notes:

- Each simulation is stored in a separate subfolder within the output/ directory.
- The script may require significant computation time due to repeated optimization runs.

---------------------------------------------------------------------

Generated outputs:

Running the script creates an output/ folder containing:

- pinch_force_batch.mat
    MATLAB file storing batch-level summary variables, including:
    objective values, optimal activation vectors, optimization times,
    forward-dynamics times, exit flags, and iteration counts.

- pinch_force_timing_summary.xlsx
    Excel file containing a summary table with, for each simulation:
    simulation ID, objective value, optimization time, forward simulation
    time, total time, exit flag, and number of iterations.

- sim_001/, sim_002/, ..., sim_050/
    One folder per simulation. Each folder contains the files associated
    with the optimal forward-dynamics re-run for that simulation.

Within each simulation folder, the following files are generated:

- Controls_optimal.sto
    Control file containing the constant optimal activations used in the
    forward-dynamics simulation.

- default_activation_optimal.osim
    Model file with the corresponding optimal default muscle activations.

- setup_optimal.xml
    ForwardTool setup file generated for that simulation.

- results_optimal/
    Folder containing the OpenSim outputs of the optimal forward-dynamics
    simulation (e.g., force and state time histories).

During optimization, an additional temporary folder may also be created:

- objective_eval/
    Internal working folder used for objective-function evaluations.