rubylabs 0.9.0 → 0.9.1

data/lib/spherelab.rb

@@ -1,20 +1,22 @@
+module RubyLabs
 
 =begin rdoc
   
 == SphereLab
 
-Definition of Vector and Body objects used for n-body simulations.
+The SphereLab module has definitions of classes and methods used in the projects for Chapter 11
+of <em>Explorations in Computing</em>.  The module includes a simple "turtle graphics" module
+for experiments with moving objects, definitions of 
+Vector and Body objects used for n-body simulations, and methods for updating a system of
+bodies based on the gravitational forces acting between pairs of bodies.
 
 =end
 
-module RubyLabs
-	
+  
 module SphereLab
   
-=begin rdoc
-  These class variables maintain the state of the display and other miscellaneous
-  global values.
-=end
+  # These class variables maintain the state of the display and other miscellaneous
+  # global values.
   
   @@sphereDirectory = File.join(File.dirname(__FILE__), '..', 'data', 'spheres')
 
@@ -45,72 +47,77 @@ module SphereLab
   MelonView = Struct.new(:bodies, :scale, :ground, :startloc, :options)
 
 =begin rdoc
-  The constant G is the universal gravitational constant, assuming mass is
+  The universal gravitational constant, assuming mass is
   in units of kilograms, distances are in meters, and time is in seconds.
 =end
 
   G = 6.67E-11
 
 =begin rdoc
-  A Vector is a 3-tuple of (x,y,z) coordinates.  Operators defined for
-  vector objects (where v is a vector and a is a scalar):
-     v == v
-     v + v
-     v - v
-     v * a
-     v.add(v)     (equivalent of v += v)
-     v.sub(v)     (equivalent of v -= v)
-     v.scale(a)   (equivalent of v *= a)
-     v.norm
+
+== Vector
+
+A Vector is a 3-tuple of (x,y,z) coordinates.  Operators defined for
+vector objects (where +v+ is a vector and +a+ is a scalar) are:
+   v == v
+   v + v
+   v - v
+   v * a
+   v.add(v)     (equivalent to v += v)
+   v.sub(v)     (equivalent to v -= v)
+   v.scale(a)   (equivalent to v *= a)
+   v.norm
+Arithmetic methods are invoked for a vector <tt>v1</tt> when Ruby evaluates an expression of the
+form <tt>v1</tt> <op> <tt>v2</tt> where <op> is +, -, or *.  They create a a new vector containing the 
+result of the operation.  + and - do element-wise addition or and subtraction, *
+is a vector-scalar multiplication.
+
+The add, sub, and scale methods modify a vector, e.g. a call to <tt>v1.add(v2)</tt> will update
+<tt>v1</tt> by adding the corresponding components in <tt>v2</tt>.
 =end
 
   class Vector
     attr_accessor :x, :y, :z
   
-=begin rdoc
-  Make a new vector with the specified x, y, and z components.
-=end
+    # Make a new vector with the specified +x+, +y+, and +z+ components.
   
     def initialize(*args)
       @x, @y, @z = args
     end
+    
+    # Create a string that displays the +x+, +y+, and +z+ coordinates of the vector.
   
     def inspect
       pos = [@x,@y,@z].map { |x| sprintf "%.5g", x }
       return "(" + pos.join(",") + ")"
     end
   
-=begin rdoc
-  v1 == v2 if the three components are the same
-=end
+    # Compare this vector with another vector +v+.  Two vectors are the same if
+    # all three components are the same.
 
     def ==(v)
       return (@x == v.x) && (@y == v.y) && (@z == v.z)
     end
 
-=begin rdoc
-  Arithmetic methods are invoked for a vector v1 when Ruby evaluates an expression of the
-  form v1 <op> v2 where <op> is +, -, or *.  They create a a new vector containing the 
-  result of the operation.  + and - do element-wise addition or and subtraction, *
-  is a vector-scalar multiplication.
-=end
-  
+    # Create a new vector that is the sum of this vector and vector +v+.
+    
     def +(v)
       Vector.new(@x + v.x, @y + v.y, @z + v.z)
     end
