123456789_123456789_123456789_123456789_123456789_

Class: Vector

Relationships & Source Files
Namespace Children
Exceptions:
ZeroVectorError
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, ::Matrix::ConversionHelper
Instance Chain:
self, ::Matrix::CoercionHelper, Enumerable, ::ExceptionForMatrix
Inherits: Object
Defined in: lib/matrix.rb

Overview

The Vector class represents a mathematical vector, which is useful in its own right, and also constitutes a row or column of a ::Matrix.

Method Catalogue

To create a Vector:

To access elements:

  • #[](i)

To set elements:

  • #[]=(i, v)

To enumerate the elements:

  • #each2(v)

  • #collect2(v)

Properties of vectors:

Vector arithmetic:

  • #*(x) “is matrix or number”

  • #+(v)

  • #-(v)

  • #/(v)

  • #+@

  • #-@

Vector functions:

Conversion to other data types:

String representations:

Class Method Summary

::Matrix::ConversionHelper - Extended

convert_to_array

Converts the obj to an Array.

Instance Attribute Summary

Instance Method Summary

::Matrix::CoercionHelper - Included

#apply_through_coercion

Applies the operator oper with argument obj through coercion of obj

Constructor Details

.new(array) ⇒ Vector

new is private; use Vector[] or .elements to create.

[ GitHub ] 

  


# File 'lib/matrix.rb', line 1937



def initialize(array)
  # No checking is done at this point.
  @elements = array
end


  







Class Method Details



  

    .[](*array)  
  



  

    

Creates a Vector from a list of elements.



Vector[7, 4, ...]


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1898



def Vector.[](*array)
  new convert_to_array(array, false)
end


  








  

    .basis(size:, index:)  
  



  

    

Returns a standard basis n-vector, where k is the index.



Vector.basis(size:, index:) # => Vector[0, 1, 0]


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1915



def Vector.basis(size:, index:)
  raise ArgumentError, "invalid size (#{size} for 1..)" if size < 1
  raise ArgumentError, "invalid index (#{index} for 0...#{size})" unless 0 <= index && index < size
  array = Array.new(size, 0)
  array[index] = 1
  new convert_to_array(array, false)
end


  








  

    .elements(array, copy = true)  
  



  

    

Creates a vector from an Array.  The optional second argument specifies whether the array itself or a copy is used internally.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1906



def Vector.elements(array, copy = true)
  new convert_to_array(array, copy)
end


  








  

    .independent?(*vs)  ⇒ Boolean 
  



  

    

Returns true iff all of vectors are linearly independent.



Vector.independent?(Vector[1,0], Vector[0,1])
  #=> true

Vector.independent?(Vector[1,2], Vector[2,4])
  #=> false


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2062



def Vector.independent?(*vs)
  vs.each do |v|
    raise TypeError, "expected Vector, got #{v.class}" unless v.is_a?(Vector)
    raise ErrDimensionMismatch unless v.size == vs.first.size
  end
  return false if vs.count > vs.first.size
  Matrix[*vs].rank.eql?(vs.count)
end


  








  

    .zero(size)  
  



  

    

Return a zero vector.



Vector.zero(3) => Vector[0, 0, 0]


  





  
Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1928



def Vector.zero(size)
  raise ArgumentError, "invalid size (#{size} for 0..)" if size < 0
  array = Array.new(size, 0)
  new convert_to_array(array, false)
end


  







Instance Attribute Details



  

    #elements   (readonly, protected)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1891



attr_reader :elements


  








  

    #zero?  ⇒ Boolean  (readonly)
  



  

    

Returns true iff all elements are zero.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2087



def zero?
  all?(&:zero?)
end


  







Instance Method Details



  

    #*(x)  
  



  

    

Multiplies the vector by x, where x is a number or a matrix.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2136



def *(x)
  case x
  when Numeric
    els = @elements.collect{|e| e * x}
    self.class.elements(els, false)
  when Matrix
    Matrix.column_vector(self) * x
  when Vector
    raise ErrOperationNotDefined, ["*", self.class, x.class]
  else
    apply_through_coercion(x, __method__)
  end
end


  








  

    #+(v)  
  



  

    

