function a = snakes_matrix ( )

%*****************************************************************************80
%
%% snakes_matrix() sets up the Snakes and Ladders matrix.
%
%  Discussion:
%
%    Snakes and Ladders, also known as Chutes and Ladders, is a game
%    played on a 10x10 board of 100 squares.  A player can be said to
%    start at square 0, that is, off the board.  The player repeatedly
%    rolls a die, and advances between 1 and 6 steps accordingly.
%    The game is won when the player reaches square 100.  In some versions,
%    the player must reach 100 by exact die count, forfeiting the move
%    if 100 is exceeded; in others, reaching or exceeding 100 counts as
%    a win.
%
%    Play is complicated by the existence of snakes and ladders.  On
%    landing on a square that begins a snake or ladder, the player is
%    immediately tranported to another square, which will be lower for
%    a snake, or higher for a ladder.
%
%    Typically, several players play, alternating turns.
%
%    Given a vector V(0:100) which is initially all zero except for the
%    first entry, the matrix-vector product A'*V represents the probabilities
%    that a player starting on square 0 will be on any given square after one
%    roll.  Correspondingly, (A')^2*V considers two moves, and so on.  Thus,
%    repeatedly multiplying by A' reveals the probability distribution associated
%    with the likelihood of occupying any particular square at a given turn
%    in the game.  
%
%    Because MATLAB does not allow zero array indices, we have to include
%    an "O" variable.
%
%    There is a single eigenvalue of value 1, whose corresponding eigenvector
%    is all zero except for a final entry of 1, representing a player who
%    has reached square 100.  All other eigenvalues have norm less than 1,
%    corresponding to the fact that there are no other long term steady
%    states or cycles in the game.
%
%  Licensing:
%
%    This code is distributed under the MIT license.
%
%  Modified:
%
%    12 September 2014
%
%  Author:
%
%    John Burkardt
%
%  Reference:
%
%    Nick Berry,
%    Mathematical Analysis of Chutes and Ladders,
%    https://www.datagenetics.com/blog/november12011/index.html
%
%  Output:
%
%    integer A(101,101), the matrix.
%
  O = 1;

  a = sparse ( [], [], [], 101, 101, 6 * 101 );

  [ snake, ladder ] = snakes_ladder_setup ( );
%
%  A(I,J) represents the probablity that a dice roll will take you from
%  square I to square J.
%
%  Starting in square I...
%
  for i = 0 + O : 100 + O
%
%  the die roll D will be between 1 and 6,
%
    for d = 1 : 6
%
%  so theoretically, our new location J will be I + D,
%
      j = i + d;
%
%  but if J is greater than 100, move us back to J,
%
      if ( 100 + O < j )
        j = 100 + O;
      end
%
%  and if J lands us on a snake, go to the tail of the snake,
%
      j = snake ( j );
% 
%  and if J lands us on a ladder, climb to the top of the ladder.
%
      j = ladder ( j );
%
%  Now record a 1/6 probability of moving from I to J.
%
      a(i,j) = a(i,j) + 1.0 / 6.0;

    end

  end

  return
end