+    
+    # Create a new vector that is the difference between this vector and vector +v+.
   
     def -(v)
       Vector.new(@x - v.x, @y - v.y, @z - v.z)
     end
+    
+    # Create a new vector that is the product of this vector and scalar +a+.
 
     def *(a)
       Vector.new(@x * a, @y * a, @z * a)
     end
 
-=begin rdoc
-  v1.add(v2) adds the components of v2 to v1 -- would be v1 += v2 if Ruby
-  allowed us to overload +=
-=end
+    # Add the components of vector +v+ to this vector.
 
     def add(v)
       @x += v.x
@@ -119,11 +126,8 @@ module SphereLab
       self
     end
   
-=begin rdoc
-  v1.sub(v2) subtracts the components of v2 from v1 -- would be v1 -= v2 if Ruby
-  allowed us to overload -=
-=end
-
+    # Subtract the components of vector +v+ from this vector.
+    
     def sub(v)
       @x -= v.x
       @y -= v.y
@@ -131,9 +135,7 @@ module SphereLab
       self
     end
     
-=begin rdoc
-  v.scale(a) -- multiply each element in v by scalar a
-=end
+    # Multiply each component of this vector by scalar +a+.
 
     def scale(a)
       @x *= a
@@ -141,31 +143,31 @@ module SphereLab
       @z *= a
     end
 
-=begin rdoc
-  The magnitude of a vector is the Euclidean norm: sqrt(x**2 + y**2 + z**2)
-=end
+    # Compute the magnitude of this vector, which is the Euclidean norm
+    # defined by sqrt(x**2 + y**2 + z**2)
 
     def norm
       sqrt(@x*@x + @y*@y + @z*@z)
     end
     
-=begin rdoc
-  Compute the angle between this vector and v -- used when drawing 2D vectors, so
-  the z dimension is ignored
-=end
+    # Compute the angle between this vector and vector +v+.  This method is
+    # only used when drawing 2D vectors, so the z dimension is ignored.
 
     def angle(v)
       acos((@x * v.x + @y * v.y) / (norm * v.norm))
     end
     
-=begin rdoc
-  Accessor functions for the coordinates as a vector of three floats
-=end
-
+    # Return a vector of three Floats corresponding to the +x+, +y+, and +z+
+    # components of this vector.
+    
     def coords
       [@x, @y, @z]
     end
     
+    # Set the three components of this vector to the values in the array +a+,
+    # which should be an array of three Floats (it can have more values, but
+    # only the first three are used).
+    
     def coords=(a)
       @x = a[0]
       @y = a[1]
@@ -176,30 +178,34 @@ module SphereLab
 
 
 =begin rdoc
-  A Body object represents the state of a celestial body.  A body has mass (a scalar),
-  position (a vector), and velocity (a vector).  A third vector, named force, is used
-  when calculating forces acting on a body.  The size and color attributes are used by
-  the visualization methods.
+
+== Body
+
+A Body object represents the state of a celestial body.  A body has mass (a scalar),
+position (a vector), and velocity (a vector).  A third vector, named force, is used
+when calculating forces acting on a body.  The size and color attributes are used by
+the visualization methods.
+
 =end
 
   class Body
     attr_accessor :mass, :position, :velocity, :force
     attr_accessor :name, :size, :color, :prevx, :prevy, :graphic
+    
+    # Create a new Body object.  If the argument list is empty, the attributes (mass,
+    # position, etc) are all set to 0.  Otherwise the arguments should be +mass+ (a
+    # Float), +position+ (a vector), and +velocity+ (another vector).  A fourth
+    # argument is an optional name for the body.
+    #
+    # Example:
+    #    >> b = Body.new
+    #    => : 0 kg (0,0,0) (0,0,0)
+    #    >> b = Body.new(1e6, Vector.new(0,0,0), Vector.new(0,0,0), "test")
+    #    => test: 1e+06 kg (0,0,0) (0,0,0)
   
     def initialize(*args)
