Developer's Workshop 2016

Welcome to the OpenSim Developer Week Wiki. The information in this Wiki page is intended to help you formulate a project that may both benefit from the OpenSim 4.0 API and is tractable for a one-week workshop. This wiki will be updated regularly so please check in as we get closer to the workshop.  

Project Goals and Accomplishment Slides

On the first day, you will all present your Project Goals slides. The workshop slides (two per project) are intended to help the OpenSim team and your fellow Workshop attendees understand your work, ask questions, and give feedback and support where possible. Follow the link to the Google Slides presentation and follow the instructions to create your slide.

The Workshop Accomplishment slides can be found here. The Accomplishment slides are an opportunity to share your accomplishments, your challenges, and what you’ve learned. Each group should have at most three slides, including a single goal slide. Please complete your slides by noon, Friday, when voting for project awards will start. 

Building OpenSim

The workshop will have hands-on examples using the new OpenSim 4.0 API. In preparation, you will need to set up your build environment (Visual Studio or Xcode, CMake, etc.) before Monday. Detailed instructions for obtaining the OpenSim source code and compiling it are on the main Github page, but here are some particulars:

1. Create a GitHub account.
2. Install command-line git, and make sure you obtain the OpenSim source code by cloning the GitHub repository (not by downloading a ZIP file).
3. If you are using Windows and plan to use the MATLAB scripting in 4.0, then you must build OpenSim as 32-bit if you have 32-bit MATLAB, or as 64-bit if you have 64-bit MATLAB. If you are using Windows but not MATLAB, then compile OpenSim as 32-bit--it compiles faster!
4. OpenSim takes a while to build. You will need at least an hour to do this; even more if you have not done it before. We will likely make bug fixes to OpenSim over the weekend, so you will need to update your build on Monday morning; this “incremental build” will be much quicker.

If you have any issues or questions, please don’t hesitate to email us at opensim@stanford.edu.

API Documentation

The (draft) API documentation for the workshop can be downloaded here and a pocket guide here. These guides include short descriptions of the important classes as well as a quick guide to the API structure and common commands. The current doxygen for OpenSim 4.0 can be found here: http://doxygen.opensim.community/.

Contributing Lecture 

A pdf copy of the lecture on contributing to OpenSim via git and Github can be downloaded here.

Location and Coffee

The workshop location is at Stanford University, Clark Center, S361 (third floor, door S3.3, through Peet’s Coffee). Directions and maps to the Clark Center can be found here. On the first day we will provide light continental breakfast items. Breakfast will be on your own on subsequent days but we will provide some light snacks and lots of coffee throughout the Workshop to help maximize productivity.

Agenda

This is a five-day workshop. On the first day of the workshop, we will provide an overview of OpenSim 4.0, with discussions, guided exercises, and interactive lectures to introduce the new features. The second day will consist of guided exercises on contributing using GitHub and how you can incorporate collaboration and contribution to your project. Days three and four will be devoted to working on projects that you and other participants bring to the workshop. Day five will include group discussions and presentations about your workshop achievements and plans for wrapping up your development.

Note: This detailed agenda is subject to change.

OpenSim 4.0

OpenSim 4.0 will allow for greater access and flexibility to software builders, making possible what may have been impossible in previous releases. Below is a list of 4.0 feature descriptions and some enabled projects to give you a sense of the types of development projects that were not possible before or that are now significantly easier.  Though the workshop will predominantly use the new 4.0 API, people who are developing new tools for the OpenSim 3 releases are also encouraged to apply. 

Features in Version 4.0

1. Nested model components. Compose a complex model from simpler more robust/testable subcomponents; for example, a muscle model can be composed of standalone activation dynamics and fiber dynamics subcomponents. As a result, components have a “path name”; e.g., “soleus_r/fiber,” We also improved the mechanism for accessing the components within a model by either path name or type.

2. Connectors between model components. Components depend on each other: joints connect two bodies, muscles need wrapping surfaces, etc. We have formalized the method for specifying the connections between components to make it easier to build modular models and to make these connections far less bug-prone.

3. Reference Frames. Performing and reporting kinematic transforms is one of the most useful functions of a multibody model and defining reference frames is essential for transforming data. Frames are new abstraction for defining and attaching reference frames in OpenSim and they have the ability to re-express quantities (positions, velocities, etc.) defined in one Frame to any other Frame.

4. Simulink-style wiring of signals between components. Each component can have Inputs and Outputs. Any model-computed value based on the state is a candidate as an Output, and can be wired to another component’s Input. A Reporter is no longer an inflexible Analysis but a modular Component that reads from designated Outputs and writes to in-memory data tables of results. That means no more reading storage files just to access a computed quantity.

