Simscape Multibody Contact Forces Library - Examples Project
Copyright 2014-2020 The MathWorks, Inc.

This library contains contact force models for use with Simscape Multibody.
They can be used for intermittent contact (parts bouncing off each other)
and persistent contact (parts resting on each other).

** Please note that the Spatial Contact Force block has been added in R2019b.
** You should see if this block meets your needs before using this library.  

You are welcome to use these models in your own projects. If you need to 
include the library in your own example, I recommend you use just the 
project Contact_Forces_Core.prj in subfolder Core.  You can either use it
directly, or include it as a Referenced Project just as is done 
in this project.


General approach for using this library:
   1. Identify the parts in your system that will hit each other during simulation

   2. Figure out which edges or surfaces will touch.  
      The contact models provided allow you to model contact between combinations
      of connected circular arcs with straight lines (2D) 
      and spheres with flat planes or cylinders (3D).

   3. Add reference frames for the lines and arcs that will touch.

   4. Add the correct contact force model between the two frames.

See the examples to understand how they are used.

Recommendations:
   1. Start with stiffness of 1e4 and damping of 1e2 and adjust from there.
   2. Use solver ode15s, Relative Tolerance = 1e-4, Absolute Tolerance = 1e-5
       and set the maximum step size to 1e-2.
   3. If you get unexpected behavior (parts flying through one another, 
       system gaining energy) your tolerances are not small enough.
       Reduce tolerances by a factor of 10 and max step size by a factor of 10
       until you get expected behavior.  Reducing stiffness and increasing damping
       can also help.


#########  Release History  #########
v 5.0(R2019b)   Mar 2020       Updated v5.0 for R2020a
     (R2020a)

v 5.0(R2019b)   Sep 2019       Move to MATLAB Projects

v 4.1(R2019a)   Mar 2019       Updated v4.1 for R2019a
                               Minor changes to accommodate physical signal units


v 4.1(R2018b)   Nov 2018       Added two examples
     (R2018a)   
     (R2017b)   1. New example Caster_4_Whl.slx
     (R2017a)      Models a four-wheel cart with casters on front wheels 
     (R2016b)
     (R2016a)   2. New example sm_build_spheres_in_sphere
     (R2015b)      MATLAB code to automatically assemble a model that has 
     (R2015a)      a user-defined number of spheres inside a sphere with
                   contact forces between all inner spheres and between 
                   inner spheres and outer sphere.

v 4.1(R2018b)   Sep 2018       Updated v4.1 for R2018b
                               All v4p1 have updated Extr_Data_Cam_Roller_Curve.m

     (R2018a)   Mar 2018       Tread example, walking robot example 
     (R2017b)
     (R2017a)   1. Adjusted Sphere to Belt Force (in 3D, Composite Forces)
     (R2016b)      Changed orientation of reference frame for the two
     (R2016a)      Sphere to Tube Enabled Forces. Z-axis flipped 180 deg
     (R2015b)      so that vx and wz inputs have the same sign. 
     (R2015a)   
                2. Adjusted sm_tread_drive example.slx
                   Uses adjusted Sphere to Belt Force, test sequence altered
                   to show turning and show both treads striking bump in 
                   forward and reverse. 

                3. New example sm_robot_6legs_4bar.slx 
                   Models 6-legged robot. Legs on each side are a pair of
                   connected four-bar linkages. Shows how to model robot
                   walking on uneven surface.   

                4. Added CFL_contact_setModel.m
                   Function to select force law in all contact forces in model.

                5. Additions to support Parts_Lib.slx 
                   Extrusion file Extr_Data_TriangleRounded_Holes.m and 
                   various images for masking parts.