-      if args[1].class == Vector
+      if args.length > 0
         @mass, @position, @velocity, @name = args
-      # elsif args[0] == :random
-      #   @mass = rand(10000) * 1e6
-      #   @position = Vector.new(rand(300)-150, rand(300)-150, 0)
-      #   @velocity = Vector.new(rand(20)-10, rand(10)-5, 0)
-      #   @name = "b" + self.object_id.to_s
-      # elsif args[0].is_a?(Numeric) && args[1].is_a?(Numeric)
-      #   @mass = args[0]
-      #   @position = Vector.new(args[1], 0.0, 0.0)
-      #   @velocity = Vector.new(0.0, 0.0, 0.0)
-      #   @name = args[2]
-      #   @linear = true
       else
         @mass = 0.0
         @position = Vector.new(0.0, 0.0, 0.0)
@@ -209,6 +215,8 @@ module SphereLab
       @force = Vector.new(0.0, 0.0, 0.0)
     end
     
+    # Make a copy of this body.
+    
     def clone
       copy = super
       if graphic
@@ -219,15 +227,16 @@ module SphereLab
       end
       return copy
     end
+    
+    # Create a string that summarizes the state of this body.
   
     def inspect
       name = @name ? @name : ""
       return sprintf "%s: %.3g kg %s %s", name, @mass, @position.inspect, @velocity.inspect
     end
 
-=begin rdoc
-  Reset the force vector to 0 (to get ready for a new round of interaction calculations).
-=end
+    # Reset the force vector to (0,0,0).  Called by SphereLab#step_system at the start of each
+    # new round of interaction calculations.
 
     def clear_force
       @force.x = 0.0
@@ -235,9 +244,7 @@ module SphereLab
       @force.z = 0.0
     end
   
-=begin rdoc
-  Compute force acting on this body wrt body b
-=end
+    # Compute the force exerted on this body by body +b+ and update this body's force vector.
 
     def add_force(b)
       r = @position - b.position
@@ -246,9 +253,7 @@ module SphereLab
       @force.add(r * mr)
     end
   
-=begin rdoc
-  Move this body by applying current force vector for dt seconds
-=end
+    # Update this body's position by applying the current force vector for +dt+ seconds.
 
     def move(dt)
       acc = @force * G * -1.0
@@ -256,10 +261,10 @@ module SphereLab
       @position.add( @velocity * dt )
     end
   
-=begin rdoc
-  Class method to compute the interaction between bodies b1 and b2 and update
-  their force vectors.
-=end
+    # This class method will compute the interaction between bodies <tt>b1</tt> and <tt>b2</tt> and update
+    # their force vectors.  Since the forces on the bodies are the same, but acting in the 
+    # opposite direction, the force can be calculated just once and then used to update both
+    # bodies.
 
     def Body.interaction(b1, b2)
       r = b1.position - b2.position
@@ -271,9 +276,16 @@ module SphereLab
   end # Body
   
 =begin rdoc
-  A class for rudimentary Turtle graphics.  All we need is enough functionality to
-  implement a robot that draws a circle by moving forward, then correcting its direction.
-  Attributes:  location and velocity vectors.
+
+== Turtle
+
+This class implements a rudimentary "turtle graphics" system.  A turtle is an object that
+moves around on a canvas, under direction from a user/program that tells it to advance, turn,
+etc.  A turtle also has a "pen" that can be raised or lowered.  When the pen is down, the
+turtle draws a line on the canvas as it moves.
+
+A Turtle object is used in the robot explorer experiment, where the object is to get the robot
+to move in as smooth a circle as possible about a central point.
 =end
 
   class Turtle
@@ -289,6 +301,19 @@ module SphereLab
     }
     
     @@north = Vector.new(0, 10, 0)
