Clarify Semantics of how Shape and Data works. (#97)

* Fixed #90

* Starting to clarify some semantic

* With the semantics clarified, the consopts need to change a bit too

* Updated the semantics to make it more clear

* Added an example to Dense.Data() to clarify the semantics.
Added tests for certain consopts that may be breaking -race

* Added mmap example for FromMemory

* Fixed ap.T and clarified shapes better in ap.go
Added an example for  T

* Fixes SelectByIndices

* Unnecessary checks for 0 removed, given that ProdInts have changed in function

Author: chewxy

ap.go

@@ -8,9 +8,12 @@ import (
 
 // An AP is an access pattern. It tells the various ndarrays how to access their data through the use of strides
 // Through the AP, there are several definitions of things, most notably there are two very specific "special cases":
-//		Scalar has Dims() of 0. However, its shape can take several forms:
-//			- (1, 1)
+//		Scalar has Dims() of 0.
 //			- (1)
+//		Scalarlikes are higher order tensors, but each with a size of 1. The Dims() are not 0.
+//			- (1, 1)
+//			- (1, 1, 1)
+//			- (1, 1, 1, 1), etc
 //		Vector has Dims() of 1, but its shape can take several forms:
 //			- (x, 1)
 //			- (1, x)
@@ -121,9 +124,12 @@ func (ap *AP) IsColVec() bool { return ap.shape.IsColVec() }
 // IsRowVec returns true when the access pattern has the shape (1, x)
 func (ap *AP) IsRowVec() bool { return ap.shape.IsRowVec() }
 
-// IsScalar returns true if the access pattern indicates it's a scalar value
+// IsScalar returns true if the access pattern indicates it's a scalar value.
 func (ap *AP) IsScalar() bool { return ap.shape.IsScalar() }
 
+// IsScalarEquiv returns true if the access pattern is equivalent to a scalar shape.
+func (ap *AP) IsScalarEquiv() bool { return ap.shape.IsScalarEquiv() }
+
 // IsMatrix returns true if it's a matrix. This is mostly a convenience method. RowVec and ColVecs are also considered matrices
 func (ap *AP) IsMatrix() bool { return len(ap.shape) == 2 }
 
@@ -297,6 +303,7 @@ func (ap *AP) S(size int, slices ...Slice) (newAP AP, ndStart, ndEnd int, err er
 
 // T returns the transposed metadata based on the given input
 func (ap *AP) T(axes ...int) (retVal AP, a []int, err error) {
+
 	// prep axes
 	if len(axes) > 0 && len(axes) != ap.Dims() {
 		err = errors.Errorf(dimMismatch, ap.Dims(), len(axes))
@@ -312,6 +319,10 @@ func (ap *AP) T(axes ...int) (retVal AP, a []int, err error) {
 	}
 	a = axes
 
+	if ap.shape.IsScalarEquiv() {
+		return ap.Clone(), a, noopError{}
+	}
+
 	// if axes is 0, 1, 2, 3... then no op
 	if monotonic, incr1 := IsMonotonicInts(axes); monotonic && incr1 && axes[0] == 0 {
 		return ap.Clone(), a, noopError{}

ap_test.go

@@ -112,12 +112,14 @@ func TestAccessPatternIsX(t *testing.T) {
 
 	ap = dummyScalar1()
 	assert.True(ap.IsScalar())
+	assert.True(ap.IsScalarEquiv())
 	assert.False(ap.IsVector())
 	assert.False(ap.IsColVec())
 	assert.False(ap.IsRowVec())
 
 	ap = dummyScalar2()
-	assert.True(ap.IsScalar())
+	assert.False(ap.IsScalar())
+	assert.True(ap.IsScalarEquiv())
 	assert.False(ap.IsVector())
 	assert.False(ap.IsColVec())
 	assert.False(ap.IsRowVec())

consopt.go

@@ -112,10 +112,17 @@ func FromScalar(x interface{}, argMask ...[]bool) ConsOpt {
 			xvi.Set(reflect.ValueOf(x))
 			uptr := unsafe.Pointer(xv.Pointer())
 
+			var v interface{}
+			if !tt.Shape().IsScalar() {
+				sl := reflect.MakeSlice(reflect.SliceOf(xt), 1, 1)
+				zeroth := sl.Index(0)
+				zeroth.Set(reflect.ValueOf(x))
+				v = sl.Interface()
+			}
 			tt.array.Ptr = uptr
 			tt.array.L = 1
 			tt.array.C = 1
-			tt.v = x
+			tt.v = v
 			tt.t = Dtype{xt}
 			tt.mask = mask
 
@@ -146,7 +153,6 @@ func FromMemory(ptr uintptr, memsize uintptr) ConsOpt {
 		switch tt := t.(type) {
 		case *Dense:
 			tt.v = nil // if there were any underlying slices it should be GC'd
-
 			tt.array.Ptr = unsafe.Pointer(ptr)
 			tt.array.L = int(memsize / tt.t.Size())
 			tt.array.C = int(memsize / tt.t.Size())

consopt_test.go

@@ -0,0 +1,94 @@
+package tensor
+
+import (
+	"fmt"
+	"io/ioutil"
+	"os"
+	"syscall"
+	"testing"
+	"testing/quick"
+	"unsafe"
+
+	"github.com/stretchr/testify/assert"
+)
+
+type F64 float64
+
+func newF64(f float64) *F64 { r := F64(f); return &r }
+
+func (f *F64) Uintptr() uintptr { return uintptr(unsafe.Pointer(f)) }
+
+func (f *F64) MemSize() uintptr { return 8 }
+
+func (f *F64) Pointer() unsafe.Pointer { return unsafe.Pointer(f) }
+
+func Test_FromMemory(t *testing.T) {
+	fn := func(F float64) bool {
+		f := newF64(F)
+		T := New(WithShape(), Of(Float64), FromMemory(f.Uintptr(), f.MemSize()))
+		data := T.Data().(float64)
+
+		if data != F {
+			return false
+		}
+		return true
+	}
+	if err := quick.Check(fn, &quick.Config{MaxCount: 1000000}); err != nil {
+		t.Logf("%v", err)
+	}
+
+	f, err := ioutil.TempFile("", "test")
+	if err != nil {
+		t.Fatal(err)
+	}
+	// fill in with fake data
+	backing := make([]byte, 8*1024*1024) // 1024*1024 matrix of float64
+	asFloats := *(*[]float64)(unsafe.Pointer(&backing))
+	asFloats = asFloats[: 1024*1024 : 1024*1024]
+	asFloats[0] = 3.14
+	asFloats[2] = 6.28
+	asFloats[1024*1024-1] = 3.14
+	asFloats[1024*1024-3] = 6.28
+	f.Write(backing)
+
+	// defer cleanup
+	defer os.Remove(f.Name())
+
+	// do the mmap stuff
+	stat, err := f.Stat()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	size := int(stat.Size())
+	fd := int(f.Fd())
+	bs, err := syscall.Mmap(fd, 0, size, syscall.PROT_READ, syscall.MAP_SHARED)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		if err := syscall.Munmap(bs); err != nil {
+			t.Error(err)
+		}
+	}()
+	T := New(WithShape(1024, 1024), Of(Float64), FromMemory(uintptr(unsafe.Pointer(&bs[0])), uintptr(size)))
+
+	s := fmt.Sprintf("%v", T)
+	expected := `⎡3.14     0  6.28     0  ...    0     0     0     0⎤
+⎢   0     0     0     0  ...    0     0     0     0⎥
+⎢   0     0     0     0  ...    0     0     0     0⎥
+⎢   0     0     0     0  ...    0     0     0     0⎥
+.
+.
+.
+⎢   0     0     0     0  ...    0     0     0     0⎥
+⎢   0     0     0     0  ...    0     0     0     0⎥
+⎢   0     0     0     0  ...    0     0     0     0⎥
+⎣   0     0     0     0  ...    0  6.28     0  3.14⎦
+`
+	if s != expected {
+		t.Errorf("Expected mmap'd tensor to be exactly the same.")
+	}
+
+	assert.True(t, T.IsManuallyManaged())
+}

defaultengine_matop_misc.go

@@ -72,9 +72,6 @@ func (StdEng) denseRepeat(t, reuse DenseTensor, newShape Shape, axis, size int,
 		outers = 1
 	} else {
 		outers = ProdInts(t.Shape()[0:axis])
-		if outers == 0 {
-			outers = 1
-		}
 	}
 
 	var stride, newStride int

defaultengine_selbyidx.go

@@ -75,9 +75,8 @@ func (e StdEng) selectByIdx(axis int, indices []int, typ reflect.Type, dataA, da
 	axStride := apA.strides[axis]
 	retStride := apRet.strides[axis]
 	var outerRetStride int
-	if outer == 0 {
+	if axis == 0 {
 		// then it's the outermost
-		outer = 1
 		outerRetStride = apRet.strides[axis] * 2
 	} else {
 		outerRetStride = apRet.strides[axis-1]
@@ -185,9 +184,7 @@ func (e StdEng) selectByIndicesB(axis int, indices []int, typ reflect.Type, data
 	axStride := apB.strides[axis]
 	retStride := apRet.strides[axis]
 	var outerRetStride int
-	if outer == 0 {
-		// then it's the outermost
-		outer = 1
+	if axis == 0 {
 		outerRetStride = apRet.strides[axis] * 2
 	} else {
 		outerRetStride = apRet.strides[axis-1]

example_dense_basics_test.go

@@ -0,0 +1,45 @@
+package tensor
+
+import (
+	"fmt"
+)
+
+// Data shows how the shape of the *Dense actually affects the return value of .Data().
+func ExampleDense_Data() {
+	T := New(WithShape(2, 2), WithBacking([]float64{1, 2, 3, 4}))
+	fmt.Printf("Basics:\n======\nAny kind of arrays: %v\n", T.Data())
+
+	fmt.Printf("\nScalar-like\n===========\n")
+	T = New(WithShape(), FromScalar(3.14))
+	fmt.Printf("WithShape(), FromScalar: %v\n", T.Data())
+
+	T = New(WithShape(), WithBacking([]float64{3.14}))
+	fmt.Printf("WithShape(), With a slice of 1 as backing: %v\n", T.Data())
+
+	T = New(WithShape(1), FromScalar(3.14))
+	fmt.Printf("WithShape(1), With an initial scalar: %v\n", T.Data())
+
+	T = New(WithShape(1, 1), WithBacking([]float64{3.14}))
+	fmt.Printf("WithShape(1, 1), With an initial scalar: %v\n", T.Data())
+
+	T = New(WithShape(1, 1), FromScalar(3.14))
+	fmt.Printf("WithShape(1, 1), With an initial scalar: %v\n", T.Data())
+
+	T.Reshape()
+	fmt.Printf("After reshaping to (): %v\n", T.Data())
+
+	// Output:
+	// Basics:
+	// ======
+	// Any kind of arrays: [1 2 3 4]
+	//
+	// Scalar-like
+	// ===========
+	// WithShape(), FromScalar: 3.14
+	// WithShape(), With a slice of 1 as backing: 3.14
+	// WithShape(1), With an initial scalar: [3.14]
+	// WithShape(1, 1), With an initial scalar: [3.14]
+	// WithShape(1, 1), With an initial scalar: [3.14]
+	// After reshaping to (): 3.14
+
+}

example_dense_matop_test.go

@@ -289,3 +289,80 @@ func ExampleRepeat_uncommonUses() {
 	// Once again, observe that the 1st element ([2 5]) has been repeated 3 times, while the rest have been repeated twice
 
 }
+
+func ExampleT() {
+	// Usual example of 2D matrix being transposed:
+	M := New(WithBacking([]int{1, 2, 3, 4, 5, 6}), WithShape(2, 3))
+	M2, err := T(M)
+	if err != nil {
+		fmt.Printf("Err: %v\n", err)
+	}
+	fmt.Printf("M:\n%v\nM2:\n%v\n", M, M2)
+
+	// T accepts optional parameters describing the permutation of axes.
+	// In a 2D case, there are only two options: (0, 1) or (1, 0).
+	// The latter is default if no parameters are passed in.
+	// The former is a no-op as rearranging a matrix so that the 0th axis becomes the 0th axis
+	// and the first axis becomes the first axis is not going to do anything.
+	//
+	// However, note that M3 is a different result.
+	M3, err := T(M, 0, 1)
+	if err != nil {
+		fmt.Printf("Err: %v\n", err)
+	}
+	fmt.Printf("M3:\n%v\nM == M3: %t", M3, M == M3)
+
+	// Output:
+	// M:
+	// ⎡1  2  3⎤
+	// ⎣4  5  6⎦
+	//
+	// M2:
+	// ⎡1  4⎤
+	// ⎢2  5⎥
+	// ⎣3  6⎦
+	//
+	// M3:
+	// ⎡1  2  3⎤
+	// ⎣4  5  6⎦
+	//
+	// M == M3: false
+
+}
+
+func ExampleT_scalarlike() {
+	// Be aware when dealing with scalarlike tensors
+	// scalar/scalarlikes have no effect when calling T()
+	// but the result is put into a new tensor
+	S := New(WithBacking([]float32{3.14}), WithShape())
+	S2, err := T(S)
+	if err != nil {
+		fmt.Printf("Err %v", err)
+	}
+	fmt.Printf("S: %v S2 %v S == S2: %t\n", S, S2, S == S2)
+
+	// however do note that scalars and scalarlikes are not the same thing.
+	// for example, consider this:
+	_, err = T(S, 1, 0)
+	fmt.Printf("error when the axes are more than the shape's dims: %v\n", err)
+
+	// but if you have a tensor that is a scalar-like:
+	S.Reshape(1, 1)
+	S2, err = T(S, 1, 0)
+	if err != nil {
+		fmt.Printf("Err: %v\n", err)
+	}
+	fmt.Printf("S:\n%v\nS2:\n%v\nS == S2: %t\n", S, S2, S == S2)
+
+	// Output:
+	// S: 3.14 S2 3.14 S == S2: false
+	// error when the axes are more than the shape's dims: Dimension mismatch. Expected 0, got 2
+	// S:
+	// ⎡3.14⎤
+	//
+	// S2:
+	// ⎡3.14⎤
+	//
+	// S == S2: false
+
+}

shape.go

@@ -26,7 +26,7 @@ func (s Shape) TotalSize() int {
 
 // CalcStrides calculates the default strides for a shape
 func (s Shape) CalcStrides() []int {
-	if s.IsScalar() {
+	if s.IsScalarEquiv() {
 		return nil
 	}
 
@@ -52,7 +52,7 @@ func (s Shape) CalcStrides() []int {
 // CalcStridesWithMask is similar to CalcStrides, except that it has an argument, masks. It is used to mask out given dimensions
 // during calculation of stride
 func (s Shape) CalcStridesWithMask(mask []bool) []int {
-	if s.IsScalar() {
+	if s.IsScalarEquiv() {
 		return nil
 	}
 
@@ -87,7 +87,7 @@ func (s Shape) CalcStridesWithMask(mask []bool) []int {
 
 // CalcStridesColMajor is like CalcStrides, but assumes a col major layout
 func (s Shape) CalcStridesColMajor() []int {
-	if s.IsScalar() {
+	if s.IsScalarEquiv() {
 		return nil
 	}
 
@@ -155,7 +155,7 @@ func (s Shape) Clone() Shape {
 
 // IsScalar returns true if the access pattern indicates it's a scalar value
 func (s Shape) IsScalar() bool {
-	return len(s) == 0 || (len(s) == 1 && s[0] == 1)
+	return len(s) == 0
 }
 
 // IsScalarEquiv returns true if the access pattern indicates it's a scalar-like value