5. Use any data file format you want. A new DataTable class replaces Storage as OpenSim’s primary container for simulation inputs and outputs. You can create a DataTable from any file format (.sto, .csv, .c3d) using the new Adapter classes. Adapters convert files of various formats to DataTables consumable by OpenSim Solvers and Tools. DataTables generated by Solvers can also be written out to various files via an adapter.

6. Save exact simulation results to a file. The new StatesTrajectory class allows perfect replay of simulations from ForwardDynamics and CMC without loss of precision (as with states storage files) or of the values for non-continuous state variables (e.g. modeling options and discrete state variables).

7. Compose your own “Study” by walking through States, realizing Model dynamics and accelerations, and piping Outputs to Reporters and writing results to a file format of your choice.

8. Extend OpenSim classes through Python (e.g., write your Analysis class in Python instead of C++).

Projects Enabled by New Features in 4.0

These first few projects could be completely prototyped in the one week of the workshop:

1. Pure kinematics study. Using coordinate information only, differentiate them to estimate velocity and acceleration and report the position, velocity and/or acceleration of Frames of interest.

2. Custom muscle analysis. From simulation results (stored in a StatesTrajectory), extract internal muscle variables (tendon strain, pennation angle, active force, force-velocity multiplier, etc.) and write them to a file without other information (moments, moment-arms, etc.) coming for the ride.

3. New data file format (e.g., .mat, .anc, .xls). By implementing a single class that reads and writes your desired file format, you can then use that file format in any OpenSim tool.

4. A Component that computes the net moment/force from a segment of the multibody tree. This calculation could be used as boundary conditions in a finite element model. Before 4.0, this would have been a new type of Analysis. 

5. A Component that computes the point of force application, to visualize a contact model. Before 4.0, this would have been a new type of Analysis. 

The following projects would require more than one week to complete, but a portion of the project would be suitable for the workshop:

1. Configurable muscle model. Modeling fatigue or different fiber type dynamics does not require authoring yet another complete muscle model. Instead, existing muscle models with constituent components (for activation dynamics, fiber kinematics, and tendon dynamics) can be overridden to include additional activation and fiber states with associated differential equations. During the workshop, participants could implement a fatigue model from a publication.

2. Parametric model fitting using Frames (instead of scale factors). Since joint locations and muscle origins and insertions can all be specified with respect to Frames, the parameters that define a single Frame can transform muscle attachments and joint axes, for example to represent tibial torsion or otherwise elongate/shorten and bend bones. During the workshop, participants could achieve a working prototype for a simple toy model, especially in MATLAB or Python.

3. Live data streaming for real-time use of OpenSim solvers. Populate an OpenSim DataTable from a streaming data source and visualize the resulting inverse kinematics or inverse dynamics solution in real-time. During the workshop, participants could connect the streaming data source to an OpenSim DataTable.

Additional Example Projects

These projects could be done without the new features in version 4.0, and are still good candidates for the workshop.

1. Implicit model formulation. OpenSim currently provides the model's dynamics as explicit differential equations, though implicit differential equations are preferable for some solution methods. During the workshop, participants could achieve the implicit formulation for just the multibody system without constraints.

2. Task-space controller. Implement an OpenSim Controller that causes a torque-actuated model to obey operational-space tasks. During the workshop, participants could achieve a working prototype for a small number of operational space tasks.

3. Patient-specific joint modeling from high-fidelity data. Joints in OpenSim are capable of capturing coupled translations and rotations as functions of limited degrees-of-freedom known as internal coordinates, which better match physiological joints than pins and sliders. In reality, it is the contact joint surfaces of bones, tension in ligaments, and other non-rigid structures such as menisci and capsules that dictate the specific path (or surface) of motion that a  joint provides under normal loads but these structures can be extremely difficult to model and simulate very slowly. On the other-hand researchers are using high-fidelity X-ray fluoroscopy, cine MRI, or bone pin measurements to characterize the kinematics of bones relative to one another during activities of daily living. The OpenSim Joint can directly capture/match the specific motion space as provided by high-fidelity data. During the workshop, available spatial kinematics of the two bones that connect to the joint of interest (such as the ankle, knee, or hip) from a high-fidelity source could be used to generate splines (or bicubic surface) such that the modeled joint reproduces nearly identical motion without having to model joint contact or other joint tissue forces.

4. Script based analysis pipeline. Automate your OpenSim workflow (e.g., IK -> RRA -> CMC) in either MATLAB or Python. This could be completed during the workshop for a subset of your data.

5. Modeling human-device interaction (e.g., robotic assistive device). Create a model of your device and add it to a musculoskeletal model. Write an OpenSim Controller class to control the device. During the workshop, participants could implement the Controller class and test it in simple scenarios.

6.