+    
+    # Create a new Turtle object.  The arguments (all optional) specify the turtle's starting
+    # position and orientation.  The possible options and their default values:
+    #    :x => 20
+    #    :y => 100
+    #    :heading => 0
+    #    :speed => 10
+    #    :track => :off
+    # Example:
+    #    >> t = Turtle.new
+    #    => #<SphereLab::Turtle x: 20 y: 100 heading: 360 speed: 10.00>
+    #    >> t = Turtle.new( :x => 100, :y => 100, :speed => 5 )
+    #    => #<SphereLab::Turtle x: 100 y: 100 heading: 360 speed: 5.00> 
 
     def initialize(args = nil)
       args = { } if args.nil?
@@ -296,29 +321,44 @@ module SphereLab
       options = @@turtleOptions.merge(args)
       alpha = Canvas.radians(options[:heading] + 90.0)
       @position = Vector.new(options[:x], options[:y], 0.0)
-      @velocity = Vector.new(-1.0 * options[:speed] * cos(alpha), options[:speed] * sin(alpha), 0.0)
+      if options[:speed] > 0
+        @velocity = Vector.new(-1.0 * options[:speed] * cos(alpha), options[:speed] * sin(alpha), 0.0)
+      else
+        raise "Turtle.new: speed must be greater than 0"
+      end
       @graphic = nil
       @reference = nil
       @tracking = options[:track]
     end
     
+    # Create a string that summarizes the status of this turtle object.
+    
     def inspect
       sprintf "#<SphereLab::Turtle x: %d y: %d heading: %d speed: %.2f>", @position.x, @position.y, heading, speed 
     end
     
+    # Return an array of two numbers representing the +x+ and +y+ coordinates of this object.
+    
     def location
       return [@position.x, @position.y]
     end
     
+    # Return the current heading, in compass degrees, of this turtle object.  The heading is a number between 0 and 360,
+    # where 0 is north, 90 is east, etc.
+    
     def heading
       d = Canvas.degrees( @velocity.angle(@@north) )
       return (@velocity.x < 0) ? (360 - d) : d
     end
     
+    # Return the current speed (in meters per second) of this turtle object.
+    
     def speed
       @velocity.norm
     end
     
+    # Reorient the turtle by telling it to turn clockwise by +alpha+ degrees. 
+    
     def turn(alpha)
       theta = -1.0 * Canvas.radians(alpha)
       x = @velocity.x * cos(theta) - @velocity.y * sin(theta)
@@ -326,11 +366,13 @@ module SphereLab
       @velocity.x = x
       @velocity.y = y
       if @graphic
-        Canvas.rotate(@graphic,alpha)
+        @graphic.rotate(alpha)
       end
       return alpha
     end
     
+    # Tell the turtle to move straight ahead from its current position for +dt+ seconds.
+    
     def advance(dt)
       prevx = @position.x
       prevy = @position.y
@@ -341,6 +383,10 @@ module SphereLab
       return dt
     end  
     
+    # Tell the turtle to rotate until its heading is orthogonal to a reference point.
+    # See the Lab Manual for details about setting a reference point and how the 
+    # orientation is calculated.
+    
     def orient
       if @reference.nil?
         puts "no reference point"
@@ -355,6 +401,9 @@ module SphereLab
       return alpha      
     end
     
+    # Turn tracking <tt>:on</tt> or <tt>:off</tt>.  When tracking is <tt>:on</tt> the
+    # turtle draws a line on the canvas as it moves.
+    
     def track(val)
       case val
       when :off  : @tracking = :off
@@ -368,13 +417,13 @@ module SphereLab
     
   end # class Turtle
   
