Skip to content

Latest commit

 

History

History
411 lines (288 loc) · 12.5 KB

README.md

File metadata and controls

411 lines (288 loc) · 12.5 KB
Raw

lightmatrix

Lightweight JavaScript library for basic matrix computations.

  1. Installation and Usage
  2. API Reference
  3. License

Installation and Usage

Node Usage

You can install the package in Node using either npm or yarn. Simply run any of the following command on your terminal. For npm, run the following command.

npm install lightmatrix --save

If you are using yarn, run the following command instead.

yarn add lightmatrix

You can also install the package with bower using the following command.

bower install lightmatrix

If you installed the package using npm or yarn, you can then require it in your code as follows.

const lightmatrix = require('lightmatrix');

const matrix = [
  [1, 2],
  [3, 4]
];

console.log(lightmatrix.determinant(matrix)); // -2

Note that installing the package with bower will place the package files in the bower_components directory of your project.

Browser Usage

On the browser, you can use the package by adding the following <script> tag to your code.

<script src="https://unpkg.com/lightmatrix/dist/lightmatrix.js"></script>

Minified
At the moment, the minified version of the package is approximately (~3KB).

<script src="https://unpkg.com/lightmatrix/dist/lightmatrix.min.js"></script>

The package adds the namespace: lightmatrix to the global window object when used in the browser and all its methods can be accessed via that namespace. Hence, you can do the following somewhere else in your script:

if (lightmatrix in window) {

  var matrix = [
    [1, 2],
    [3, 4]
  ];

  console.log(lightmatrix.determinant(matrix)); // -2

}

API Reference

Matrix Specification

A matrix is specified using the array literal notation. The matrix is an array of rows, whereas each row is an array of column elements. A column element must be a numeric or number value.

Here is a valid 2x3 matrix (2 rows, 3 cols):

var matrix = [
  [1, 2, 3], // Row 1 (3 column elements)
  [4, 5, 6] // Row 2 (3 column elements)
];

lightmatrix Methods

Here are the available methods of the lightmatrix module:

lightmatrix.ok(matrix)

Alias: lightmatrix.valid

Tests the input matrix argument to verify it is a valid matrix. It returns true if it is a valid matrix, otherwise it returns false.

var matrix = [
  [1, 2],
  [3, 4]
];

console.log(lightmatrix.ok(matrix)); // true
console.log(lightmatrix.valid([1, 2, 3])); // false
console.log(lightmatrix.valid(5)); // false

lightmatrix.dimension(matrix)

Alias: lightmatrix.order

Returns the order of the matrix argument as an array of the format [rows, cols]. However, if the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrix = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.dimension(matrix)); // [2, 3]

console.log(lightmatrix.order([1, 2, 3])); // throws Error
console.log(lightmatrix.order(5)); // throws Error

lightmatrix.unit(dimension)

Alias: lightmatrix.identity

Returns a new identity or unit matrix matrix of the specified dimension. If the dimension argument is 0 or any non-numeric value, then a 2x2 identity matrix is returned by default.

console.log(lightmatrix.unit(3)); // [ [1, 0, 0], [0, 1, 0], [0, 0, 1] ]
console.log(lightmatrix.identity(0)); // [ [1, 0], [0, 1] ]

lightmatrix.equal(matrixA, matrixB)

Alias: lightmatrix.same

Compares the two input matrix arguments matrixA and matrixB to verify they are of the same order and contain the same elements at all positions. It returns true these conditions are met, otherwise it returns false. However, if any of the matrix arguments is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [1, 2],
  [4, 5]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.equal(matrixA, matrixB)); // false
console.log(lightmatrix.same(matrixB, matrixB)); // true

lightmatrix.sum(matrixA, matrixB)

Alias: lightmatrix.add

Adds the two input matrix arguments matrixA and matrixB and returns the resulting matrix provided that the input matrices are of the same order. However, if the input matrices are of different orders, an 'Error: Matrices not compatible.' is thrown. If any of the matrix arguments is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [1, 2],
  [4, 5]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.sum(matrixA, matrixB)); // throws Error
console.log(lightmatrix.add(matrixA, matrixA)); // [ [2, 4], [8, 10] ]

lightmatrix.product(matrixOrScalarA, matrixOrScalarB)

Alias: lightmatrix.multiply

Multiplies the two input matrix/scalar arguments matrixOrScalarA and matrixOrScalarB.

