API Upgrade Notes for OpenSim 3.0

API Users should be aware of several changes to the OpenSim API in 3.0:

1. A note to API users with existing plugins and main programs:  Both OpenSim libraries and its dependency on Simbody libraries are being simplified and some libraries (such SimTKcpodes.lib) are no longer separate dependencies and are now part of the new SimTKsimbody library. This means existing projects that are seeking these libraries will fail to link and build. We advise users to replace their CMake files for their plugins and main programs with CMake files distributed with OpenSim examples since these are up-to-date.
2. OpenSim 3.0 uses Simbody 3.0, this implies changes to the make files used to build plugins and/or main programs. Please update references to older versions or use CMake files provided with the latest distribution.
3. OpenSim::Property has been redefined and reimplemented.  It is now unnecessary to declare properties of different types (e.g. PropertyBool, PropertyDbl, PropertyStr, etc.) and the new Property class is templatized to enable you to contain any defined type, T. Convenience macros are also provided so that properties can be declared in the header and all the "wiring" performed automatically, which include get/set_<property_name>() methods.  Old properties are still supported via Property_Deprecated, but will eventually be replaced and removed. Please convert your code to use the new property system. See Property.h for more details on usage and upgrading.
4. The ModelComponent interface was refined and additional Doxygen documentation provided. In particular, the defining ModelComponent methods were renamed for clarity:  setup() to connectToModel(); createSystem() to addToSystem(); initStatesFromDefaults() to initStateFromProperties(); and setDefaultsFromState() to setPropertiesFromState() to better reflect the purpose of these creation methods. Methods for adding modeling option, state and cache variables have been refined. Please refer to the ModelComponent Doxygen documentation for more details and the most recent interface.
5. The base Muscle class has been re-engineered.  Muscle provides access (get) methods for all values of interests describing a unipennate muscle composed of a muscle fiber and tendon in series. The underlying Muscle class makes no assumptions about the implementation (e.g. activation and contraction dynamics and rigid vs. compliant tendon) and instead provides three high-level virtual methods that concrete models must implement: calcMuscleLengthInfo(), calcFiberVelocityInfo(), calcMuscleDynamicsInfo() which populate data structures accessed by the access methods.
6. New muscle models built on the new Muscle interface include Millard2012EquilibriumMuscle and Millard2012AccelerationMuscle model which feature guaranteed smooth, differentiable and modifiable muscle curves that specify: active fiber force-length and force-velocity relationships, the passive fiber force-length curve, the tendon force-strain curve. In addition there is a new Thelen2003Muscle model that conforms to the publication to which it is associated (DG Thelen, Journal of biomechanical engineering, 2003). Both the Millard2012EquilibriumMuscle and Thelen2003Muscle are equilibrium models- that is the force in the fiber and tendon are equivalent in the direction of the tendon, and the solution of the initial equilibrium state has been improved. The Millard2012AccelerationMuscle introduces a fiber velocity state but has the advantage that the force-velocity relationship is not inverted to determine the fiber velocity and therefore does not suffer from singularities that the inversion creates due to small active fiber forces.
7. A new Probe component type has been added to the ModelComponent hierarchy with several Probes provided. A Probe is a ModelComponent which serves to calculate and output values of interest, such as system kinetic and potential energy, the power generated and/or dissipated by a force, etc. A custom probe allows a user to output just the  values of interest for a given simulation or battery of simulations. Probes also allow some mathematical operations to be performed on the probed value such as differentiating, integrating or taking the max value.  Probes will replace most Analyses in the near future. The advantages of a Probe is that it is much easier to write and customize than an Analysis, its values can be accessed at run-time so that high-level decisions can be made during a simulation, which can be useful for detecting important events and writing more sophisticated controllers.
8. There have been significant changes to the Doxygen documentation for the Model and ModelComponent classes (Joint, Constraint, Force, Actuator, Muscle, Controller, ...) as well as refinements to their interfaces. We strongly encourage developers to use the latest Doxygen documentation (### LINK ###) to guide their development.
9. All examples have been updated to the latest interfaces and best practices and serve as good starting points for you to expand.