-=begin rdoc
-  Set up an experiment with a robot/turtle.  Initialize the canvas, make the turtle,
-  assign it a graphic.  These methods are all defined with respect to a canvas, and
-  they will print an error message if the experiment has not been set up with a call
-  to init_robot (which sets @@drawing).
-=end
-
+  # Initialize the RubyLabs Canvas for an experiment with the robot explorer.  The
+  # canvas will show a map of an area 400 x 400 meters and the robot (represented by
+  # a Turtle object) on the west edge, facing north.  The two options that can be
+  # passed specify the canvas size and a polygon that determines its shape:
+  #   :canvasSize => 400,
+  #   :polygon => [4,0,0,10,4,8,8,10],    
+  
   def view_robot(userOptions = {})
     options = @@robotOptions.merge(userOptions)
     poly = options[:polygon].clone
@@ -401,12 +450,29 @@ module SphereLab
     return true
   end
   
+  # Plant a "flag" at location +fx+, +fy+, which will serve as a reference point for
+  # calls to <tt>robot.orient</tt> to reorient the robot.  The flag will be shown as
+  # a circle on the canvas at the specified position.
+  
   def set_flag(fx, fy)
     r = 3.0
     Canvas::Circle.new( fx + r/2, fy + r/2, r, :fill => 'darkblue' )
     @reference = [ fx, fy ]          
   end
-    
+  
+  # Return a reference to the Turtle object that represents the robot explorer
+  # (created when the user calls view_robot).
+  # In experiments, users combine a call to this method with a call to a method that
+  # controls the robot.
+  #
+  # Example:
+  #   >> robot
+  #   => #<SphereLab::Turtle x: 40 y: 200 heading: 360 speed: 10.00>
+  #   >> robot.heading
+  #   => 360.0
+  #   >> robot.turn(30)
+  #   => 30
+     
   def robot
     if @@drawing.nil?
       puts "No robot; call view_robot to initialize"
@@ -415,24 +481,12 @@ module SphereLab
       return @@drawing.turtle
     end
   end
-      
-  # :begin :make_circle
-  def make_circle(nseg, time, angle)
-    view_robot
-    robot.turn( angle/2 )
-    nseg.times { robot.advance(time); robot.turn(angle) }
-    robot.turn( -angle/2 )
-    return true
-  end
-  # :end :make_circle
-
 
-=begin rdoc
-  These methods create a set of bodies with random size, location, and initial
-  velocity.
-=end
-
-  def random_vectors(r, i, n)
+  # The methods that make random bodies need to be fixed -- they need a more formal
+  # approach to define a system that "keeps together" longer.  In the meantime, turn
+  # off documentation....
+  
+  def random_vectors(r, i, n)   # :nodoc:
     theta = (2 * PI / n) * i + (PI * rand / n)
     # radius = r + (r/3)*(rand-0.5)
     radius = r + r * (rand-0.5)
@@ -444,13 +498,7 @@ module SphereLab
     return Vector.new(x, y, 0), Vector.new(vx, vy, 0)
   end
 
-  def random_velocity(v, r)
-    res = Vector.new(-r * cos)
-  end
-  
-  # todo -- put mm, mr in global options
-
-  def random_bodies(n, big)
+  def random_bodies(n, big)   # :nodoc:
     big = 1 if big.nil?
     moving = true if moving.nil?
     res = []
@@ -477,7 +525,7 @@ module SphereLab
     return res
   end
   
-  def falling_bodies(n)
+  def falling_bodies(n)   # :nodoc: 
     raise "n must be 5 or more" unless n >= 5
     a = random_bodies(n-1, n-1)
     b = Body.new(1e13, (a[0].position + a[1].position), Vector.new(0,0,0))
@@ -492,26 +540,33 @@ module SphereLab
     return a
   end
   
