blasjs - npm Package Compare versions

Comparing version 1.0.1 to 1.0.2

dist/src/lib/f_func.d.ts

@@ -74,3 +74,3 @@ export declare function isZero(v: Complex): boolean;
 export declare const each: (xx: {}) => (fn: (x: any, idx?: string | number | undefined) => any) => any;
-export declare function numberPrecision(prec?: number): (x: any, ...rest: any[]) => number | number[];
+export declare function numberPrecision(prec?: number): Function;
 export declare function arrayrify<T, R>(fn: (x: T, ...rest: any[]) => R): (x: T | T[], ...rest: any[]) => R | R[];
@@ -77,0 +77,0 @@ export declare function coerceToArray(o: any): {

dist/src/lib/index.d.ts

@@ -5,14 +5,29 @@ import { level1 } from './l1';
 export { level1, level2, level3 };
-import { arrayrify, complex, fortranArrComplex32, fortranArrComplex64, fortranMatrixComplex32, fortranMatrixComplex64, multiplexer, muxCmplx, numberPrecision } from './f_func';
+import { arrayrify, complex, Complex, FortranArr, fortranArrComplex32, fortranArrComplex64, fortranMatrixComplex32, fortranMatrixComplex64, fpArray, multiplexer, muxCmplx, numberPrecision } from './f_func';
 export declare const util: Readonly<{
+    arrayrify: typeof arrayrify;
+    complex: typeof complex;
+    each: (xx: {}) => (fn: (x: any, idx?: string | number | undefined) => any) => any;
     fortranArrComplex32: typeof fortranArrComplex32;
     fortranArrComplex64: typeof fortranArrComplex64;
+    fortranMatrixComplex32: typeof fortranMatrixComplex32;
+    fortranMatrixComplex64: typeof fortranMatrixComplex64;
+    map: (xx: {}) => (fn: (x: any, idx?: string | number | undefined) => any) => any;
+    multiplexer: typeof multiplexer;
+    muxCmplx: typeof muxCmplx;
+    numberPrecision: typeof numberPrecision;
+}>;
+export { Complex, fpArray, FortranArr };
+export declare const helper: Readonly<{
+    arrayrify: typeof arrayrify;
     complex: typeof complex;
     each: (xx: {}) => (fn: (x: any, idx?: string | number | undefined) => any) => any;
-    numberPrecision: typeof numberPrecision;
-    arrayrify: typeof arrayrify;
+    fortranArrComplex32: typeof fortranArrComplex32;
+    fortranArrComplex64: typeof fortranArrComplex64;
+    fortranMatrixComplex32: typeof fortranMatrixComplex32;
+    fortranMatrixComplex64: typeof fortranMatrixComplex64;
+    map: (xx: {}) => (fn: (x: any, idx?: string | number | undefined) => any) => any;
     multiplexer: typeof multiplexer;
     muxCmplx: typeof muxCmplx;
-    fortranMatrixComplex64: typeof fortranMatrixComplex64;
-    fortranMatrixComplex32: typeof fortranMatrixComplex32;
+    numberPrecision: typeof numberPrecision;
 }>;

package.json

@@ -49,3 +49,3 @@ {
         "tslint-loader": "^3.5.3",
-        "typescript": "^2.7.1",
+        "typescript": "^2.8.3",
         "uglifyjs-webpack-plugin": "^1.1.8",
@@ -121,3 +121,3 @@ "webpack": "^2.7.0",
     "types": "./dist/src/lib/index.d.ts",
-    "version": "1.0.1"
+    "version": "1.0.2"
 }

README.md

@@ -1,22 +0,402 @@
-# BLASjs (Basic Linear Algebra Subprograms)
-Pure Javascript (Typescript) implementation of [BLAS](https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms) (Basic Linear Algebra Subprograms).
+# BLASjs  (<span style="font-size:small" ><span style="color:red; font-weight: bold;">B</span>asic <span style="color:red; font-weight: bold;">L</span>inear <span style="color:red; font-weight: bold;">A</span>lgebra <span style="color:red; font-weight: bold;">S</span>ubprograms</span>)
 
-* BLAS cheat sheet in [pdf](http://www.netlib.org/blas/blasqr.pdf).
-* BLAS routines [overview](http://www.netlib.org/blas/#_blas_routines).
+This is a 100% Pure Javascript ( TypeScript ) re-write of the reference implementation `Basic Linear Algebra SubPrograms` (BLAS) numerical library found [here][blas-site].
+This is a full manual re-write, ["emscripten"](https://kripken.github.io/emscripten-site) was not used.
 
-
 #### summary
 
+BLASjs contains all the functions (Complex, Real) of the reference implementation capable for `32 bit` and `64 bit` floating point arithmatic:
 
+* :ok_hand: 100% code coverage
+* 1005 tests
+* Output off all tests equal to the BLAS FORTRAN reference implementation.
+* Level 1: all vector-vector operations implemented.
+* Level 2: all vector-matrix operations implemented.
+* Level 3: all matrix-matrix operations implemented.
+* Helper functions to easy porting of FORTRAN BLAS usage to Javascript.
 
-## Level 1
+#### Node and Web
 
-### SINGLE
+The library js file is an agnostic UMD library, it can be used in a web client
+as-well as in a server side node environment.
 
+## Installation
 
+#### node
+
+```bash
+npm i blasjs
+```
+
+```javascript
+//node
+   const blas = require('blasjs');
+//or typescript
+   import * as blas from 'blasjs';
+```
+
+#### web
+
+The module directory contains a minimized bundle for use in html `<script>` tag. The library is attached to the `window.BLAS` object after loading.
+
+```html
+<!-- script src="your_server_url/blasjs.min.js"></script -->
+<!-- this example uses unpkg as CDN -->
+<script src="https://unpkg.com/blasjs@latest/dist/lib/blasjs.min.js">
+<script>
+  const blas = window.BLAS; //UMD exposes it as BLAS
+
+  //fetch some level3 complex 64 bit precision matrix-matrix operations
+  const {
+      level3: { zsyrk, ztrmm, ztrsm }
+   } = blas;
+</script>
+```
+
+# Table of Contents
+
+* [Language differences with FORTRAN/BLAS](#language-differences-with-fortranblas)
+* [*Read this first*: Helper functions](#helper-functions-for-working-with-blasjs)
+    * [arrayrify](#arrayrify)
+    * [complex](#complex)
+    * [each](#each)
+    * [map](#map)
+    * [muxCmplx](#muxCmplx)
+    * [numberPrecision](#numberPrecision)
+    * [FortranArr](#fortranArr)
+* [Level 1 Functions](#level-1)
+    * [`isamax`/`idamax`/`izamax`/`icamax` find maximum element of a vector]()
+    * [`sasum`/`dasum` sum of the absolute vector element values]()
+    * [`saxpy/daxpy/caxpy/zaxpy` ]
+    * scnrm2
+    * scopy/dcopy/ccopy/zcopy
+    * sdot/ddot/cdotc/zdotc
+    * sdsdot/dsdot  Compute the inner product of two vectors with extended precision.
+    * snrm2/drnm2
+    * srot/drot/zdrot/csrot
+    * srotg/drotg/crotg/zrotg
+    * srotm/drotm
+    * srotmg/drotmg
+    * sscal/dscal/cscal/csscal
+    * sswap/dswap/cswap/zswap
+    * cdotu/zdotu
+    * scasum/dzasum
+
+* [Level 2](#level-2) 
+    * sgbmv/dgbmv/cgbmv/zgbmv
+    * sgemv/dgemv/cgemv/zgemv
+    * sger/dger
+    * ssbmv/dspmv
+    * sspr/dspr
+    * ssymv/dsymv
+    * ssyr/dsyr
+    * sspr2/dspr2
+    * ssymv, dsymv
+    * ssyr/dsyr
+    * ssyr2, dsyr2
+    * stbmv/dtbmv/ctbmv/ztbmv
+    * stbsv/dtbsv/ctbsv/ztbsv
+    * stpmv/dtpmv/ctpmv/ztpmv
+    * stpsv/dtpsv/ctpsv/ztpsv
+    * strmv/dtrmv/ctrmv/ztrmv
+    * strsv/dtrsv/ctrsv/ztrsv
+    * strmv/dtrmv/ctrmv/ztrmv
+    * strsv/dtrsv/ctrsv/ztrsv
+    * cgerc/zgerc
+    * cgeru/zgeru
+    * chbmv/zhbmv
+    * chemv/zhemv
+    * cher/zher
+    * cher2/zher2
+    * chpmv/zhpmv
+    * chpr/zhpr
+    * chpr2/zhpr2
+
+# Language differences with FORTRAN/BLAS.
+
+FORTRAN language can instrinsicly work with non-zero based multidimensional arrays and complex numbers. Below are some examples from FORTRAN that have no Javascript counterpart. The reference implementation of BLAS functions expect inputs of these types.
+
+`FORTRAN complex scalar, complex array, complex Matrix`
+
+```fortran
+!    double precision Complex number
+     COMPLEX*16 alpha
+!
+!    double precision Complex array with offset 2
+     COMPLEX*16 vector(2,10)
+!
+!    double precision complex MultiDimensional Array (matrix)
+!    rows 1 to 5 , columns 1 to 10
+     COMPLEX*16 A(1:5,1:10)
+```
+
+To work with the concept of non-zero based arrays and complex numbers in JS, 
+these FORTRAN constructs have equivalents in the `blasjs` library.
+
+`blasjs complex scalar, complex array, complex Matrix`
+
+```javascript
+  const blas = require('blasjs');
+
+  const {
+      helper:{
+        /* create complex Object from 2 real numbers */
+        complex,
+
+        /* create single precision Real/complex arrays, */
+        fortranArrComplex32,
+
+        /* create double precision Real/Complex arrays */
+        fortranArrComplex64,
+
+        /* create single precision 2 dimensional Real/Complex arrays */
+        fortranMatrixComplex32,
+
+        /* Double precision 2 dimensional Real/Complex arrays */
+        fortranMatrixComplex64,
+      }
+  } = blas;
+```
+
+These functions are extensively documented in the [helper functions](#helper-functions-for-working-with-blasjs).
+It is recommended you read this introductory part of the documentation first.
+before anything else.
+
+# Helper functions
+
+`blasjs`
+uses "FORTRAN like" complex number 32/64 bit precision multidimensional complex/real data.
+These helper functions have been designed to significantly ease the use of working with these
+data types in JavaScript.
+
+### `arrayrify`
+
+Creates a new function capable to accept vectorized input, by wrapping an existing function given as argument.
+
+_Example_:
+
+```javascript
+const blas = require('blasjs');
+
+const { helper: { arrayrify } } = blas;
+const PI = Math.PI;
+//
+const sin = arrayrify(Math.sin)
+
+sin([PI/3, PI/4, PI/6]); // returns array aswell
+// [ 0.866025, 0.7071067811, 0.5 ]
+
+sin(PI/3); // returns scalar
+sin( [ PI/3 ] ); // returns scalar
+// 0.866025
+
+sin([]) // edge case
+// undefined
+
+sin() //
+//NaN  same as Math.sin()
+```
+
+### `complex`
+
+Mimics the GNU Fortran extension [complex](https://gcc.gnu.org/onlinedocs/gfortran/COMPLEX.html).
+Creates a JS object that represents a complex scalar number.
+Used by `blasjs` for scalar input arguments.
+
+_Example_:
+
+```javascript
+const blas = require('blasjs');
+
+const { helper: { complex } } = blas;
+
+const c1 = complex(0.1,0.3);
+//c1 = { re: 0.1, im: 0.3 }
+
+const c2 = complex();
+//c2 = { re: 0, im: 0 }
+
+const c3 = complex(0.5);
+//c3 = { re: 0.5, im:0 }
+```
+
+### `each`
+
+Curried functional analog to `Array.prototype.forEach`, but takes arbitrary input.
+
+_Example_:
+
+```javascript
+const blas = require('blasjs');
+
+const { helper: { each } } = blas;
+
+//Iterates over an object like a map
+const curry1 = each( {  hello: 'world', ts: new Date() })
+curry1( (val, key) => console.log(`${val} ':'  ${key}`)))
+//world : hello
+//2018-05-10T13:57:08.923Z : ts
+
+//Handles array also
+each( ['a','b','c','d'])( (v,idx) =>console.log(v,idx, typeof idx))
+//a 0 number
+//b 1 number
+//c 2 number
+//d 3 number
+
+//Edge cases
+each()(console.log)
+//nothing happens
+
+each(null)(console.log)
+//nothing happens
+
+each([])(console.log)
+//nothing happens
+```
+
+### `map`
+
+Curried functional analog to `Array.prototype.map`, but takes arbitrary input.
+
+:warning: Forces the output to be a an array regardless of the input.
+
+_Example_:
+
+```javascript
+const blas = require('blasjs');
+
+const { helper: { map } } = blas;
+
+//trivial
+map([1,2,3])(v=>v*2);
+//[ 2, 4, 6 ]
+
+//key properties
+map({ a:'A', b:'B' })( (val, key) => key+'='+val);
+//[ 'a=A', 'b=B' ]
+
+map(null)( v => '/'+v);
+//[]
+
+map()( v => '/'+v);
+//[]
+
+map()()
+//[]
+```
+
+### `muxCmplx`
+
+Creates an array of complex numbers from arrayed input.
+The result is always an array type.
+
+_Example_:
+
+```javascript
+const blas = require('blasjs');
+
+const { helper: { muxCmplx } } = blas;
+
+const reals = [ 0.1, -0.2, 0.3, 0.45 ];
+const imaginary = [ 0.1, -0.2, 0.3, 0.45 ];
+
+// normal usage
+muxCmplx(reals, imaginary)
+/*[ { re: 0.1, im: 0.1 },
+    { re: -0.2, im: -0.2 },
+    { re: 0.3, im: 0.3 },
+    { re: 0.45, im: 0.45 } ]*/
+
+//R recycling rule is used
+muxCmplx([1,2], imaginary)
+/*^[ { re: 1, im: 0.1 },
+     { re: 2, im: -0.2 },
+     { re: 1, im: 0.3 },
+     { re: 2, im: 0.45 } ]*/
+
+//dont care about imaginary
+muxCmplx(reals)
+/*[ { re: 0.1, im: undefined },
+    { re: -0.2, im: undefined },
+    { re: 0.3, im: undefined },
+    { re: 0.45, im: undefined } ]*/
+
+muxCmplx() //
+// [ { re: undefined, im: undefined } ]
+
+muxCmplx(1) //
+// [ { re: 1, im: undefined } ]
+
+//3 specify real and imaginary
+muxCmplx(1,-2)//
+//[ { re: 1, im: -2 } ]
+```
+
+#### `numberPrecision`
+
+Enforces significant figure of a number, or on the properties of a JS object (deep search) with numeric values.
+
+_Example_:
+
+```javascript
+const blas = require('blasjs');
+
+const { helper: { numberPrecision } } = blas;
+
+const _4 = numberPrecision(4);
+
+_4(0.123456789);
+//0.1235
+
+_4(123456789)
+//123500000
+
+//enforce significance over properties
+_4( { car: 'Mazda' , aux: { priceUSD: 24.3253E+3, maxWarpSpeed:3.42111E-4 } } );
+//{ car: 'Mazda', aux: { priceUSD: 24330, maxWarpSpeed: 0.0003421 } }
+
+_4([0.123456, 0.78901234]);
+//[ 0.1235, 0.789 ]
+```
+
+#### `FortranArr`
+
+Abstraction of a 1 dimensional single precision (32bit) complex/real FORTRAN array.
+Used by [level 1](#level-1) and [level 2](#level-2) `blasjs` functions.
+`FortranArr`objects should be created by the [`fortranArrComplex32`](#fortranArrComplex32) and [`fortranArrComplex64`](#fortranArrComplex64) helper functions.
+
+_decl_:
+
+```typescript
+export declare type FortranArr = {
+    base: number;
+    r: fpArray; 
+    i?: fpArray;
+    s: FortranSetterGetter;
+    toArr: () => Complex[] | number[];
+};
+```
+
+* Iterates over object properties and values.
+* Iterates over array elements 
+    fortranArrComplex32,
+    fortranArrComplex64,
+    fortranMatrixComplex32,
+    fortranMatrixComplex64,
+
+   
+
+
+
 [srotg]: https://en.wikipedia.org/wiki/Givens_rotation
 [givenmodified]: https://www.ibm.com/support/knowledgecenter/en/SSFHY8_5.5.0/com.ibm.cluster.essl.v5r5.essl100.doc/am5gr_srotm.htm
 
-[caxpy]: http://www.netlib.org/lapack/explore-html/da/df6/group__complex__blas__level1_ga9605cb98791e2038fd89aaef63a31be1.html
+[caxpy]:  http://www.netlib.org/lapack/explore-html/da/df6/group__complex__blas__level1_ga9605cb98791e2038fd89aaef63a31be1.html
 
+[blas-site]: http://www.netlib.org/blas/
+[blas-source]: https://github.com/Reference-LAPACK/lapack/tree/master/BLAS
+
+
+
 Some notes on Matrix symbols
@@ -29,2 +409,5 @@
 
-A̅ᵗ ∙ B̅  
+_`A̅ᵗ ∙ B̅`_
+
+Aᵗ 
+```

No alert changes

Improved metrics

Lines of code

9721

increased by0.19%

Number of lines in readme file

413

increased by1324.14%

Worsened metrics

Total package byte prevSize

2017509

decreased by-1.49%

No dependency changes