Vector addition.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2153



def +(v)
  case v
  when Vector
    raise ErrDimensionMismatch if size != v.size
    els = collect2(v) {|v1, v2|
      v1 + v2
    }
    self.class.elements(els, false)
  when Matrix
    Matrix.column_vector(self) + v
  else
    apply_through_coercion(v, __method__)
  end
end


  








  

    #+@  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2201



def +@
  self
end


  








  

    #-(v)  
  



  

    

Vector subtraction.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2171



def -(v)
  case v
  when Vector
    raise ErrDimensionMismatch if size != v.size
    els = collect2(v) {|v1, v2|
      v1 - v2
    }
    self.class.elements(els, false)
  when Matrix
    Matrix.column_vector(self) - v
  else
    apply_through_coercion(v, __method__)
  end
end


  








  

    #-@  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2205



def -@
  collect {|e| -e }
end


  








  

    #/(x)  
  



  

    

Vector division.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2189



def /(x)
  case x
  when Numeric
    els = @elements.collect{|e| e / x}
    self.class.elements(els, false)
  when Matrix, Vector
    raise ErrOperationNotDefined, ["/", self.class, x.class]
  else
    apply_through_coercion(x, __method__)
  end
end


  








  

    #==(other)  
  



  

    

Returns true iff the two vectors have the same elements in the same order.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2112



def ==(other)
  return false unless Vector === other
  @elements == other.elements
end


  








  

    

      #[](range)  
      #[](integer)  
    

    Also known as: #element, #component
  



  

    

Returns element or elements of the vector.


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1951



def [](i)
  @elements[i]
end


  








  

    

      #[]=(range, new_vector)  
      #[]=(range, row_matrix)  
      #[]=(range, new_element)  
      #[]=(integer, new_element)  
    

    Also known as: #set_element, #set_component
  



  

    