-=begin rdoc
-  Initialize a new n-body system, returning an array of body objects.  The
-  parameter is the name of a predefined system, the name of a file, or the
-  symbol :random.
-=end
-
-	def make_system(*args)
+  # Initialize a new n-body system, returning an array of body objects.  If the argument
+  # is a symbol it is the name of a predefined system in the SphereLab data directory, 
+  # otherwise it should be the name of a file in the local directory.
+  #
+  # Example:
+  #   >> b = make_system(:melon)
+  #   => [melon: 3 kg (0,6.371e+06,0) (0,0,0), earth: 5.97e+24 kg (0,0,0) (0,0,0)]
+  #   >> b = make_system(:solarsystem)
+  #   => [sun: 1.99e+30 kg (0,0,0) (0,0,0), ... pluto: 1.31e+22 kg (-4.5511e+12,3.1753e+11,1.2822e+12) (636,-5762.1,440.88)]
+  #--
+  # When random bodies are working again add this back in to the comment:
+  #  ... or the symbol :random, which...
+
+  def make_system(*args)
     bodies = []
-		begin
-		  raise "usage: make_system(id)" unless args.length > 0
-		  if args[0] == :random
-		    raise "usage:  make_system(:random, n, m)" unless args.length >= 2 && args[1].class == Fixnum
-		    return random_bodies(args[1], args[2])
-	    elsif args[0] == :falling
-		    raise "usage:  make_system(:falling, n)" unless args.length >= 1 && args[1].class == Fixnum
-	      return falling_bodies(args[1])
-	    end
-	    filename = args[0]
-  	  if filename.class == Symbol
-  	    filename = File.join(@@sphereDirectory, filename.to_s + ".txt")
+    begin
+      raise "usage: make_system(id)" unless args.length > 0
+      if args[0] == :random
+        raise "usage:  make_system(:random, n, m)" unless args.length >= 2 && args[1].class == Fixnum
+        return random_bodies(args[1], args[2])
+      elsif args[0] == :falling
+        raise "usage:  make_system(:falling, n)" unless args.length >= 1 && args[1].class == Fixnum
+        return falling_bodies(args[1])
+      end
+      filename = args[0]
+      if filename.class == Symbol
+        filename = File.join(@@sphereDirectory, filename.to_s + ".txt")
       end
       File.open(filename).each do |line|
         line.strip!
@@ -536,37 +591,39 @@ module SphereLab
           # end
         end       
       end
-		rescue
-			puts "error: #{$!}"
-			return nil
-		end
-		return bodies
-	end
-	
-=begin rdoc
-  Write the mass, position, and velocity for each body to a file.  Not intended to
-  be used by students, but used to save interesting data sets they can load and use.
-=end
-
-# d 4.5e16 300 -75 0 -5 2 0 6 #ff6666
-
-	
-	def save_system(b, fn)
-	  raise "file exists" if File.exists?(fn)
-	  File.open(fn, "w") do |f|
-	    b.each do |x|
-	      f.printf "%s %g %g %g %g %g %g %g %d %s\n", 
-	        x.name, x.mass, 
-	        x.position.x, x.position.y, x.position.z, 
-	        x.velocity.x, x.velocity.y, x.velocity.z, 
-	        x.size, x.color
-	    end
-	  end
-	end
-	
-=begin rdoc
-  Initialize the drawing canvas by drawing a circle for each body in list b.
-=end
+    rescue
+      puts "error: #{$!}"
+      return nil
+    end
+    return bodies
+  end
+  
+  # Write the mass, position, and velocity for each body in array +b+ to a file named +fn+.
+  # The data in the file can later be read back in by passing the file name to make_system.  
+  #--
+  # Not intended to be used by students, but to save interesting data sets they can load and use.
+  
+  def save_system(b, fn)
+    raise "file exists" if File.exists?(fn)
+    File.open(fn, "w") do |f|
+      b.each do |x|
+        f.printf "%s %g %g %g %g %g %g %g %d %s\n", 
+          x.name, x.mass, 
+          x.position.x, x.position.y, x.position.z, 
+          x.velocity.x, x.velocity.y, x.velocity.z, 
+          x.size, x.color
+      end
+    end
+  end
+  
+  # Initialize the RubyLabs Canvas to show the motion of a set of bodies in an 
+  # n-body simulation and draw a circle for each body in +blist+.
+  #
+  # Example -- make a drawing with the Sun and the inner three planets:
+  #   >> b = make_system(:solarsystem)
+  #   => [sun: 1.99e+30 kg (0,0,0) (0,0,0), ... ]
+  #   >> view_system(b[0..3])
+  #   => true
 
   def view_system(blist, userOptions = {})
     Canvas.init(700, 700, "SphereLab::N-Body")