If two scalars are supplied, then the arithmetic product of the scalars is returned. If one scalar and one matrix are supplied, then the resulting scalar product matrix is returned. However, if two matrices are supplied, it returns the resulting product matrix provided that the matrix product matrixOrScalarA * matrixOrScalarB is possible, otherwise an 'Error: Matrices not compatible.' is thrown.

Note: The scalar is required to strictly be of the number type.

If any of the matrix arguments is an array but an invalid matrix, or a non-array, an 'Error: Invalid arguments supplied.' is thrown.

var matrixA = [
  [1, 2],
  [4, 5]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

var matrixC = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];

console.log(lightmatrix.multiply(-5, 10)); // -50
console.log(lightmatrix.multiply(-5, matrixA)); // [ [-5, -10], [-20, -25] ]
console.log(lightmatrix.product(matrixA, matrixB)); // [ [9, 12, 15], [24, 33, 42] ]
console.log(lightmatrix.product(matrixA, matrixC)); // throws Error

lightmatrix.transpose(matrix)

Transposes the input matrix argument and returns the transposed matrix provided that the input matrix is valid. However, if the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrix = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.transpose(matrix)); // [ [1, 4], [2, 5], [3, 6] ]
console.log(lightmatrix.transpose([1, 2, 3])); // throws Error

lightmatrix.determinant(matrix)

Computes and returns the determinant of the matrix argument provided that the input matrix is valid and is a square matrix.

Note: The matrix must be a square matrix to be able to compute its determinant otherwise an 'Error: Square matrix required.' will be thrown.

Note: The determinant is 0 for a singular matrix which means the inverse of such a matrix does not exist.

If the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.determinant(matrixA)); // 0 (singular matrix)
console.log(lightmatrix.determinant(matrixB)); // throws Error (non-square matrix)

lightmatrix.minors(matrix)

Computes the minor of each element of the matrix argument and returns a matrix of the minors provided that the input matrix is valid and is a square matrix.

Note: The matrix must be a square matrix to be able to compute its minors otherwise an 'Error: Square matrix required.' will be thrown.

if the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.minors(matrixA)); // [ [-3, -6, -3], [-6, -12, -6], [-3, -6, -3] ]
console.log(lightmatrix.minors(matrixB)); // throws Error (non-square matrix)

lightmatrix.cofactors(matrix)

Computes the cofactor of each element of the matrix argument and returns a matrix of the cofactors provided that the input matrix is valid and is a square matrix.

Note: The matrix must be a square matrix to be able to compute its cofactors otherwise an 'Error: Square matrix required.' will be thrown.

if the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.cofactors(matrixA)); // [ [-3, 6, -3], [6, -12, 6], [-3, 6, -3] ]
console.log(lightmatrix.cofactors(matrixB)); // throws Error (non-square matrix)

lightmatrix.adjoint(matrix)

Computes and returns the adjoint (transpose of the cofactors matrix) of the matrix argument provided that the input matrix is valid and is a square matrix.

Note: The matrix must be a square matrix to be able to compute its adjoint otherwise an 'Error: Square matrix required.' will be thrown.

if the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.adjoint(matrixA)); // [ [-3, 6, -3], [6, -12, 6], [-3, 6, -3] ]
console.log(lightmatrix.adjoint(matrixB)); // throws Error (non-square matrix)

lightmatrix.inverse(matrix)

Computes and returns the inverse (scalar product of the adjoint matrix and the reciprocal of the determinant) of the matrix argument provided that the input matrix is valid and is a square matrix.

Note: The matrix must be a square matrix to be able to compute its inverse otherwise an 'Error: Square matrix required.' will be thrown.

Note: The inverse cannot be computed for a singular matrix since its determinant is 0. Attempting to compute the inverse throws an 'Error: Cannot compute inverse of singular matrix.'.

if the matrix argument is an array but an invalid matrix, or a non-array, an 'Error: Invalid matrix specification.' is thrown.

var matrixA = [
  [-8, 10],
  [-4, 4]
];

var matrixB = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9]
];

var matrixC = [
  [1, 2, 3],
  [4, 5, 6]
];

console.log(lightmatrix.inverse(matrixA)); // [ [0.5, -1.25], [0.5, -1] ]
console.log(lightmatrix.inverse(matrixB)); // throws Error (singular matrix)
console.log(lightmatrix.inverse(matrixC)); // throws Error (non-square matrix)

License

The lightmatrix package is covered by the MIT License (please read carefully).


MIT License

Copyright (c) 2018 Glad Chinda

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.