Set element or elements of vector.


  





  
Raises:


    
  
  • 
    (FrozenError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1966



def []=(i, v)
  raise FrozenError, "can't modify frozen Vector" if frozen?
  if i.is_a?(Range)
    range = Matrix::CoercionHelper.check_range(i, size, :vector)
    set_range(range, v)
  else
    index = Matrix::CoercionHelper.check_int(i, size, :index)
    set_value(index, v)
  end
end


  








  

    #angle_with(v)  
  



  

    

Returns an angle with another vector. Result is within the [0..Math::PI].



Vector[1,0].angle_with(Vector[0,1])
# => Math::PI / 2


  





  
Raises:


    
  
  • 
    (TypeError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2321



def angle_with(v)
  raise TypeError, "Expected a Vector, got a #{v.class}" unless v.is_a?(Vector)
  raise ErrDimensionMismatch if size != v.size
  prod = magnitude * v.magnitude
  raise ZeroVectorError, "Can't get angle of zero vector" if prod == 0
  dot = inner_product(v)
  if dot.abs >= prod
    dot.positive? ? 0 : Math::PI
  else
    Math.acos(dot / prod)
  end
end


  








  

    #coerce(other)  
  



  

    

The coerce method provides support for Ruby type coercion. This coercion mechanism is used by Ruby to handle mixed-type numeric operations: it is intended to find a compatible common type between the two operands of the operator. See also Numeric#coerce.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2381



def coerce(other)
  case other
  when Numeric
    return Matrix::Scalar.new(other), self
  else
    raise TypeError, "#{self.class} can't be coerced into #{other.class}"
  end
end


  








  

    #collect(&block)  
    Also known as: #map
  



  

    

Like Array#collect.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2265



def collect(&block) # :yield: e
  return to_enum(:collect) unless block_given?
  els = @elements.collect(&block)
  self.class.elements(els, false)
end


  








  

    #collect!(&block)  
    Also known as: #map!
  



  

    

Like Array#collect!


  





  
Raises:


    
  
  • 
    (FrozenError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2275



def collect!(&block)
  return to_enum(:collect!) unless block_given?
  raise FrozenError, "can't modify frozen Vector" if frozen?
  @elements.collect!(&block)
  self
end


  








  

    #collect2(v)  
  



  

    

Collects (as in Enumerable#collect) over the elements of this vector and v in conjunction.


  





  
Raises:


    
  
  • 
    (TypeError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2040



def collect2(v) # :yield: e1, e2
  raise TypeError, "Integer is not like Vector" if v.kind_of?(Integer)
  raise ErrDimensionMismatch if size != v.size
  return to_enum(:collect2, v) unless block_given?
  Array.new(size) do |i|
    yield @elements[i], v[i]
  end
end


  








  

    #component(i)  
  



  

    

Alias for #[].


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1955



alias component []


  








  

    #covector  
  



  

    

Creates a single-row matrix from this vector.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2341



def covector
  Matrix.row_vector(self)
end


  








  

    #cross(*vs)  
  



  

    

Alias for #cross_product.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2260



alias_method :cross, :cross_product


  








  

    #cross_product(*vs)  
    Also known as: #cross
  



  

    

Returns the cross product of this vector with the others.



Vector[1, 0, 0].cross_product Vector[0, 1, 0]   => Vector[0, 0, 1]



It is generalized to other dimensions to return a vector perpendicular to the arguments.



Vector[1, 2].cross_product # => Vector[-2, 1]
Vector[1, 0, 0, 0].cross_product(
   Vector[0, 1, 0, 0],
   Vector[0, 0, 1, 0]
)  #=> Vector[0, 0, 0, 1]


  





  
Raises:


    
  
  • 
    (ErrOperationNotDefined)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2240



def cross_product(*vs)
  raise ErrOperationNotDefined, "cross product is not defined on vectors of dimension #{size}" unless size >= 2
  raise ArgumentError, "wrong number of arguments (#{vs.size} for #{size - 2})" unless vs.size == size - 2
  vs.each do |v|
    raise TypeError, "expected Vector, got #{v.class}" unless v.is_a? Vector
    raise ErrDimensionMismatch unless v.size == size
  end
  case size
  when 2
    Vector[-@elements[1], @elements[0]]
  when 3
    v = vs[0]
    Vector[ v[2]*@elements[1] - v[1]*@elements[2],
      v[0]*@elements[2] - v[2]*@elements[0],
      v[1]*@elements[0] - v[0]*@elements[1] ]
  else
    rows = self, *vs, Array.new(size) {|i| Vector.basis(size: size, index: i) }
    Matrix.rows(rows).laplace_expansion(row: size - 1)
  end
end


  








  

    #dot(v)  
  



  

    

Alias for #inner_product.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2226



alias_method :dot, :inner_product


  








  

    #each(&block)  
  



  

    

Iterate over the elements of this vector


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2017



def each(&block)
  return to_enum(:each) unless block_given?
  @elements.each(&block)
  self
end


  








  

    #each2(v)  
  



  

    

Iterate over the elements of this vector and v in conjunction.


  





  
Raises:


    
  
  • 
    (TypeError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2026



def each2(v) # :yield: e1, e2
  raise TypeError, "Integer is not like Vector" if v.kind_of?(Integer)
  raise ErrDimensionMismatch if size != v.size
  return to_enum(:each2, v) unless block_given?
  size.times do |i|
    yield @elements[i], v[i]
  end
  self
end


  








  

    #element(i)  
  



  

    

Alias for #[].


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1954



alias element []


  








  

    #elements_to_f  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2359



def elements_to_f
  warn "Vector#elements_to_f is deprecated", uplevel: 1
  map(&:to_f)
end


  








  

    #elements_to_i  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2364



def elements_to_i
  warn "Vector#elements_to_i is deprecated", uplevel: 1
  map(&:to_i)
end


  








  

    #elements_to_r  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2369



def elements_to_r
  warn "Vector#elements_to_r is deprecated", uplevel: 1
  map(&:to_r)
end


  








  

    #eql?(other)  ⇒ Boolean 
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2117



def eql?(other)
  return false unless Vector === other
  @elements.eql? other.elements
end


  








  

    #freeze  
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2091



def freeze
  @elements.freeze
  super
end


  








  

    #hash  
  



  

    

Returns a hash-code for the vector.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2125



def hash
  @elements.hash
end


  








  

    #independent?(*vs)  ⇒ Boolean 
  



  

    

Returns true iff all of vectors are linearly independent.



Vector[1,0].independent?(Vector[0,1])
  #=> true

Vector[1,2].independent?(Vector[2,4])
  #=> false


  





  


  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2080



def independent?(*vs)
  self.class.independent?(self, *vs)
end


  








  

    #initialize_copy(v)   (private)
  



  

    

Called for dup & clone.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2099



private def initialize_copy(v)
  super
  @elements = @elements.dup unless frozen?
end


  








  

    #inner_product(v)  
    Also known as: #dot
  



  

    

Returns the inner product of this vector with the other.



Vector[4,7].inner_product Vector[10,1]  => 47


  





  
Raises:


    
  
  • 
    (ErrDimensionMismatch)
  
    • 





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2217



def inner_product(v)
  raise ErrDimensionMismatch if size != v.size

  p = 0
  each2(v) {|v1, v2|
    p += v1 * v2.conj
  }
  p
end


  








  

    #inspect  
  



  

    

Overrides Object#inspect


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2404



def inspect
  "Vector" + @elements.inspect
end


  








  

    #magnitude  
    Also known as: #r, #norm
  



  

    

Returns the modulus (Pythagorean distance) of the vector.



Vector[5,8,2].r => 9.643650761


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2287



def magnitude
  Math.sqrt(@elements.inject(0) {|v, e| v + e.abs2})
end


  








  

    #map(&block)  
  



  

    

Alias for #collect.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2270



alias_method :map, :collect


  








  

    #map!(&block)  
  



  

    

Alias for #collect!.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2281



alias map! collect!


  








  

    #map2(v, &block)  
  



  

    

Like #collect2, but returns a Vector instead of an Array.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2296



def map2(v, &block) # :yield: e1, e2
  return to_enum(:map2, v) unless block_given?
  els = collect2(v, &block)
  self.class.elements(els, false)
end


  








  

    #norm  
  



  

    

Alias for #magnitude.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2291



alias_method :norm, :magnitude


  








  

    #normalize  
  



  

    

Returns a new vector with the same direction but with norm 1.



v = Vector[5,8,2].normalize
# => Vector[0.5184758473652127, 0.8295613557843402, 0.20739033894608505]
v.norm => 1.0


  





  
Raises:





  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2310



def normalize
  n = magnitude
  raise ZeroVectorError, "Zero vectors can not be normalized" if n == 0
  self / n
end


  








  

    #r  
  



  

    

Alias for #magnitude.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2290



alias_method :r, :magnitude


  








  

    #round(ndigits = 0)  
  



  

    

Returns a vector with entries rounded to the given precision (see Float#round)


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1999



def round(ndigits=0)
  map{|e| e.round(ndigits)}
end


  








  

    #set_component(i, v)   (private)
  



  

    

Alias for #[]=.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1977



alias set_component []=


  








  

    #set_element(i, v)   (private)
  



  

    

Alias for #[]=.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1976



alias set_element []=


  








  

    #set_range(range, value)   (private)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1984



private def set_range(range, value)
  if value.is_a?(Vector)
    raise ArgumentError, "vector to be set has wrong size" unless range.size == value.size
    @elements[range] = value.elements
  elsif value.is_a?(Matrix)
    raise ErrDimensionMismatch unless value.row_count == 1
    @elements[range] = value.row(0).elements
  else
    @elements[range] = Array.new(range.size, value)
  end
end


  








  

    #set_value(index, value)   (private)
  

  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 1980



private def set_value(index, value)
  @elements[index] = value
end


  








  

    #size  
  



  

    

Returns the number of elements in the vector.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2006



def size
  @elements.size
end


  








  

    #to_a  
  



  

    

Returns the elements of the vector in an array.


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2348



def to_a
  @elements.dup
end


  








  

    #to_matrix  
  



  

    

Return a single-column matrix from this vector


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2355



def to_matrix
  Matrix.column_vector(self)
end


  








  

    #to_s  
  



  

    

Overrides Object#to_s


  



  [ GitHub ]


  

  


# File 'lib/matrix.rb', line 2397



def to_s
  "Vector[" + @elements.join(", ") + "]"
end