@@ -592,10 +649,11 @@ module SphereLab
     return true  
   end
 
-=begin rdoc
-  Demonstrate adding force vectors by moving only one body
-=end
-
+  # Run one step of a simulation of an n-body system where only one body is allowed
+  # to move and all the others are fixed in place.  The first argument is a reference
+  # to the moving body, the second is any array containing references to the other
+  # bodies in the system, and the third is the time step size.
+  
   def update_one(falling, stationary, time)
     if falling.graphic.nil?
       puts "display the system with view_system"
@@ -619,31 +677,29 @@ module SphereLab
     return true
   end
 
-=begin rdoc
-  Call SphereLab::step(bodies, time) to calculate the pairwise interactions between all
-  Body objects in the array +bodies+ and then compute their new positions after +time+ seconds.
-=end
-
-# :begin :step_system
+  # Run one time step of a full n-body simulation.  Compute the pairwise interactions of all
+  # bodies in the system, update their force vectors, and then move them an amount determined
+  # by the time step size +dt+.
+  #--
+  # :begin :step_system
   def step_system(bodies, dt)
     nb = bodies.length
   
-    for i in 0..(nb-1)         # compute all pairwise interactions
+    for i in 0..(nb-1)      # compute all pairwise interactions
       for j in (i+1)..(nb-1)
         Body.interaction( bodies[i], bodies[j] )
       end
     end
   
     bodies.each do |b|
-      b.move(dt)          # apply the accumulated forces
+      b.move(dt)            # apply the accumulated forces
       b.clear_force         # reset force to 0 for next round
     end
   end
-# :end :step_system
+  # :end :step_system
     
-=begin rdoc
-  After making a canvas with view_system, call this method to move the bodies on the canvas.
-=end
+  # This method will call step_system to simulate the motion of a set of bodies for the
+  # specified amount of time +dt+ and then update their positions on the canvas.
 
   def update_system(bodies, dt)
     return false unless @@drawing
@@ -664,23 +720,19 @@ module SphereLab
     return true
   end
 
-=begin rdoc
-  Map a simulation's (x,y) coordinates to screen coordinates using origin
-  and scale factor
-=end
+  # Map a simulation's (x,y) coordinates to screen coordinates using origin
+  # and scale factor
 
-  def scale(vec, origin, sf)
+  def scale(vec, origin, sf)  # :nodoc:
     loc = vec.clone
     loc.scale(sf)
     loc.add(origin)
     return loc.x, loc.y
   end
     
-=begin rdoc
-  Make a vector that defines the location of the origin (in pixels).
-=end
+  # Make a vector that defines the location of the origin (in pixels).
 
-  def setOrigin(type)
+  def setOrigin(type)   # :nodoc:
     case type
     when :center
       Vector.new( Canvas.width/2, Canvas.height/2, 0)
@@ -689,12 +741,10 @@ module SphereLab
     end
   end
   
-=begin rdoc
-  Set the scale factor.  Use the parameter passed by the user, or find the
-  largest coordinate in a list of bodies.  Add 20% for a margin
-=end
+  # Set the scale factor.  Use the parameter passed by the user, or find the
+  # largest coordinate in a list of bodies.  Add 20% for a margin
 
-  def setScale(blist, origin, scale)
+  def setScale(blist, origin, scale)  # :nodoc:
     if scale == nil
       dmax = 0.0
       blist.each do |b|
@@ -707,10 +757,22 @@ module SphereLab
     return (sf / dmax) * 0.8
   end
   