v 4.0(R2018a)	Mar 2018       Updated for R2018a
     (R2017b)
     (R2017a)   1. Added Sphere to Tube Enabled Force
     (R2016b)      Sphere to Tube force that can be enabled/disabled
     (R2016a)      and can be used to model the ends of a driven conveyor belt.
     (R2015b)
     (R2015a)   2. Added Sphere to Belt Force (in 3D, Composite Forces)
                   Used to models spheres on a moving conveyor belt.  Can
                   also be used to model vehicles that ride on treads
                   like a bulldozer.  See sm_tread_drive  

                3. New examples sm_tread_drive, Frict3D_Balls_on_Driven_Tube 
                   These examples use Sphere to Tube Enabled Force and
                   Sphere to Belt Force. 

                4. Added sm_ball_bearing_testrig example
                   Models a ball bearing with variants that use
                   Common Gear Constraint (ideal) and contact forces
                   (permits vibration).

                5. Added extrusion script Extr_Data_Block_NotchCircle.m 
                   Used to calculate cross-sectional profile for inner and
                   outer race in Ball Bearing Testrig example


v 3.9 (R2017b)	Jan 2018       Added Cam Roller Constraint
                1. Added Cam Roller Constraint.  
                   Uses Point-on-Curve Constraint to model circular
                   roller on a cam with arbitrary profile.

                2. Added Extr_Data_Cam_Roller_Curve.m to calculate
                   path of Point-on-Curve Constraint.

                3. Added Cam_Follower_Constraint example.


v 3.8 (R2017b)	Sept 2017      Updated for R2017b


v 3.7 (R2017a)	July 2017      Sphere to Cone Force, many fixes
      (R2016b)		           Library saved in versions R2015b through R2017a
      (R2016a)
      (R2015b)
                1. Added Sphere to Cone Force.  Contact force is active on
		        inside and outside of cone.  Also added extrusion script
		        Extr_Data_Frustrum_Conical.m and example 
                Coll3D_08_Ball_in_Spinning_Cone.slx

                2. Sphere to Tube Force - fixed relative velocity calculation in
                Contact_Forces_Lib/3D/Sphere to Tube Force/Forces/Ff/vTan
                Previous releases delivered incorrect results if the cylinder
                could spin.  Added new example Coll3D_07_Balls_and_Sliding_Tube.slx

                3. Extr_Data_Box.m: functional change, parameters are full width
                and height instead of half width and half height.  Affected
                parameters within a few examples, such as Spinning Boxes

                4. Extr_Data_Cam.m: Changed to Extr_Data_Cam_Circles.m, which has
                two additional parameters (radii of holes).  Affected example
                Cam Follower and the UI for parameterizing the cam.

                5. Many 2D contact forces have been modified so that they
		        no longer refer to the World frame.  This permits them to be
                used in any plane, not just the x-y plane.

                6. Circle to Ring Force: calculations adjusted to use consistent
                distance to contact point for circle and ring.  May result in
                minor changes to simulation results.

                7. Mask commands adjusted - eliminated imread(), use option
                "Opaque with ports" (R16a and above), and other settings.


v 3.6 (R2017a)	Mar  2017       Updated for R2017a
      (R2016b)	
                1. New example: Ball on Wheel with Controller (2D Friction Examples)
                   Models a ball balanced on a wheel.
                2. Removed MATLAB variables from blocks in Contact_Forces_Lib.slx
                   Some library elements contained MATLAB variables in the dialog box
                   parameters on the Dimensions and Visual tab.  These were replaced
                   with hardcoded default values to avoid warnings about undefined variables.
                3. Additional parameters were added to the Sphere block in Parts_Lib.slx 
                   to enable the marks to be shown or hidden per axis. 
                4. New script CFL_SaveLibsOnly.m that copies only the critical files 
        		   of this repository to a new folder so you can include them in
                   your own project.

