SPEC.en

	Ruby/NArray  ver 0.5.9p8 (2010-01-16)	by Masahiro TANAKA


Class method:
    NArray.new(typecode, size, ...)	create new NArray. initialize with 0.

    NArray.byte(size,...)		1 byte unsigned integer
    NArray.sint(size,...)		2 byte signed integer
    NArray.int(size,...)		4 byte signed integer
    NArray.sfloat(size,...)		single precision float
    NArray.float(size,...)		double precision float
    NArray.scomplex(size,...)		single precision complex
    NArray.complex(size,...)		double precision complex
    NArray.object(size,...)		Ruby object
				all above method initialize with 0 or nil.

    NArray.to_na(array)			convert to NArray
    NArray.to_na(string,type[,size,...])
    NArray[...]
      NArray[1,5,10.0]  #=>  NArray.float(3):[1.0, 5.0, 10.0]
      NArray[1..10]     #=>  NArray.int(10):[1,2,3,4,5,6,7,8,9,10]


Class constant:
    CLASS_DIMENSION	# of dimension treated as data.
			0 for NArray, 1 for NVector, 2 for NMatrix.

NArray information
    self.dim		Return the dimension = the number of indices
    self.rank		same as dim
    self.shape		Return the array of sizes of each index
    self.total		Return the number of total elements