-=begin rdoc
-  Initialize the drawing for a "2-body system" with a small object and the
-  earth.  The parameters are the list of Body objects and viewing options.
-=end
+  # Initialize the RubyLabs Canvas to show a drawing of a "2-body system" with 
+  # a small circle to represent a watermelon and a much larger partial circle for the
+  # earth.  The two Body objects representing the melon and earth should be passed
+  # in the array +blist+. Additonal optional arguments are viewing options, which have
+  # the following defaults:
+  #   :canvasSize => 400
+  #   :mxmin => 100         maximum melon x position
+  #   :mymin => 50,         maximum melon y position
+  #   :hmax => 100,         maximum melon height
+  #   :dash => 1,           size of dashes drawn as melon falls
+  #
+  # Example:
+  #   >> b = make_system(:melon)
+  #   => [melon: 3 kg (0,6.371e+06,0) (0,0,0), earth: 5.97e+24 kg (0,0,0) (0,0,0)]
+  #   >> view_melon(b)
+  #   => true
   
   def view_melon(blist, userOptions = {})
     options = @@droppingOptions.merge(userOptions)
@@ -731,11 +793,16 @@ module SphereLab
     return true
   end
   
-=begin rdoc
-  Position the melon (body 0) at a specified height.  If no drawing, save the current
-  position in prevy, but if drawing, get the earth's surface from the drawing (this allows
-  students to move the melon up or down in the middle of an experiment)
-=end
+  # Position the melon (the first body in the array +blist+) at a specified height
+  # above the earth. 
+  #
+  # Example:
+  #   >> position_melon(b, 50)
+  #   => 50
+  #-- 
+  # If no drawing, save the current position in prevy, but if drawing, get the earth's 
+  # surface from the drawing (this allows students to move the melon up or down in the 
+  # middle of an experiment)
   
   def position_melon(blist, height)
     melon = blist[0]
@@ -758,6 +825,10 @@ module SphereLab
     return height
   end
   
+  # Execute one time step of the two-body simulation involving the two objects in
+  # +blist+.  Similar to the general purpose method update_system, except the 
+  # drawing position of the earth is not updated.
+  
   def update_melon(blist, dt)
     melon = blist[0]
     mx = melon.position.x
@@ -778,6 +849,21 @@ module SphereLab
     return blist[0].height
   end
   
+  # Repeatedly call the update_melon method until the +y+ position of the melon
+  # is less than or equal to the +y+ position of the surface of the earth.  The
+  # two objects representing the melon and earth are passed in the array +blist+,
+  # and +dt+ is the size of the time step to use in calls to update_melon.
+  # The return value is the amount of simulated time it takes the melon to hit
+  # the earth; it will be the product of +dt+ and the number of time steps (number of
+  # calls to update_melon).
+  #
+  # Example -- to run an experiment that drops the melon from 50 meters, using a
+  # time step size of .01 seconds:
+  #   >> position_melon(b, 50)
+  #   => 50
+  #   >> drop_melon(b, 0.01)
+  #   => 3.19
+  #--
   # :begin :drop_melon
   def drop_melon(blist, dt)
     count = 0
@@ -790,22 +876,24 @@ module SphereLab
   end
   # :end :drop_melon
 
-  
-=begin rdoc
-  Methods used in IRB sessions.
-=end
-
-# :begin :dist
+  # Compute the distance traveled by an object moving at velocity +r+ for
+  # an amount of time +t+.
+  #--
+  # :begin :dist
   def dist(r, t)
     return r * t
   end
-# :end :dist
-
-# :begin :falling
+  # :end :dist
+  
+  # Compute the distance an object will fall when it is initially stationary
+  # and then falls for an amount of time +dt+, accelerating
+  # according to the force of the Earth's gravity.
+  #--
+  # :begin :falling
   def falling(t)
     return 0.5 * 9.8 * t**2
   end
-# :end :falling
+  # :end :falling
 
 end # SphereLab