docs: def directInitialMatrix(self):   
          """
          We generate an initial sparse matrix with all the transition rates (or probabilities).
          We later transform this matrix into a rate or probability matrix depending on the preferred method of obtaining pi.
          """
          
          #First initialize state codes and the mapping with states. 
          self.setStateCodes()  
  
          #For each state, calculate the indices of reached states and rates using the transition function.
          results  = imap(self.transitionStates, self.mapping.values())
          
           #Simpler alternative that uses less memory. 
           #Would be competitive if the conversion from dok to csr is faster.  
  #        D = dok_matrix((self.size,self.size),dtype=float)
  #        for index,(col,rate) in enumerate(results):
  #            D.update({(index,c): r for c,r in zip(col,rate)})
  #        return D.tocsr()
  
          #preallocate memory for the rows, cols and rates of the sparse matrix      
          rows = np.empty(self.size,dtype=int)
          cols = np.empty(self.size,dtype=int)
          rates = np.empty(self.size,dtype=float)
              
          #now fill the arrays with the results, increasing their size if current memory is too small.
          right = 0
          for index,(col,rate) in enumerate(results): #more robust alternative: in izip(self.mapping.keys(),results)
              left = right
              right += len(col)
              if right >= len(cols):
                  new_capacity = int(round(right * 1.5))  #increase the allocated memory if the vectors turn out to be too small.
                  cols.resize(new_capacity)
                  rates.resize(new_capacity)
                  rows.resize(new_capacity)
              rows[left:right] = index #since states are sorted, the index indeed corresponds to the state.
              cols[left:right] = col
              rates[left:right] = rate   
             
          #Place all data in a coo_matrix and convert to a csr_matrix for quick computations.
          return coo_matrix((rates[:right],(rows[:right],cols[:right])),shape=(self.size,self.size)).tocsr()