Core design ideas

This page serves as a reference of design ideas that lay in core of core.matrix.

• Explicitness is preferred - you get what you ask for
• except when the contrary stated in documentation or makes no sense, all functions receive arguments of identical dimensionality and shape (example: in (add a b) a and b should be of the same shape; in (mul a b) a and b should be of same dimensionality, if you want to multiply matrix (2d) by vector (1d), please reshape the vector to column or row matrix);
• Mike: I think we want to support the broadcasting case for elementwise operations I've added a section Broadcasting describing how it currently works
• reshape and broadcast should be fast;
• Mike: not sure if reshape can always be fast - doesn't it often imply making a full copy of data?
• it is assumed by default implementations of protocols that get- (and set-…! for mutable implementations) are fast and that the data is arranged in row-major order in memory (so the access is as sequential as possible);
• when it's motivated by performance reasons, default protocol implementations can coerce at least one input argument to NDArray (copying the data) and return NDArray instead of original datatype (mul on immutable implementations is one of examples); this effect should be stated in default.clj in documentation for protocol implementation.
• second element of operations such as matrix multiplication can be internally coerced to the type of first element, so be aware of your types