Slicing Array
 - Index components:	Integer, Range, Array, true.
 - Index order:		FORTRAN type.
    a[ 1, 2, -1 ]	element slicing.
			  If negative, counts backward from the end.
			  Element-dimensions are contracted.
    a[ 0..3, 4..1 ]	extract in the range.
			  If the former of the range is bigger,
			   return elements in reversed order.
    a[ [1,3,2,4] ]	an array with the elements of the indices.
			  If `a' has multi-dimension but, in [],
			   single index is specified,
			   `a' is treated as a single dimension array.
    a[ 1, 2..3, [1,3,2,4], true ]   compound index.
				    This returns 3-dim array.
    a[]			same as a.dup.
    a[ 0, true ]	sams as a[0,0..-1]. `true' means all.
    a[ false, 0 ]	same as a[true,true,0], if a is a 3-d array,
			`false' means ellipsis dimension.
    a[ mask ]		masking. "mask" is a byte NArray with its
			length equal to that of "a". According to the
			value of each element of mask, the corresponding
			element in "a" is eliminated (when 0) or
			retained (when not 0).
			Example: 
				a=NArray.float(2,2).indgen!
				p a[ a.lt 3 ]
				--> [ 0.0, 1.0, 2.0 ]
				(Here, a.lt 3 gives a byte NArray)
				(This is also done by a[ (a.lt 3).where ])

 - A 2-or-more-dim array object with only one argument in `[ ]',
   is treated as a flat 1-d array.
   e.g.: a[3] is same as a[0,1] if a is 3x3 array.

 - self.slice(...)	Same as self[...] but keeps the rank of
			original array by not elimiting dimensions 
			whose length became equal to 1 (which self[] 
			does). This is not the case with the
			1-dimensional indexing and masking (same as []).

Replacing Elements -- Same rule as slicing

    a[ 1, 2, 3 ] = 1
    a[ 0..3, 1..4, 2..5 ] = 2
    a[ [1,3,2,4], true ] = 3
    a[] = 4			Same as a.fill!(4)
  
    a[0..2]  = b[1..5]		--> Error! due to different num of elements.
    a[1,2]   = b[0..2,1..3]	Storing elements from index [1,2]
				( a[1,2]=b[0,1],a[2,2]=b[1,1],... )
    a[0..2,0..3]  = b[0..2,1]	Storing repetitively
				( a[0,0]=b[0,1],..,a[0,3]=b[0,1] )

Filling values
    self.indgen!([start[,step]]) Generate index;
				 Set values from 'start' with 'step' increment
    self.fill!(value)		 Fill elements with 'value'
    self.random!(max)		 Set random values between 0<=x<max
				 using MT19337
    self.randomn		 Set Normally distributed random values
				 with mean=0, dispersion=1 (Box-Muller)
    NArray.srand([seed])	 Set random seed.
				 A time-depend seed is choosed if omitted.

Operation: performed element by element
    a = NArray.float(3,3).indgen
    b = NArray.float(3,3).fill(10)
    c = a*b	# --> NArray.float(3,3)

    a = NArray.float(3,1).indgen
    b = NArray.float(1,3).fill(10)
    c = a*b	# --> NArray.float(3,3) -- size=1 dimension is extensible.

Arithmetic operator
    -self
    self + other
    self - other
    self * other
    self / other
    self % other
    self ** other
    self.abs

    self.add! other
    self.sbt! other
    self.mul! other
    self.div! other
    self.mod! other

Bitwise operator (only for integers)
    ~self
    self & other
    self | other
    self ^ other

Comparison
  -- element-wise comparison, results in BYTE-type NArray;
     Note that not true nor false is returned.
    self.eq other  ( == operator was obsolete after ver 0.5.4 )
    self.ne other
    self.gt other
    self >  other
    self.ge other
    self >= other
    self.lt other
    self <  other 
    self.le other
    self <= other 

    self.and other  element-wise condition.
    self.or  other
    self.xor other
    self.not other

    self.all?	  true if all the elements are true.
    self.any?	  true if any element is true.
    self.none?	  true if none of the element is true.
    self.where	  Return NArray of indices where elements are true.
    self.where2	  Return Array including two NArrays of indices,
		  where elements are true and false, respectively.

	e.g.: idx_t,idx_f = (a>12).where2

Statistics
    self.sum(dim,..)     Summation
    self.mean(dim,..)    Mean
    self.stddev(dim,..)  Standard deviation
    self.rms(dim,..)     Root mean square
    self.rmsdev(dim,..)  Root mean square deviation
    self.min(dim,..)     Minimum
    self.max(dim,..)     Maximum
	note: * If dimensions are specified, statistics are performed
	      	on those dimensions and the rest dimensions are kept.
	      * Range can be used.
	      * If dimension is not specified, statistics are performed
	        for all the elements.
    self.median(dim)	 Median in 0..dim (All dimensions if omitted)

Sort
    self.sort(dim)	  Sort in 0..dim (All dimensions if omitted)
    self.sort_index(dim)  Return index of Sort result.
			     self[self.sort_index] equals to self.sort.

Transpose
    self.transpose( dim0, dim1, .. )
	Transpose array.
	The dim0-th dimension goes to the 0-th dimension of new array.
	Negative number counts backward.
	transpose(-1,1..-2,0) is replacement between the first and the last.

Changing Shapes of indices
    self.reshape!(size,...)
    self.shape=(size,...)
    self.newdim=(dim)	    Insert new dimension with size=1

Reference to another NArray
    self.refer			create NArray obj referring to another NArray
    self.reshape(size,...)	same as self.refer.reshape!
    self.newdim(dim,...)	same as self.refer.newdim!

Type conversion
    self.floor      Return integer NArray whose elements processed 'floor'
    self.ceil
    self.round
    self.to_f	    Convert NArray type to float
    self.to_i       Convert NArray type to integer
    self.to_a	    Convert NArray type to Ruby-object
    self.to_s	    Convert NArray data to String as a binary data.
    self.to_string  Convert NArray type to Ruby-object
		    containing Strings as printed elements

Iteration
    self.each {|i| ...}
    self.collect {|i| ...}
    self.collect! {|i| ...}

Byte swap
    self.swap_byte	swap byte order
    self.hton		convert to network byte order
    self.ntoh		
    self.htov		convert to VAX byte order
    self.vtoh		

Boolean / mask related
    self.count_false	count # of elements whose value == 0 (only for
			byte type)
    self.count_true	count # of elements whose value != 0 (only for
			byte type)
    self.mask( mask )	same as self[ mask ], but exclusively for masking.
			Unlike [], a int or sint mask is accepted.

Complex compound number
    self.real
    self.imag
    self.conj
    self.conj!
    self.angle		atan2(self.imag, self.real)
    self.imag= other	set imaginary part
    self.im		multiply by imaginary unit

NMath module
    sqrt(x)
    exp(x)
    log(x)
    log10(x)
    log2(x)
    atan2(x,y)
    sin,cos,tan
    sinh,cosh,tanh
    asin,acos,atan
    asinh,acosh,atanh
    csc,sec,cot
    csch,sech,coth
    acsc,asec,acot
    acsch,asech,acoth
    covariance	(no idea why NMath::covariance doesn't work)


FFTW module
 (separate module)
    fftw(x,[1|-1])
    convol(a,b)		convolution with FFTW


NMatrix

  Subclass of NArray.  First 2 dimensions are used as Matrix.
  Residual dimensions are treated as Multi-dimensional array.
  The order of Matrix dimensions is opposite from
  the notation of mathematics:  a_ij => a[j,i]

  Methods:
    +,-	 enable if other is NMatrix.
    *	 Matrix product if other is NMatrix or NVector.
	 Scalar product if other is Numeric or NArray.
	 ex: NMatrix[[1,2],[3,4]] * [1,10]
	       == NMatrix[ [[1,2],[3,4]], [[10,20],[30,40]] ]
    /	 Scalar division if other is Numeric or NArray.
	 Solve Linear Equation with LU factorization
	  if other is square NMatrix.  a/b == b.lu.solve(a)

    transpose		transpose Matrix dimensions if argument omitted.
    diagonal(val)
    diagonal!(val)	set val to diagonal elements. (set 1 if omitted)
    unit		set 1 to diagonal elements.
    inverse		Inverse matrix.
    lu			compute LU factorization.
			return NMatrixLU class object.

NVector

  Subclass of NArray.  First 1 dimension is used as Vector.
  Residual dimensions are treated as Multi-dimensional array.

  Methods:
    +,-	 enable if other is NVector.
    *	 Matrix product if other is NMatrix.
	 Inner product if other is NVector.
	 Scalar product if other is Numeric or NArray.
    /	 Scalar division if other is Numeric or NArray.
	 Solve Linear Equation with LU factorization
	   if other is square NMatrix.  v/m == m.lu.solve(v)


NMatrixLU

  Created by NMatrix#lu method.
  Including LU (NMatrix) and pivot (NVector).

  Methods:
    solve(other)	Solve with the result of LU factorization.
			other should be NMatrix or NVector instance.