%% Modeling the Opening Shot in Pool
% This example shows how to model the opening shot of pool using continuous time semantics of Stateflow(R). There are 15 balls arranged
% in a triangular grid near one end of the table and the cue ball is
% released towards them from the other end of the table. This example
% is meant as an exercise in explaining how the continuous time features
% of Stateflow can be used to very simply express systems which have a
% large number of discontinuous events which rapidly (and unpredictably)
% change the evolution of the system.

% Copyright 2007-2013 The MathWorks, Inc.

%% Physics
% We make several simplifying assumptions in simulating the system. Perhaps
% the most important simplification is that we completely ignore
% the "spin" of the balls. In other words, the over-all state of the
% system is described completely by the positions and velocities of the
% individual balls.
% 
% *Friction Model*
% 
% We use a simplified friction model where we assume that a ball which is
% moving is acted upon by a friction force of constant magnitude which acts
% opposite to the direction of motion. In other words:
%
% $$\dot{\mathbf{x}} = \mathbf{v}$$
% 
% $$\dot{\mathbf{v}} = -\mu g \hat{\mathbf{v}}$$
% 
% where
% 
% $$\mathbf{x} = \mbox{vector position of the ball}$$
% 
% $$\mathbf{v} = \mbox{vector velocity of the ball}$$
% 
% $$g = \mbox{acceleration due to gravity}$$
% 
% $$\mu = \mbox{coefficient of friction}$$
% 
% $$\hat{\mathbf{v}} = \mbox{unit vector in the direction of the velocity of
% the ball.}$$
% 
% Note however that the friction force acts only as long as the ball is
% actually moving, not when it is stationary. Thus we should more accurately
% be saying:
% 
% $$\dot{\mathbf{v}} =
% \left\{
% \begin{array}{cc}
% -\mu g \hat{\mathbf{v}} & \mbox{when $\|v\| > 0$}\\ 
% 0 & \mbox{otherwise}
% \end{array}
% \right.
% $$
% 
% This implies that the friction dynamics of the pool balls have an
% inherent modal description which we need to account for when we model the
% system.
% 
% *Collision Dynamics*
% 
% Collision between balls is modeled using a simple restoring force model.
% In other words, we model the balls as being very slightly springy. When
% the balls are in contact, the reaction force between them is given by:
% 
% $$\mathbf{F}_1 = k_p(2R-\Delta \mathbf{p})\hat{\Delta \mathbf{p}} - k_v\Delta \mathbf{v}$$
% 
% $$\mathbf{F}_2 = -\mathbf{F}_1$$
% 
% where 
% 
% $$F_1 = \mbox{force on the first ball involved in the collision}$$
% 
% $$F_2 = \mbox{force on the second ball involved in the collision}$$
% 
% $$\Delta \mathbf{p} = \mathbf{p}_1 - \mathbf{p}_2 = \mbox{relative separation of the centers of the
% two balls}.$$
% 
% $$R = \mbox{radius of each ball}$$
% 
% $$\Delta \mathbf{v} = \mathbf{v}_1 - \mathbf{v}_2 = \mbox{relative velocity of the two balls}$$
% 
% Note once again that any two balls have a restoring force acting between
% them only so long as
% 
% $$\|\Delta \mathbf{p}\| < 2R$$
% 
% otherwise the restoring force is zero. Note also that since the balls are
% free to move in two dimensions, we need to account for |N^2/2| potential 
% collisions.
%
%% Stateflow(R) Model
% 
% The model consists of two Stateflow charts and one MATLAB Function block.
% The chart |Init| is responsible for the initial setup of the pool balls
% on the table and interactively letting the user choose the initial
% position and velocity of the cue ball. Note that this chart is a very
% thin wrapper around a MATLAB(R) function |sf_pool_plotter.m| which does
% the actual work of plotting.
%
% The middle chart |Pool| is the chart which actually contains the
% description of the pool ball dynamics. We will explore this chart in
% greater detail later.
%
% The final MATLAB(TM) Function block |Plot| is responsible for animating the
% balls during the simulation. Once again this is a very thin wrapper
% around |sf_pool_plotter.m|

clear
close all
bdclose all

open_system('sf_pool');
r = sfroot;
m = r.find('-isa', 'Stateflow.Machine', 'Name', 'sf_pool');
c = m.find('-isa', 'Stateflow.Chart', 'Name', 'Pool');

% first close the chart.
c.Visible = 0;

%% 
% *Chart: Pool*
% This chart is responsible for the majority of the work during the
% simulation. 

c.Visible = 1;

%% 
% In order to represent the dynamics of the pool table, we use
% the following variables
% 
% *Continuous Time Variables*
%
% * |p| An |Nx2| matrix whose |i^th| row represents the position of the
% |i^th| ball.
% * |v| An |Nx2| matrix whose |i^th| row represents the velocity of the
% |i^th| ball.
%
% *Discrete Time Variables*
%
% * |ball_interaction| An |NxN| boolean matrix which represents the
% interactions between the balls. If |ball_interaction(i,j)| is true, it
% means that the |i^th| ball and the |j^th| ball are presently in contact.
% Note that due to the symmetric nature of the system, we only use the
% upper triangular portion of this matrix.
% * |stopped| An |Nx1| boolean vector which represents whether a ball is presently
% moving or whether it is stopped.
% * |last_vel| An |Nx2| vector which represents the velocity of the balls.
% We update this vector after each incident which could change the velocity
% of a ball. |last_vel| and |stopped| are both used in the function
% |frictionForce| which models the friction between the balls and the
% table.
%
% *Friction Force Model*

f = c.find('Name', 'frictionForce');
disp(f.Script);

%% Simulation Result
% Upon simulation, a very bare-bones GUI of a pool table is shown with 15
% balls arranged in a triangular grid at one end of the table. The user is
% asked to place the cue ball and choose its initial velocity. The system
% then simulates the evolution of the pool balls while animating their
% motion.

global sf_pool_init_pos sf_pool_init_vel
sf_pool_init_pos = [-25, -5];
sf_pool_init_vel = [80, 10]*2.5;

set_param('sf_pool', 'StopTime', '10');
c.Visible = 0;
% g1093681 workaround
%evalc('sim(''sf_pool'')');

%% 

bdclose all;
clear
close all;
