# Documentation

## Calculate Motion Using Matrices

The model `sf_pool` is an example of using matrices in a C chart to simulate the opening shot on a pool table.

### How the Model Works

The model consists of the following blocks.

Model ComponentDescription
Init chartInitializes the position and velocity of the cue ball.
Pool chartCalculates the two-dimensional dynamics of each ball on the pool table.
Plot blockAnimates the motion of each ball during the opening shot.
Vel scopeDisplays the velocity of each ball during the opening shot.
ClockProvides the instantaneous simulation time to the Plot block.

### Storage of Two-Dimensional Data in Matrices

To simulate the opening shot, the Pool chart stores two-dimensional data in matrices.

To store values for...The Pool chart uses...
The instantaneous position of each ballThe 15-by-2 matrix `p`
The instantaneous velocity of each ballThe 15-by-2 matrix `v`
Friction and interaction forces acting on each ballThe 15-by-2 matrix `v_dot`
Boolean data on whether any two balls are in contactThe 15-by-15 matrix `ball_interaction`

### Calculation of Two-Dimensional Dynamics of Each Ball

The Pool chart calculates the motion of each ball on the pool table using MATLAB® functions that perform matrix calculations.

MATLAB FunctionDescription
`frictionForce`Calculates the friction force acting on each ball.
`getBallInteraction`Returns a matrix of Boolean data on whether any two balls are in contact.
`hasBallInteractionChanged`Returns 1 if ball interactions have changed and 0 otherwise.
`initBalls`Initializes the position and velocity of every ball on the pool table.
`interactionForce`Calculates the interaction force acting on each ball.
`isAnyBallGoingToStop`Returns 1 if any ball has stopped moving and 0 otherwise.
`isAnyBallNewlyPocketed`Returns 1 if any ball has been newly pocketed and 0 otherwise.
`isAnyBallOutOfBounds`Returns true if any ball is out of bounds and false otherwise.
`nearHole`Returns true if a ball is near a pocket on the pool table and false otherwise.
`pocketNewBalls`Sets the velocity of a ball to 0 if it has been pocketed.
`resetBallsPosAndVel`Resets the position and velocity of any ball that is out of bounds.
`updateStopFlags`Keeps track of which balls have stopped moving.

### Run the Model

To run the model, follow these steps:

1. Type `sf_pool` at the MATLAB command prompt.

2. Start simulation.

3. Click anywhere in the animated pool table to specify the initial position of the cue ball.

4. Click a different spot to specify the initial velocity of the cue ball.

5. Watch the balls move across the pool table.