# File structures/CellComplex.rb, line 121
  def iterate dim
    @cells[dim].each_key do |cell| yield cell end
  end
  
  ## add
  ##
  ## Add a cell to the complex. lower is an array with the cells
  ## of dimension one lower that are incident to the cell. It is
  ## required that these lower dimensional cells be in the complex.
  ## Also the new cell can not be in the boundary of any other 
  ## existing cell.
  ## This function returns the newly created cell.
  
  def add (lower,data = nil, inverted = false)
    begin
      ## make sure that the lower cells are in the complex
      lower.each do |lowCell|
        if (!lowCell.is_a?(Cell) || !member?(lowCell))
          raise "object #{lowCell} is not a cell" 
        end
      end
      
      ## make sure that the lower cells all have the same dimension
      if (lower != [])
        ld = lower[0].dim
        exit if ld >= @dim
        lower.each do |lowCell|
          if (lowCell.dim != ld) 
            raise "boundary cells have different dimension" 
          end
        end
      end
      
      ## create the new cell and add it to the complex
      cellDim = (lower.empty? ? 0 : lower[0].dim+1 )
      cell = @cellCreate.call(self, cellDim, data)
      @lower[cell] = lower
      @upper[cell] = Array.new
      @cells[cellDim][cell] = true
      @inverted[cell] = inverted
      
      ## update the incidence and switch structures
      ## for the lower dimensional faces
      
      lower.each do |lowCell|
        @lower[lowCell].each do |lowestCell|
          matches = @upper[lowestCell] & lower
          if (matches.length > 2)
            raise "diamond property violation"
          end
          if (matches.length == 2)
            @switchH[[lowestCell,matches[1],cell]] = matches[0]
            @switchH[[lowestCell,matches[0],cell]] = matches[1]
          end
        end
        @upper[lowCell].push(cell)
      end
      
      ## if the new cell is an edge add the switch triples
      ## that start with the -1 dimensional cell
      
      if (cellDim == 1)
        if lower.length > 2
          raise "diamond property violation" 
        end
        if (lower.length == 2) 
          @switchH[[nil,lower[0],cell]] = lower[1]
          @switchH[[nil,lower[1],cell]] = lower[0]
        else
          ## self-loop
          @switchH[[nil,lower[0],cell]] = lower[0]
        end
      end
      
      ## if the new cell is a d-dimensional cell
      ## add the switch tripes that end with the d+1
      ## cell
      
      if (cell.dim == @dim)
        lower.each do |lowCell|
          upper = @upper[lowCell]
          if upper.length > 2
            raise "diamond property violation"
          end
          if (upper.length == 2)
            @switchH[[lowCell,upper[0],nil]] = upper[1]
            @switchH[[lowCell,upper[1],nil]] = upper[0]
          end
        end
      end
    return cell

    rescue
      raise $!
      #print "CellComplex.add: ",$!
      #exit
    end

  end

  ## switch
  ##
  ## return the switch_k of the tuple if it is define and nil otherwise

  def switch(k, tuple)
    raise "nil Tuple given to switch" if tuple == nil
    raise "non-Tuple given to switch" if !tuple.is_a? CellTuple
    raise "bad call to switch" if k<0 || k>tuple.dim
    raise "bad tuple given to switch" if !tuple.dim.is_a? Integer
    triple = [tuple[k-1], tuple[k], tuple[k+1]]
    otherCell = @switchH[triple]
    if (otherCell == nil) 
      return nil
    else
      newTupArr = Array.new
      for j in 0..tuple.dim
        newTupArr[j] = tuple[j]
      end
      newTupArr[k] = otherCell
      return CellTuple.new(newTupArr)
    end
  end

  ## delete
  ##
  ## delete the given cell from the complex.  All other cells
  ## that contain it in their boundary are also deleted.

  def delete cell

    ## recursively delete cells which contain the cell in their
    ## boundary
    upper = @upper[cell].clone
    upper.each do |upCell| delete upCell end
   
    ## update the incidence and switch structures for the
    ## lower dimensional cells
    @lower[cell].each do |lowCell|

      ## delete triples for lowCell and it's switch if applicable
      @lower[lowCell].each do |lowestCell|
        otherCell = @switchH[[lowestCell,lowCell,cell]]
        if (otherCell != nil)
          @switchH[[lowestCell,lowCell,cell]] = nil
          @switchH[[lowestCell,otherCell,cell]] = nil
        end
      end

      ## if cell is of highest dimension then delete triples
      ## that have the d+1 cell
      if (cell.dim == @dim) 
        otherCell = @switchH[[lowCell, cell, nil]]
        if otherCell != nil
          @switchH[[lowCell, cell, nil]] = nil
          @switchH[[lowCell, otherCell, nil]] = nil
        end
      end

      @upper[lowCell].delete(cell)
    end
    
    @cells[cell.dim].delete(cell)
    @lower[cell] = nil
    @upper[cell] = nil
    @inverted[cell] = nil
  end

  ## member?
  ##
  ## return true iff the given cell is in the complex

  def member? cell
    return @cells[cell.dim].member?(cell)
  end

  ## down
  ##
  ## retrive the cells lower than the parameter cell
  ## which are offset dimensions lower (offset >= 0)

  def down(cell,offset=1)
    return [cell] if (offset == 0)
    lower = Array.new
    @lower[cell].each do |lowCell|
        lower |= self.down(lowCell,offset-1)
    end
    return lower
  end

  ## up
  ##
  ## retrive the cells higher than the parameter cell
  ## which are offset dimensions higher (offset >= 0)

  def up(cell,offset=1)
    return [cell] if (offset == 0)
    upper = Array.new
    return [] if @upper[cell] == nil
    @upper[cell].each do |upCell|
        upper |= self.up(upCell,offset-1)
    end
    return upper
  end

  ## rotate
  ##
  ## get a circular ordering of the k-1 and k cells between the
  ## (k-2) and (k+1) cells of the given tuple in the incidence
  ## lattice.
  ## More precisely it returns a sequnence c_0, ..., c_m
  ## of cells such that if i is even then c_i is of dimension k - 1
  ## and if i is odd then c_i is of dimension k.  In addition 
  ## c_i and c_i+1 are adjacent.  If the (k-2) cell is in the interior
  ## of the complex then c_m and c_i are adajacent.  Otherwise
  ## c_m is on the boundary.

  def rotate(k, tuple)
    index = k - 1
    nextCell = cell = tuple[index]
    nextTuple = tuple
    begin 
      yield nextCell
      oldTuple = nextTuple
      nextTuple = switch(index, nextTuple)
      index = (index == k) ? k - 1 : k
      nextCell = nextTuple[index] if nextTuple != nil
    end until (nextCell == cell || nextTuple == nil) 
    if (nextTuple == nil)
      yield oldTuple[k-1]
    end
  end
    
  ## getTuple
  ##
  ## returns a tuple containing cell. 
  ## The algorithm to determine the tuple is as follows.  Let
  ## k be the dimension of c.  Let t be the tuple that has c
  ## in its k^th entry and such that the i^th entry is the first
  ## cell that was given when i+1^th cell was created. If
  ## the cell of dimension d in the t is not inverted then t
  ## is returned otherwise switch(0,t) is returned.

  def getTuple(cell)
    begin
      tuple = []
      
      # get cells at and bellow cell
      k = cell.dim
      if dim < 0 || dim > @dim
        raise "cell has dimesion #{dim} and complex has dimension #{@dim}"
      end
      c = cell
      while k >= 0 do
        tuple[k] = c
        lowC = @lower[c]
        c = (lowC == nil) ? nil : lowC[0]
        if c == nil && k > 0
          raise "non-vertex cell has no boundary elements #{k} #{cell}"
        end
        k -= 1
      end
      
      ctuple = CellTuple.new(tuple)
      ctuple = switch(0, ctuple) if @inverted[ctuple[@dim]]
    return ctuple
  
    rescue => exc
      print "CellComplex.getTuple: ", $!
      puts exc.backtrace
      exit
    end
  end

  ## returns a (v, e, f) tuple for v 
  ## this tuple may not be oriented
  def getFullTuple v
    e = up(v)[0]
    t = up(e)[0]
    CellTuple.new(v, e, t)
  end

  ## returns an oriented tuple containing ed
  ## if tri is given the tuple will also contain tri
  def getOTuple(ed,tri = nil)
    puts "Warning" if ed==nil
    tri = up(ed)[0] if (tri==nil)
    if tri==nil 
      puts "Cell Complex is not properly constructed. This should not be."
      puts ed
      puts up(ed)
      puts down(ed)
    end
    tup = getTuple(tri)
    while (tup[1] != ed)
      tup = switch(1,switch(0,tup))
    end
    return tup
  end

  ## returns an oriented tuple containing v
  ## if tri is given the tuple will also contain tri
  def getOTupleV(v,tri = nil)
    t1 = up(up(v)[0])[0]
    tup = getTuple(t1)
    while (tup[0] != v)
      tup = switch(0,switch(1,tup))
    end
    return tup
  end

  ## show
  ##
  ## debug function that prints the data associated with every
  ## cell and its incident cells

  def show
    @cells.each do |dCells|
      dCells.each_key do |cell|
        puts "Cell: #{cell} #{cell.data}"
        puts "Upper:"
        @upper[cell].each do |upCell|
          puts "#{upCell}"
        end
        puts "Lower:"
        @lower[cell].each do |lowCell|
          puts "#{lowCell}"
        end
      end
    end
  end

  ## import
  ##
  ## this function adds the elements of otherComplex to this one
  ## nothing is cloned, so it is assumed that otherComplex will be discarded

  def import otherComplex
    @switchH.update(otherComplex.switchH)
    @cells.each_index {|i| @cells[i].update(otherComplex.cells[i]) }
    @lower.update(otherComplex.lower)
    @upper.update(otherComplex.upper)
    @inverted.update(otherComplex.inverted)
  end

  attr_reader :dim
  attr_reader :cells,:switchH,:lower,:upper,:inverted
  # protected :cells,:switchH,:lower,:upper,:inverted
  ## I leave open access on these for debugging and reporting purposes
  ## Exact access levels can be determined at a later date
end