v 3.5 (R2016b)	Jan  2017	3D Composite Forces, Sphere-to-Plane Enabled
                1. Added Face-to-Plane in 3D/Composite Forces.  This is useful for
                   two flat square surfaces that may contact each other at arbitrary 
                   angles.  It assumes no edges will intersect (one square is 
                   significantly larger than the other
                2. Added Face-to-Belt-Faces forces in 3D/Composite Forces.  This is
                   useful for modeling 3D boxes on conveyor belts where only one
                   face of the box will encounter the belt.  It accepts the 
                   speed of the belt as an input signal (vx and/or vy)
                3. Added Sphere-to-Plane Enabled Force.  This is used within the
                   composite force´Face-to-Belt-Faces composite force
                4. Added example Gripper with Conveyor Belts (3D Applications). 
                   Uses the new forces to model a box that is transferred by a 
                   gripper between two conveyor belts.  One belt brings the box
                   to the gripper, the other moves it away.

		Additional parameters were added to the Cylinder block 
                in Parts_Lib.slx to enable arbitrary colors for the cylinders.

v 3.4 (R2016b)	Sep  2016	Updated for R2016b
		1. Fixed outputs for Circle-to-Ring, Sphere-to-Tube, Sphere-to-Plane
		   Force output signals for these signals now go to zero when 
		   circle/sphere leaves active range for force, where active range is 
		   an arc of the ring/tube or length of the plane. Previously, the
		   measured value for the force would be held if the force was active
		   as the circle/sphere left the active range for the force.

		2. Copy for Merge block added in Sphere-to-Plane block
		   This block is necessary in some configurations.


v 3.3 (R2016a)	Apr  2016	Added optional visualization for contact surfaces
		The surfaces associated with the contact forces can now be visualized.	
		This helps you confirm you have oriented the surfaces properly and
		defined them to be an appropriate length or active range of angles.

		All contact forces now have an additional tab labeled "Visual".  On
		this tab you can enable a visualization of the surface, which is done
		using a Solid with density set to 0.  For the 2D contact forces you 
		will need to define the length of the surface along the z-axis of
		the contact force and it is used for visualization purposes only. 
		You can show/hide all contact surfaces in the model using the
		new function CFL_visual_setOnOff.m in the Scripts_Data directory.

		Additionally in this release, a number of plotting scripts have been
		added to the examples, and in many cases the variables used by
		the example were moved to the Model Workspace.


v 3.2 (R2016a)	Mar  2016	Disabled zero crossings in some Abs blocks
      (R2015b)  Affects Circle-to-Finite Line, Sphere to Finite Plane
		The zero-crossings in Abs blocks used to check the displacement
                of the circle/sphere reference frame from the line/plane
		reference frame along the line/surface (y / xy) direction is
		not necessary.  When the line/plane can move along the (y / xy)
 		direction, it can lead to excessive zero crossings, slowing down
		the simulation.


v 3.1 (R2016a)	Mar  2016	Renamed Simscape Multibody Contact Forces Library
		1. Geneva drive model imported from CAD is now parameterized
			

v 3.0 (R2015b)  Sept 2015	Updated to R2015b


v 3.0 (R2015a)  July 2015	3D models added
                1. Sphere-to-Sphere, Sphere-in-Sphere, Sphere-to-Plane, 
                   Sphere-to-Tube added, all with optional friction model
                2. Added 3D collision and friction examples
		3. Added Two Wheel Robot example (3D Applications)

                (2D Models)
                4. Modified 2D enabled forces
		   ** Change from v2.0 -- may require you to update your models ** 
                   Modified Circle to Circle Force Enabled, 
                   Circle to Finite Line Force Enabled to use a bus as the
                   input signal instead of signal input.  Bus permits user to
                   optionally define enabled/disabled, and to set velocity
                   perpendicular to normal force (vy).  Primary use is for ideal 
                   models of conveyor belts.
                5. Added 2D/Composite forces (Box to Box force, Box to Belt force)
                6. Added Belts_01_Two_Belts.slx (simple conveyor belt example)
                
                Documentation, Dialog boxes
                7. Updates to all dialog boxes (added images, fixed prompts and description)
                8. Documentation revised                


v 2.0 (R2014a)  September 2014	Friction model added
                1. Added optional friction model (Stick-Slip Continuous)
		   to Circle to Circle, Circle to Finite Line, Circle to Ring
                2. Added all Friction_* examples 
                3. Added Spinning Boxes example 
                   Shows box-to-box contact force
                4. Fixed callback commands, all contact force blocks
		   Set variant in Initialization commands instead of mask callbacks
                5. Fixed Circle to Finite Line, Circle to Finite Line Enabled
                   Force on line was applied in wrong reference frame

v 1.0 (R2014a)  August 2014     Initial release.
		Circle-Circle (Enabled), Circle-Line (Enabled), Circle-Ring
		7 Simple, Cam Follower, Geneva Drive. Mini Golf compatible