├── .eslintrc ├── .gitignore ├── .travis.yml ├── LICENSE ├── README.md ├── docs ├── costants.md ├── functions.md ├── functions │ ├── abs.md │ ├── acos.md │ ├── acosh.md │ ├── acot.md │ ├── acoth.md │ ├── acsc.md │ ├── acsch.md │ ├── add.md │ ├── and.md │ ├── arg.md │ ├── asec.md │ ├── asech.md │ ├── asin.md │ ├── asinh.md │ ├── atan.md │ ├── atan2.md │ ├── atanh.md │ ├── bellNumbers.md │ ├── bignumber.md │ ├── bitAnd.md │ ├── bitNot.md │ ├── bitOr.md │ ├── bitXor.md │ ├── boolean.md │ ├── catalan.md │ ├── cbrt.md │ ├── ceil.md │ ├── chain.md │ ├── combinations.md │ ├── compare.md │ ├── complex.md │ ├── composition.md │ ├── concat.md │ ├── config.md │ ├── conj.md │ ├── cos.md │ ├── cosh.md │ ├── cot.md │ ├── coth.md │ ├── createUnit.md │ ├── cross.md │ ├── csc.md │ ├── csch.md │ ├── cube.md │ ├── deepEqual.md │ ├── det.md │ ├── diag.md │ ├── distance.md │ ├── divide.md │ ├── dot.md │ ├── dotDivide.md │ ├── dotMultiply.md │ ├── dotPow.md │ ├── equal.md │ ├── exp.md │ ├── eye.md │ ├── factorial.md │ ├── filter.md │ ├── fix.md │ ├── flatten.md │ ├── floor.md │ ├── fraction.md │ ├── gamma.md │ ├── gcd.md │ ├── hypot.md │ ├── im.md │ ├── intersect.md │ ├── inv.md │ ├── isInteger.md │ ├── isNaN.md │ ├── isNegative.md │ ├── isNumeric.md │ ├── isPositive.md │ ├── isPrime.md │ ├── isZero.md │ ├── kldivergence.md │ ├── larger.md │ ├── largerEq.md │ ├── lcm.md │ ├── leftShift.md │ ├── log.md │ ├── log10.md │ ├── lsolve.md │ ├── lup.md │ ├── lusolve.md │ ├── matrix.md │ ├── max.md │ ├── mean.md │ ├── median.md │ ├── min.md │ ├── mod.md │ ├── mode.md │ ├── multinomial.md │ ├── multiply.md │ ├── norm.md │ ├── not.md │ ├── nthRoot.md │ ├── number.md │ ├── ones.md │ ├── or.md │ ├── partitionSelect.md │ ├── permutations.md │ ├── pickRandom.md │ ├── pow.md │ ├── prod.md │ ├── quantileSeq.md │ ├── random.md │ ├── randomInt.md │ ├── range.md │ ├── re.md │ ├── resize.md │ ├── rightArithShift.md │ ├── rightLogShift.md │ ├── round.md │ ├── sec.md │ ├── sech.md │ ├── sign.md │ ├── sin.md │ ├── sinh.md │ ├── size.md │ ├── slu.md │ ├── smaller.md │ ├── smallerEq.md │ ├── sort.md │ ├── sparse.md │ ├── splitUnit.md │ ├── sqrt.md │ ├── square.md │ ├── squeeze.md │ ├── std.md │ ├── stirlingS2.md │ ├── string.md │ ├── subset.md │ ├── subtract.md │ ├── sum.md │ ├── tan.md │ ├── tanh.md │ ├── to.md │ ├── trace.md │ ├── transpose.md │ ├── unaryMinus.md │ ├── unaryPlus.md │ ├── unequal.md │ ├── unit.md │ ├── usolve.md │ ├── var.md │ ├── xgcd.md │ ├── xor.md │ └── zeros.md ├── index.md ├── installation.md ├── operators.md ├── release.md └── units.md ├── functions ├── enviroment │ └── math-enviroment.js ├── math.js └── nop.js ├── gulpfile.js ├── index.js ├── logo.png ├── mkdocs.yml ├── package.json └── test.sh /.eslintrc: -------------------------------------------------------------------------------- 1 | --- 2 | extends: '@elastic/kibana' 3 | rules: 4 | "no-unused-vars": 0 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | 6 | # Runtime data 7 | pids 8 | *.pid 9 | *.seed 10 | 11 | # Directory for instrumented libs generated by jscoverage/JSCover 12 | lib-cov 13 | 14 | # Coverage directory used by tools like istanbul 15 | coverage 16 | 17 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 18 | .grunt 19 | 20 | # node-waf configuration 21 | .lock-wscript 22 | 23 | # Compiled binary addons (http://nodejs.org/api/addons.html) 24 | build/Release 25 | 26 | # Dependency directory 27 | node_modules 28 | 29 | # Optional npm cache directory 30 | .npm 31 | 32 | # Optional REPL history 33 | .node_repl_history 34 | 35 | build 36 | target 37 | site/ 38 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - 6 4 | 5 | addons: 6 | apt: 7 | sources: 8 | - ubuntu-toolchain-r-test 9 | packages: 10 | - g++-4.8 11 | sudo: required 12 | dist: trusty 13 | 14 | env: 15 | - ELASTIC_VERSION="5.6.0" 16 | - ELASTIC_VERSION="5.6.4" DEPLOY="true" 17 | 18 | 19 | 20 | before_script: 21 | - CXX="g++-4.8" 22 | - npm install -g gulp 23 | - wget -O kibana.tar.gz https://github.com/elastic/kibana/archive/v${ELASTIC_VERSION}.tar.gz 24 | - mkdir -p kibana && tar -zxf kibana.tar.gz -C kibana --strip-components=1 25 | - sh -c 'cd kibana && npm install' 26 | - curl -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-${ELASTIC_VERSION}.deb && sudo dpkg -i --force-confnew elasticsearch-${ELASTIC_VERSION}.deb && sudo service elasticsearch restart 27 | - curl -O https://raw.githubusercontent.com/rockymadden/transfer-cli/master/src/transfer && chmod +x transfer 28 | - pip install requests[security] 29 | - pip install --user mkdocs 30 | 31 | script: 32 | - mkdocs build 33 | - gulp build 34 | - gulp package 35 | - bash test.sh 36 | 37 | deploy: 38 | provider: releases 39 | file_glob: true 40 | api_key: 41 | secure: pJitDpcL+ApeS39FK96Jm4o+5grv/XmfnPO0EK753WvF+biMjvDLE2/7vKF0jUzHNZrNVGmLSXLxv0JqIliDyhS7H1SLiOrlQb/JpROJy44W8InDVW00YcpUXqezMrX4J2w5LdhlMZ6X5C8uo6VEI4DmexT6apQ1atWXa3Ew/ZaAzVNvnXq3S1NasAJxBZsZ+vOaJM/eubgpQ61z2iww/S9Q4U32RSG6/fX1xZ/rj2Mc0VWzdT3jBr4v8ROooG42n33T8zqTfuw/Ml5yqjy+a7niCZ+mJESWWnZHC773xlyo2aEOBnsMrdxrCgO+xqZo5BC3wWssMmXFaMIkgC380IOapM0/r7rG+tLhBilGsx0nxeE8AR2PoZXGPAxEb2obqr8s1e8Cex6JGGY8WWp9aytRUgxXsWRyV6dtEef9mRVhMxXC83cfBE4WyVbL054E2ePlhTFD6UwzHR+86YK/jT+05UoQlGDmEFPB4uCxZBhHTta+hJ+fvcxTfqDltL+PqZ65Z3DQP38PTiDjVeuthIJ15TtqO5AFOH5FR1vlEG4zsMfc/Vc4voHzz/BqxK7RFM27xM8OfYqwMAzNh58KriJS5ALwgP7ejM2M4RkmrwOcC8wcCI16vJk5TC66vVU79eWpAgL/oNJppOiHC3q/sSuJWmCUteDdGEJeMCP5AMg= 42 | file: target/mathlion-*.zip 43 | skip_cleanup: true 44 | draft: true 45 | on: 46 | repo: fermiumlabs/mathlion 47 | tags: true 48 | condition: "$DEPLOY = true" 49 | notifications: 50 | email: false 51 | slack: fermiumlabs:0BfrFyD9uqr9bFhsH0Etn4wo 52 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | Fermium LABS logo 3 | 4 | 5 | # Mathlion 6 | 7 | [![Build Status](https://travis-ci.org/fermiumlabs/mathlion.svg?branch=master)](https://travis-ci.org/fermiumlabs/mathlion) [![Github Releases (by Release)](https://img.shields.io/github/downloads/fermiumlabs/mathlion/total.svg)](https://github.com/fermiumlabs/mathlion/releases/latest) 8 | 9 | ![logo](logo.png) 10 | 11 | Mathlion is a Kibana extension that enables equation parsing and advanced math under Timelion. 12 | Check out what it can do in the [documentation](http://mathlion.docs.fermiumlabs.com/) 13 | 14 | ### Installation 15 | 16 | Copy the last installation url for your version of Kibana from [the repository releases](https://github.com/fermiumlabs/mathlion/releases/latest). The file follows the naming `mathlion-major.minor.patch_for_kibana-major.minor.patch.zip` where the first version is the one of mathlion, the second version indicated it's the one in Kibana. 17 | 18 | Remember that starting from Kibana 5.0 you always need an update version of every plugin for it to start as indicated [here](https://siren.solutions/in-kibana-5-all-your-plugins-will-break-at-each-and-every-update/). 19 | 20 | ```sh 21 | #Kibana >= 5.x 22 | 23 | ./bin/kibana-plugin install https://github.com/fermiumlabs/mathlion/releases/download/version_name/mathlion-major.minor.patch_for_kibana-major.minor.patch.zip 24 | 25 | #Kibana 4 26 | ./bin/kibana --install mathlion -u https://github.com/fermiumlabs/mathlion/releases/download/version_name/mathlion-0.2.0_for_kibana-4.X.zip 27 | ``` 28 | 29 | ### Examples 30 | 31 | ```js 32 | .es(*).math("a=source") //the variable "a" now contains the elasticsearch query. 33 | .nop().math("a") //this row now equals the former elasticsearch query 34 | 35 | .es(*).math("source") //return the .es(*) query 36 | .es(*).math("source+5") // add 5 to the .es(*) query 37 | 38 | .nop().math("a=a+2 ; a=a+3 ") //adds 5 to a 39 | .nop().math("a=a+2 ; a=a+3 ; a ") //adds 5 to a and displays a+5 40 | 41 | .es(*).math("a=source") //this query is invisible and does not generate an axis 42 | .es(*).math("a=source; a") //this query does 43 | 44 | .nop.math("sqrt(3^2 + 4^2)") //returns 5 45 | 46 | //Calculate power comsumption based on measured current and stimated voltage (in Europe) 47 | .nop().math("electricPower(v,i)=(v*i)") 48 | .es(metric=avg:current).math(machineCurrent=source) 49 | .nop().math("elascPower(230,machineCurrent)") 50 | 51 | //plot the horizontal statistical mean and variance 52 | .es(*).math("me=mean(source); va=var(source)") 53 | .value(1).math(me*source) 54 | .value(1).math("(me+sqrt(va))*source") 55 | .value(1).math("(me-sqrt(va))*source") 56 | 57 | ``` 58 | 59 | ## Supported Kibana versions 60 | 61 | This plugin is supported by: 62 | 63 | * Kibana 5 64 | * Kibana 4.x (check out branch [backport-4](https://github.com/fermiumlabs/mathlion/tree/backport-4)) 65 | 66 | We regularly test only for Kibana 5. If you find bugs on Kibana 4 you can open a issue, but we would prefer a pull request. 67 | 68 | ## Features: 69 | 70 | * Full-featured math in Timelion 71 | * Variables and custom functions 72 | * Physical constants 73 | * Units of measurement 74 | 75 | For upcoming features and TODOs check [here](https://github.com/fermiumlabs/mathlion/projects). 76 | 77 | ## How to update (for developers) 78 | 79 | If you need to update mathlion for a new Kibana release: 80 | 81 | 1. Add your version to package.json, inside "kibanas". 82 | 2. Inside travis.yml add an "ELASTIC_VERSION" environmental variable with the latest version of kibana. 83 | 3. commit your changes 84 | 4. run `npm version patch` 85 | 86 | ## How to request an update (for users) 87 | 88 | If you need to update mathlion for a new Kibana release: 89 | 90 | 1. Add your version to package.json, inside "kibanas". Be sure to write correct Json. You can validate it [Here](https://jsonlint.com/) 91 | 2. Inside travis.yml add your version [Here](https://github.com/fermiumlabs/mathlion/blob/master/.travis.yml#L16) 92 | 3. open a Pull request against Master 93 | 94 | If you need it urgently, write to support@fermiumlabs.com 95 | 96 | --- 97 | 98 | 99 | Follow Fermium LABS on Twitter 100 | 101 | -------------------------------------------------------------------------------- /docs/functions/abs.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function abs 4 | 5 | Calculate the absolute value of a number. For matrices, the function is 6 | evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | abs(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | A number or matrix for which to get the absolute value 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | Absolute value of `x` 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | abs(3.5); // returns number 3.5 32 | abs(-4.2); // returns number 4.2 33 | 34 | abs([3, -5, -1, 0, 2]); // returns Array [3, 5, 1, 0, 2] 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [sign](sign.md) 41 | -------------------------------------------------------------------------------- /docs/functions/acos.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function acos 4 | 5 | Calculate the inverse cosine of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | acos(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | The arc cosine of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | acos(0.5); // returns number 1.0471975511965979 33 | acos(cos(1.5)); // returns number 1.5 34 | 35 | acos(2); // returns Complex 0 + 1.3169578969248166 i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [cos](cos.md), 42 | [atan](atan.md), 43 | [asin](asin.md) 44 | -------------------------------------------------------------------------------- /docs/functions/acosh.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function acosh 4 | 5 | Calculate the hyperbolic arccos of a value, 6 | defined as `acosh(x) = ln(sqrt(x^2 - 1) + x)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | acosh(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic arccosine of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | acosh(1.5); // returns 0.9624236501192069 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [cosh](cosh.md), 40 | [asinh](asinh.md), 41 | [atanh](atanh.md) 42 | -------------------------------------------------------------------------------- /docs/functions/acot.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function acot 4 | 5 | Calculate the inverse cotangent of a value, defined as `acot(x) = atan(1/x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | acot(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Complex | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | Complex | Array | Matrix | The arc cotangent of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | acot(0.5); // returns number 0.4636476090008061 33 | acot(cot(1.5)); // returns number 1.5 34 | 35 | acot(2); // returns Complex 1.5707963267948966 -1.3169578969248166 i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [cot](cot.md), 42 | [atan](atan.md) 43 | -------------------------------------------------------------------------------- /docs/functions/acoth.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function acoth 4 | 5 | Calculate the hyperbolic arccotangent of a value, 6 | defined as `acoth(x) = atanh(1/x) = (ln((x+1)/x) + ln(x/(x-1))) / 2`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | acoth(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic arccotangent of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | acoth(0.5); // returns 0.8047189562170503 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [acsch](acsch.md), 40 | [asech](asech.md) 41 | -------------------------------------------------------------------------------- /docs/functions/acsc.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function acsc 4 | 5 | Calculate the inverse cosecant of a value, defined as `acsc(x) = asin(1/x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | acsc(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Complex | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | Complex | Array | Matrix | The arc cosecant of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | acsc(0.5); // returns number 0.5235987755982989 33 | acsc(csc(1.5)); // returns number ~1.5 34 | 35 | acsc(2); // returns Complex 1.5707963267948966 -1.3169578969248166 i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [csc](csc.md), 42 | [asin](asin.md), 43 | [asec](asec.md) 44 | -------------------------------------------------------------------------------- /docs/functions/acsch.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function acsch 4 | 5 | Calculate the hyperbolic arccosecant of a value, 6 | defined as `acsch(x) = asinh(1/x) = ln(1/x + sqrt(1/x^2 + 1))`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | acsch(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic arccosecant of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | acsch(0.5); // returns 1.4436354751788103 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [asech](asech.md), 40 | [acoth](acoth.md) 41 | -------------------------------------------------------------------------------- /docs/functions/add.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function add 4 | 5 | Add two values, `x + y`. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | add(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | First value to add 20 | `y` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Second value to add 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Sum of `x` and `y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | add(2, 3); // returns number 5 33 | 34 | var a = complex(2, 3); 35 | var b = complex(-4, 1); 36 | add(a, b); // returns Complex -2 + 4i 37 | 38 | add([1, 2, 3], 4); // returns Array [5, 6, 7] 39 | 40 | var c = unit('5 cm'); 41 | var d = unit('2.1 mm'); 42 | add(c, d); // returns Unit 52.1 mm 43 | 44 | add("2.3", "4"); // returns number 6.3 45 | ``` 46 | 47 | 48 | ## See also 49 | 50 | [subtract](subtract.md) 51 | -------------------------------------------------------------------------------- /docs/functions/and.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function and 4 | 5 | Logical `and`. Test whether two values are both defined with a nonzero/nonempty value. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | and(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | First value to check 20 | `y` | number | BigNumber | Complex | Unit | Array | Matrix | Second value to check 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | boolean | Array | Matrix | Returns true when both inputs are defined with a nonzero/nonempty value. 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | and(2, 4); // returns true 33 | 34 | a = [2, 0, 0]; 35 | b = [3, 7, 0]; 36 | c = 0; 37 | 38 | and(a, b); // returns [true, false, false] 39 | and(a, c); // returns [false, false, false] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [not](not.md), 46 | [or](or.md), 47 | [xor](xor.md) 48 | -------------------------------------------------------------------------------- /docs/functions/arg.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function arg 4 | 5 | Compute the argument of a complex value. 6 | For a complex number `a + bi`, the argument is computed as `atan2(b, a)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | arg(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Array | Matrix | A complex number or array with complex numbers 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Array | Matrix | The argument of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var a = complex(2, 2); 34 | arg(a) / pi; // returns number 0.25 35 | 36 | var b = complex('2 + 3i'); 37 | arg(b); // returns number 0.982793723247329 38 | atan2(3, 2); // returns number 0.982793723247329 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [re](re.md), 45 | [im](im.md), 46 | [conj](conj.md), 47 | [abs](abs.md) 48 | -------------------------------------------------------------------------------- /docs/functions/asec.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function asec 4 | 5 | Calculate the inverse secant of a value. Defined as `asec(x) = acos(1/x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | asec(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Complex | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | Complex | Array | Matrix | The arc secant of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | asec(0.5); // returns 1.0471975511965979 33 | asec(sec(1.5)); // returns 1.5 34 | 35 | asec(2); // returns 0 + 1.3169578969248166 i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [acos](acos.md), 42 | [acot](acot.md), 43 | [acsc](acsc.md) 44 | -------------------------------------------------------------------------------- /docs/functions/asech.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function asech 4 | 5 | Calculate the hyperbolic arcsecant of a value, 6 | defined as `asech(x) = acosh(1/x) = ln(sqrt(1/x^2 - 1) + 1/x)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | asech(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic arcsecant of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | asech(0.5); // returns 1.3169578969248166 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [acsch](acsch.md), 40 | [acoth](acoth.md) 41 | -------------------------------------------------------------------------------- /docs/functions/asin.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function asin 4 | 5 | Calculate the inverse sine of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | asin(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | The arc sine of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | asin(0.5); // returns number 0.5235987755982989 33 | asin(sin(1.5)); // returns number ~1.5 34 | 35 | asin(2); // returns Complex 1.5707963267948966 -1.3169578969248166 i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [sin](sin.md), 42 | [atan](atan.md), 43 | [acos](acos.md) 44 | -------------------------------------------------------------------------------- /docs/functions/asinh.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function asinh 4 | 5 | Calculate the hyperbolic arcsine of a value, 6 | defined as `asinh(x) = ln(x + sqrt(x^2 + 1))`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | asinh(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic arcsine of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | asinh(0.5); // returns 0.48121182505960347 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [acosh](acosh.md), 40 | [atanh](atanh.md) 41 | -------------------------------------------------------------------------------- /docs/functions/atan.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function atan 4 | 5 | Calculate the inverse tangent of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | atan(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | The arc tangent of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | atan(0.5); // returns number 0.4636476090008061 33 | atan(tan(1.5)); // returns number 1.5 34 | 35 | atan(2); // returns Complex 1.5707963267948966 -1.3169578969248166 i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [tan](tan.md), 42 | [asin](asin.md), 43 | [acos](acos.md) 44 | -------------------------------------------------------------------------------- /docs/functions/atan2.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function atan2 4 | 5 | Calculate the inverse tangent function with two arguments, y/x. 6 | By providing two arguments, the right quadrant of the computed angle can be 7 | determined. 8 | 9 | For matrices, the function is evaluated element wise. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | atan2(y, x) 16 | ``` 17 | 18 | ### Parameters 19 | 20 | Parameter | Type | Description 21 | --------- | ---- | ----------- 22 | `y` | number | Array | Matrix | Second dimension 23 | `x` | number | Array | Matrix | First dimension 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | number | Array | Matrix | Four-quadrant inverse tangent 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | atan2(2, 2) / pi; // returns number 0.25 36 | 37 | var angle = unit(60, 'deg'); // returns Unit 60 deg 38 | var x = cos(angle); 39 | var y = sin(angle); 40 | 41 | atan(2); // returns Complex 1.5707963267948966 -1.3169578969248166 i 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [tan](tan.md), 48 | [atan](atan.md), 49 | [sin](sin.md), 50 | [cos](cos.md) 51 | -------------------------------------------------------------------------------- /docs/functions/atanh.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function atanh 4 | 5 | Calculate the hyperbolic arctangent of a value, 6 | defined as `atanh(x) = ln((1 + x)/(1 - x)) / 2`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | atanh(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic arctangent of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | atanh(0.5); // returns 0.5493061443340549 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [acosh](acosh.md), 40 | [asinh](asinh.md) 41 | -------------------------------------------------------------------------------- /docs/functions/bellNumbers.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function bellNumbers 4 | 5 | The Bell Numbers count the number of partitions of a set. A partition is a pairwise disjoint subset of S whose union is S. 6 | bellNumbers only takes integer arguments. 7 | The following condition must be enforced: n >= 0 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | bellNumbers(n) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `n` | Number | BigNumber | Total number of objects in the set 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | Number | BigNumber | B(n) 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | bellNumbers(3); // returns 5; 33 | bellNumbers(8); // returns 4140; 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [stirlingS2](stirlingS2.md) 40 | -------------------------------------------------------------------------------- /docs/functions/bignumber.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function bignumber 4 | 5 | Create a BigNumber, which can store numbers with arbitrary precision. 6 | When a matrix is provided, all elements will be converted to BigNumber. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | bignumber(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `value` | number | string | Fraction | BigNumber | Array | Matrix | boolean | null | Value for the big number, 0 by default. 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | BigNumber | The created bignumber 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | 0.1 + 0.2; // returns number 0.30000000000000004 32 | bignumber(0.1) + bignumber(0.2); // returns BigNumber 0.3 33 | 34 | 35 | 7.2e500; // returns number Infinity 36 | bignumber('7.2e500'); // returns BigNumber 7.2e500 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [boolean](boolean.md), 43 | [complex](complex.md), 44 | [matrix](matrix.md), 45 | [string](string.md), 46 | [unit](unit.md) 47 | -------------------------------------------------------------------------------- /docs/functions/bitAnd.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function bitAnd 4 | 5 | Bitwise AND two values, `x & y`. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | bitAnd(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Array | Matrix | First value to and 20 | `y` | number | BigNumber | Array | Matrix | Second value to and 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Array | Matrix | AND of `x` and `y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | bitAnd(53, 131); // returns number 1 33 | 34 | bitAnd([1, 12, 31], 42); // returns Array [0, 8, 10] 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [bitNot](bitNot.md), 41 | [bitOr](bitOr.md), 42 | [bitXor](bitXor.md), 43 | [leftShift](leftShift.md), 44 | [rightArithShift](rightArithShift.md), 45 | [rightLogShift](rightLogShift.md) 46 | -------------------------------------------------------------------------------- /docs/functions/bitNot.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function bitNot 4 | 5 | Bitwise NOT value, `~x`. 6 | For matrices, the function is evaluated element wise. 7 | For units, the function is evaluated on the best prefix base. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | bitNot(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Array | Matrix | Value to not 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Array | Matrix | NOT of `x` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | bitNot(1); // returns number -2 33 | 34 | bitNot([2, -3, 4]); // returns Array [-3, 2, 5] 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [bitAnd](bitAnd.md), 41 | [bitOr](bitOr.md), 42 | [bitXor](bitXor.md), 43 | [leftShift](leftShift.md), 44 | [rightArithShift](rightArithShift.md), 45 | [rightLogShift](rightLogShift.md) 46 | -------------------------------------------------------------------------------- /docs/functions/bitOr.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function bitOr 4 | 5 | Bitwise OR two values, `x | y`. 6 | For matrices, the function is evaluated element wise. 7 | For units, the function is evaluated on the lowest print base. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | bitOr(x, y) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Array | Matrix | First value to or 21 | `y` | number | BigNumber | Array | Matrix | Second value to or 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Array | Matrix | OR of `x` and `y` 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | bitOr(1, 2); // returns number 3 34 | 35 | bitOr([1, 2, 3], 4); // returns Array [5, 6, 7] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [bitAnd](bitAnd.md), 42 | [bitNot](bitNot.md), 43 | [bitXor](bitXor.md), 44 | [leftShift](leftShift.md), 45 | [rightArithShift](rightArithShift.md), 46 | [rightLogShift](rightLogShift.md) 47 | -------------------------------------------------------------------------------- /docs/functions/bitXor.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function bitXor 4 | 5 | Bitwise XOR two values, `x ^ y`. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | bitXor(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Array | Matrix | First value to xor 20 | `y` | number | BigNumber | Array | Matrix | Second value to xor 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Array | Matrix | XOR of `x` and `y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | bitXor(1, 2); // returns number 3 33 | 34 | bitXor([2, 3, 4], 4); // returns Array [6, 7, 0] 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [bitAnd](bitAnd.md), 41 | [bitNot](bitNot.md), 42 | [bitOr](bitOr.md), 43 | [leftShift](leftShift.md), 44 | [rightArithShift](rightArithShift.md), 45 | [rightLogShift](rightLogShift.md) 46 | -------------------------------------------------------------------------------- /docs/functions/boolean.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function boolean 4 | 5 | Create a boolean or convert a string or number to a boolean. 6 | In case of a number, `true` is returned for non-zero numbers, and `false` in 7 | case of zero. 8 | Strings can be `'true'` or `'false'`, or can contain a number. 9 | When value is a matrix, all elements will be converted to boolean. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | boolean(x) 16 | ``` 17 | 18 | ### Parameters 19 | 20 | Parameter | Type | Description 21 | --------- | ---- | ----------- 22 | `value` | string | number | boolean | Array | Matrix | null | A value of any type 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | boolean | Array | Matrix | The boolean value 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | boolean(0); // returns false 35 | boolean(1); // returns true 36 | boolean(-3); // returns true 37 | boolean('true'); // returns true 38 | boolean('false'); // returns false 39 | boolean([1, 0, 1, 1]); // returns [true, false, true, true] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [bignumber](bignumber.md), 46 | [complex](complex.md), 47 | [matrix](matrix.md), 48 | [string](string.md), 49 | [unit](unit.md) 50 | -------------------------------------------------------------------------------- /docs/functions/catalan.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function catalan 4 | 5 | The Catalan Numbers enumerate combinatorial structures of many different types. 6 | catalan only takes integer arguments. 7 | The following condition must be enforced: n >= 0 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | catalan(n) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `n` | Number | BigNumber | nth Catalan number 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | Number | BigNumber | Cn(n) 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | catalan(3); // returns 5; 33 | catalan(8); // returns 1430; 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [bellNumbers](bellNumbers.md) 40 | -------------------------------------------------------------------------------- /docs/functions/cbrt.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function cbrt 4 | 5 | Calculate the cubic root of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | cbrt(x) 14 | cbrt(x, allRoots) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Value for which to calculate the cubic root. 22 | `allRoots` | boolean | Optional, false by default. Only applicable when `x` is a number or complex number. If true, all complex roots are returned, if false (default) the principal root is returned. 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | number | BigNumber | Complex | Unit | Array | Matrix | Returns the cubic root of `x` 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | cbrt(27); // returns 3 35 | cube(3); // returns 27 36 | cbrt(-64); // returns -4 37 | cbrt(unit('27 m^3')); // returns Unit 3 m 38 | cbrt([27, 64, 125]); // returns [3, 4, 5] 39 | 40 | var x = complex('8i'); 41 | cbrt(x); // returns Complex 1.7320508075689 + i 42 | cbrt(x, true); // returns Matrix [ 43 | // 1.7320508075689 + i 44 | // -1.7320508075689 + i 45 | // -2i 46 | // ] 47 | ``` 48 | 49 | 50 | ## See also 51 | 52 | [square](square.md), 53 | [sqrt](sqrt.md), 54 | [cube](cube.md) 55 | -------------------------------------------------------------------------------- /docs/functions/ceil.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function ceil 4 | 5 | Round a value towards plus infinity 6 | If `x` is complex, both real and imaginary part are rounded towards plus infinity. 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | ceil(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Number to be rounded 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Array | Matrix | Rounded value 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | ceil(3.2); // returns number 4 33 | ceil(3.8); // returns number 4 34 | ceil(-4.2); // returns number -4 35 | ceil(-4.7); // returns number -4 36 | 37 | var c = complex(3.2, -2.7); 38 | ceil(c); // returns Complex 4 - 2i 39 | 40 | ceil([3.2, 3.8, -4.7]); // returns Array [4, 4, -4] 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [floor](floor.md), 47 | [fix](fix.md), 48 | [round](round.md) 49 | -------------------------------------------------------------------------------- /docs/functions/chain.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function chain 4 | 5 | Wrap any value in a chain, allowing to perform chained operations on 6 | the value. 7 | 8 | All methods available in the js library can be called upon the chain, 9 | and then will be evaluated with the value itself as first argument. 10 | The chain can be closed by executing `chain.done()`, which returns 11 | the final value. 12 | 13 | The chain has a number of special functions: 14 | 15 | - `done()` Finalize the chain and return the chain's value. 16 | - `valueOf()` The same as `done()` 17 | - `toString()` Executes `format()` onto the chain's value, returning 18 | a string representation of the value. 19 | 20 | 21 | ## Syntax 22 | 23 | ```js 24 | chain(value) 25 | ``` 26 | 27 | ### Parameters 28 | 29 | Parameter | Type | Description 30 | --------- | ---- | ----------- 31 | `value` | * | A value of any type on which to start a chained operation. 32 | 33 | ### Returns 34 | 35 | Type | Description 36 | ---- | ----------- 37 | type.Chain | The created chain 38 | 39 | 40 | ## Examples 41 | 42 | ```js 43 | chain(3) 44 | .add(4) 45 | .subtract(2) 46 | .done(); // 5 47 | 48 | chain( [[1, 2], [3, 4]] ) 49 | .subset(index(0, 0), 8) 50 | .multiply(3) 51 | .done(); // [[24, 6], [9, 12]] 52 | ``` 53 | 54 | 55 | -------------------------------------------------------------------------------- /docs/functions/combinations.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function combinations 4 | 5 | Compute the number of ways of picking `k` unordered outcomes from `n` 6 | possibilities. 7 | 8 | Combinations only takes integer arguments. 9 | The following condition must be enforced: k <= n. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | combinations(n, k) 16 | ``` 17 | 18 | ### Parameters 19 | 20 | Parameter | Type | Description 21 | --------- | ---- | ----------- 22 | `n` | number | BigNumber | Total number of objects in the set 23 | `k` | number | BigNumber | Number of objects in the subset 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | number | BigNumber | Number of possible combinations. 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | combinations(7, 5); // returns 21 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [permutations](permutations.md), 42 | [factorial](factorial.md) 43 | -------------------------------------------------------------------------------- /docs/functions/compare.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function compare 4 | 5 | Compare two values. Returns 1 when x > y, -1 when x < y, and 0 when x == y. 6 | 7 | x and y are considered equal when the relative difference between x and y 8 | is smaller than the configured epsilon. The function cannot be used to 9 | compare values smaller than approximately 2.22e-16. 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | compare(x, y) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `x` | number | BigNumber | Fraction | Unit | string | Array | Matrix | First value to compare 25 | `y` | number | BigNumber | Fraction | Unit | string | Array | Matrix | Second value to compare 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | number | BigNumber | Fraction | Array | Matrix | Returns the result of the comparison: 1, 0 or -1. 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | compare(6, 1); // returns 1 38 | compare(2, 3); // returns -1 39 | compare(7, 7); // returns 0 40 | 41 | var a = unit('5 cm'); 42 | var b = unit('40 mm'); 43 | compare(a, b); // returns 1 44 | 45 | compare(2, [1, 2, 3]); // returns [1, 0, -1] 46 | ``` 47 | 48 | 49 | ## See also 50 | 51 | [equal](equal.md), 52 | [unequal](unequal.md), 53 | [smaller](smaller.md), 54 | [smallerEq](smallerEq.md), 55 | [larger](larger.md), 56 | [largerEq](largerEq.md) 57 | -------------------------------------------------------------------------------- /docs/functions/complex.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function complex 4 | 5 | Create a complex value or convert a value to a complex value. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | complex() // creates a complex value with zero 12 | // as real and imaginary part. 13 | complex(re : number, im : string) // creates a complex value with provided 14 | // values for real and imaginary part. 15 | complex(re : number) // creates a complex value with provided 16 | // real value and zero imaginary part. 17 | complex(complex : Complex) // clones the provided complex value. 18 | complex(arg : string) // parses a string into a complex value. 19 | complex(array : Array) // converts the elements of the array 20 | // or matrix element wise into a 21 | // complex value. 22 | complex({re: number, im: number}) // creates a complex value with provided 23 | // values for real an imaginary part. 24 | complex({r: number, phi: number}) // creates a complex value with provided 25 | // polar coordinates 26 | ``` 27 | 28 | ### Parameters 29 | 30 | Parameter | Type | Description 31 | --------- | ---- | ----------- 32 | `args` | * | Array | Matrix | Arguments specifying the real and imaginary part of the complex number 33 | 34 | ### Returns 35 | 36 | Type | Description 37 | ---- | ----------- 38 | Complex | Array | Matrix | Returns a complex value 39 | 40 | 41 | ## Examples 42 | 43 | ```js 44 | var a = complex(3, -4); // a = Complex 3 - 4i 45 | a.re = 5; // a = Complex 5 - 4i 46 | var i = a.im; // Number -4; 47 | var b = complex('2 + 6i'); // Complex 2 + 6i 48 | var c = complex(); // Complex 0 + 0i 49 | var d = add(a, b); // Complex 5 + 2i 50 | ``` 51 | 52 | 53 | ## See also 54 | 55 | [bignumber](bignumber.md), 56 | [boolean](boolean.md), 57 | [matrix](matrix.md), 58 | [number](number.md), 59 | [string](string.md), 60 | [unit](unit.md) 61 | -------------------------------------------------------------------------------- /docs/functions/composition.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function composition 4 | 5 | The composition counts of n into k parts. 6 | 7 | composition only takes integer arguments. 8 | The following condition must be enforced: k <= n. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | composition(n, k) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `n` | Number | BigNumber | Total number of objects in the set 22 | `k` | Number | BigNumber | Number of objects in the subset 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | Number | BigNumber | Returns the composition counts of n into k parts. 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | composition(5, 3); // returns 6 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [combinations](combinations.md) 41 | -------------------------------------------------------------------------------- /docs/functions/concat.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function concat 4 | 5 | Concatenate two or more matrices. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | concat(A, B, C, ...) 12 | concat(A, B, C, ..., dim) 13 | ``` 14 | 15 | ### Where 16 | 17 | - `dim: number` is a zero-based dimension over which to concatenate the matrices. 18 | By default the last dimension of the matrices. 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `args` | ... Array | Matrix | Two or more matrices 25 | 26 | ### Returns 27 | 28 | Type | Description 29 | ---- | ----------- 30 | Array | Matrix | Concatenated matrix 31 | 32 | 33 | ## Examples 34 | 35 | ```js 36 | var A = [[1, 2], [5, 6]]; 37 | var B = [[3, 4], [7, 8]]; 38 | 39 | concat(A, B); // returns [[1, 2, 3, 4], [5, 6, 7, 8]] 40 | concat(A, B, 0); // returns [[1, 2], [5, 6], [3, 4], [7, 8]] 41 | concat('hello', ' ', 'world'); // returns 'hello world' 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [size](size.md), 48 | [squeeze](squeeze.md), 49 | [subset](subset.md), 50 | [transpose](transpose.md) 51 | -------------------------------------------------------------------------------- /docs/functions/config.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function config 4 | 5 | Set configuration options for js, and get current options. 6 | Will emit a 'config' event, with arguments (curr, prev). 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | config(config: Object): Object 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `options` | Object | Available options: {number} epsilon Minimum relative difference between two compared values, used by all comparison functions. {string} matrix A string 'Matrix' (default) or 'Array'. {string} number A string 'number' (default), 'BigNumber', or 'Fraction' {number} precision The number of significant digits for BigNumbers. Not applicable for Numbers. {string} parenthesis How to display parentheses in LaTeX and string output. 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | Object | Returns the current configuration 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | config().number; // outputs 'number' 32 | eval('0.4'); // outputs number 0.4 33 | config({number: 'Fraction'}); 34 | eval('0.4'); // outputs Fraction 2/5 35 | ``` 36 | 37 | 38 | -------------------------------------------------------------------------------- /docs/functions/conj.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function conj 4 | 5 | Compute the complex conjugate of a complex value. 6 | If `x = a+bi`, the complex conjugate of `x` is `a - bi`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | conj(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Array | Matrix | A complex number or array with complex numbers 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Complex | Array | Matrix | The complex conjugate of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | conj(complex('2 + 3i')); // returns Complex 2 - 3i 34 | conj(complex('2 - 3i')); // returns Complex 2 + 3i 35 | conj(complex('-5.2i')); // returns Complex 5.2i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [re](re.md), 42 | [im](im.md), 43 | [arg](arg.md), 44 | [abs](abs.md) 45 | -------------------------------------------------------------------------------- /docs/functions/cos.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function cos 4 | 5 | Calculate the cosine of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | cos(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | Cosine of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | cos(2); // returns number -0.4161468365471422 33 | cos(pi / 4); // returns number 0.7071067811865475 34 | cos(unit(180, 'deg')); // returns number -1 35 | cos(unit(60, 'deg')); // returns number 0.5 36 | 37 | var angle = 0.2; 38 | pow(sin(angle), 2) + pow(cos(angle), 2); // returns number ~1 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [cos](cos.md), 45 | [tan](tan.md) 46 | -------------------------------------------------------------------------------- /docs/functions/cosh.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function cosh 4 | 5 | Calculate the hyperbolic cosine of a value, 6 | defined as `cosh(x) = 1/2 * (exp(x) + exp(-x))`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | cosh(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Complex | Array | Matrix | Hyperbolic cosine of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | cosh(0.5); // returns number 1.1276259652063807 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [sinh](sinh.md), 40 | [tanh](tanh.md) 41 | -------------------------------------------------------------------------------- /docs/functions/cot.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function cot 4 | 5 | Calculate the cotangent of a value. Defined as `cot(x) = 1 / tan(x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | cot(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Complex | Unit | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | Complex | Array | Matrix | Cotangent of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | cot(2); // returns number -0.45765755436028577 33 | 1 / tan(2); // returns number -0.45765755436028577 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [tan](tan.md), 40 | [sec](sec.md), 41 | [csc](csc.md) 42 | -------------------------------------------------------------------------------- /docs/functions/coth.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function coth 4 | 5 | Calculate the hyperbolic cotangent of a value, 6 | defined as `coth(x) = 1 / tanh(x)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | coth(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic cotangent of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | // coth(x) = 1 / tanh(x) 34 | coth(2); // returns 1.0373147207275482 35 | 1 / tanh(2); // returns 1.0373147207275482 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [sinh](sinh.md), 42 | [tanh](tanh.md), 43 | [cosh](cosh.md) 44 | -------------------------------------------------------------------------------- /docs/functions/createUnit.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function createUnit 4 | 5 | Create a user-defined unit and register it with the Unit type. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | createUnit({ 12 | baseUnit1: { 13 | aliases: [string, ...] 14 | prefixes: object 15 | }, 16 | unit2: { 17 | definition: string, 18 | aliases: [string, ...] 19 | prefixes: object, 20 | offset: number 21 | }, 22 | unit3: string // Shortcut 23 | }) 24 | ``` 25 | 26 | ### Parameters 27 | 28 | Parameter | Type | Description 29 | --------- | ---- | ----------- 30 | `name` | string | The name of the new unit. Must be unique. Example: 'knot' 31 | `definition` | string, Unit | Definition of the unit in terms of existing units. For example, '0.514444444 m / s'. 32 | `options` | Object | (optional) An object containing any of the following properties: 33 | 34 | ### Returns 35 | 36 | Type | Description 37 | ---- | ----------- 38 | Unit | The new unit 39 | 40 | 41 | ## Examples 42 | 43 | ```js 44 | createUnit('foo'); 45 | createUnit('knot', {definition: '0.514444444 m/s', aliases: ['knots', 'kt', 'kts]}); 46 | createUnit('mph', '1 mile/hour'); 47 | ``` 48 | 49 | 50 | ## See also 51 | 52 | [unit](unit.md) 53 | -------------------------------------------------------------------------------- /docs/functions/cross.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function cross 4 | 5 | Calculate the cross product for two vectors in three dimensional space. 6 | The cross product of `A = [a1, a2, a3]` and `B =[b1, b2, b3]` is defined 7 | as: 8 | 9 | cross(A, B) = [ 10 | a2 * b3 - a3 * b2, 11 | a3 * b1 - a1 * b3, 12 | a1 * b2 - a2 * b1 13 | ] 14 | 15 | 16 | ## Syntax 17 | 18 | ```js 19 | cross(x, y) 20 | ``` 21 | 22 | ### Parameters 23 | 24 | Parameter | Type | Description 25 | --------- | ---- | ----------- 26 | `x` | Array | Matrix | First vector 27 | `y` | Array | Matrix | Second vector 28 | 29 | ### Returns 30 | 31 | Type | Description 32 | ---- | ----------- 33 | Array | Matrix | Returns the cross product of `x` and `y` 34 | 35 | 36 | ## Examples 37 | 38 | ```js 39 | cross([1, 1, 0], [0, 1, 1]); // Returns [1, -1, 1] 40 | cross([3, -3, 1], [4, 9, 2]); // Returns [-15, -2, 39] 41 | cross([2, 3, 4], [5, 6, 7]); // Returns [-3, 6, -3] 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [dot](dot.md), 48 | [multiply](multiply.md) 49 | -------------------------------------------------------------------------------- /docs/functions/csc.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function csc 4 | 5 | Calculate the cosecant of a value, defined as `csc(x) = 1/sin(x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | csc(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Complex | Unit | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | Complex | Array | Matrix | Cosecant of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | csc(2); // returns number 1.099750170294617 33 | 1 / sin(2); // returns number 1.099750170294617 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [sin](sin.md), 40 | [sec](sec.md), 41 | [cot](cot.md) 42 | -------------------------------------------------------------------------------- /docs/functions/csch.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function csch 4 | 5 | Calculate the hyperbolic cosecant of a value, 6 | defined as `csch(x) = 1 / sinh(x)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | csch(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic cosecant of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | // csch(x) = 1/ sinh(x) 34 | csch(0.5); // returns 1.9190347513349437 35 | 1 / sinh(0.5); // returns 1.9190347513349437 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [sinh](sinh.md), 42 | [sech](sech.md), 43 | [coth](coth.md) 44 | -------------------------------------------------------------------------------- /docs/functions/cube.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function cube 4 | 5 | Compute the cube of a value, `x * x * x`. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | cube(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | Number for which to calculate the cube 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | Cube of x 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | cube(2); // returns number 8 32 | pow(2, 3); // returns number 8 33 | cube(4); // returns number 64 34 | 4 * 4 * 4; // returns number 64 35 | 36 | cube([1, 2, 3, 4]); // returns Array [1, 8, 27, 64] 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [multiply](multiply.md), 43 | [square](square.md), 44 | [pow](pow.md), 45 | [cbrt](cbrt.md) 46 | -------------------------------------------------------------------------------- /docs/functions/deepEqual.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function deepEqual 4 | 5 | Test element wise whether two matrices are equal. 6 | The function accepts both matrices and scalar values. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | deepEqual(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | First matrix to compare 20 | `y` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Second matrix to compare 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Returns true when the input matrices have the same size and each of their elements is equal. 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | deepEqual(2, 4); // returns false 33 | 34 | a = [2, 5, 1]; 35 | b = [2, 7, 1]; 36 | 37 | deepEqual(a, b); // returns false 38 | equal(a, b); // returns [true, false, true] 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [equal](equal.md), 45 | [unequal](unequal.md) 46 | -------------------------------------------------------------------------------- /docs/functions/det.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function det 4 | 5 | Calculate the determinant of a matrix. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | det(x) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | Array | Matrix | A matrix 19 | 20 | ### Returns 21 | 22 | Type | Description 23 | ---- | ----------- 24 | number | The determinant of `x` 25 | 26 | 27 | ## Examples 28 | 29 | ```js 30 | det([[1, 2], [3, 4]]); // returns -2 31 | 32 | var A = [ 33 | [-2, 2, 3], 34 | [-1, 1, 3], 35 | [2, 0, -1] 36 | ] 37 | det(A); // returns 6 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [inv](inv.md) 44 | -------------------------------------------------------------------------------- /docs/functions/diag.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function diag 4 | 5 | Create a diagonal matrix or retrieve the diagonal of a matrix 6 | 7 | When `x` is a vector, a matrix with vector `x` on the diagonal will be returned. 8 | When `x` is a two dimensional matrix, the matrixes `k`th diagonal will be returned as vector. 9 | When k is positive, the values are placed on the super diagonal. 10 | When k is negative, the values are placed on the sub diagonal. 11 | 12 | 13 | ## Syntax 14 | 15 | ```js 16 | diag(X) 17 | diag(X, format) 18 | diag(X, k) 19 | diag(X, k, format) 20 | ``` 21 | 22 | ### Parameters 23 | 24 | Parameter | Type | Description 25 | --------- | ---- | ----------- 26 | `x` | Matrix | Array | A two dimensional matrix or a vector 27 | `k` | number | BigNumber | The diagonal where the vector will be filled in or retrieved. Default value: 0. 28 | `format` | string | The matrix storage format. Default value: 'dense'. 29 | 30 | ### Returns 31 | 32 | Type | Description 33 | ---- | ----------- 34 | Matrix | Array | Diagonal matrix from input vector, or diagonal from input matrix. 35 | 36 | 37 | ## Examples 38 | 39 | ```js 40 | // create a diagonal matrix 41 | diag([1, 2, 3]); // returns [[1, 0, 0], [0, 2, 0], [0, 0, 3]] 42 | diag([1, 2, 3], 1); // returns [[0, 1, 0, 0], [0, 0, 2, 0], [0, 0, 0, 3]] 43 | diag([1, 2, 3], -1); // returns [[0, 0, 0], [1, 0, 0], [0, 2, 0], [0, 0, 3]] 44 | 45 | // retrieve the diagonal from a matrix 46 | var a = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; 47 | diag(a); // returns [1, 5, 9] 48 | ``` 49 | 50 | 51 | ## See also 52 | 53 | [ones](ones.md), 54 | [zeros](zeros.md), 55 | [eye](eye.md) 56 | -------------------------------------------------------------------------------- /docs/functions/distance.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function distance 4 | 5 | Calculates: 6 | The eucledian distance between two points in 2 and 3 dimensional spaces. 7 | Distance between point and a line in 2 and 3 dimensional spaces. 8 | Pairwise distance between a set of 2D or 3D points 9 | NOTE: 10 | When substituting coefficients of a line(a, b and c), use ax + by + c = 0 instead of ax + by = c 11 | For parametric equation of a 3D line, x0, y0, z0, a, b, c are from: (x−x0, y−y0, z−z0) = t(a, b, c) 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | distance([x1, y1], [x2, y2]) 18 | distance({pointOneX: 4, pointOneY: 5}, {pointTwoX: 2, pointTwoY: 7}) 19 | distance([x1, y1, z1], [x2, y2, z2]) 20 | distance({pointOneX: 4, pointOneY: 5, pointOneZ: 8}, {pointTwoX: 2, pointTwoY: 7, pointTwoZ: 9}) 21 | distance([[A], [B], [C]...]) 22 | distance([x1, y1], [LinePtX1, LinePtY1], [LinePtX2, LinePtY2]) 23 | distance({pointX: 1, pointY: 4}, {lineOnePtX: 6, lineOnePtY: 3}, {lineTwoPtX: 2, lineTwoPtY: 8}) 24 | distance([x1, y1, z1], [LinePtX1, LinePtY1, LinePtZ1], [LinePtX2, LinePtY2, LinePtZ2]) 25 | distance({pointX: 1, pointY: 4, pointZ: 7}, {lineOnePtX: 6, lineOnePtY: 3, lineOnePtZ: 4}, {lineTwoPtX: 2, lineTwoPtY: 8, lineTwoPtZ: 5}) 26 | distance([x1, y1], [xCoeffLine, yCoeffLine, constant]) 27 | distance({pointX: 10, pointY: 10}, {xCoeffLine: 8, yCoeffLine: 1, constant: 3}) 28 | distance([x1, y1, z1], [x0, y0, z0, a-tCoeff, b-tCoeff, c-tCoeff]) point and parametric equation of 3D line 29 | distance([x, y, z], [x0, y0, z0, a, b, c]) 30 | distance({pointX: 2, pointY: 5, pointZ: 9}, {x0: 4, y0: 6, z0: 3, a: 4, b: 2, c: 0}) 31 | ``` 32 | 33 | ### Parameters 34 | 35 | Parameter | Type | Description 36 | --------- | ---- | ----------- 37 | `x` | Array | Matrix | Object | Co-ordinates of first point 38 | `y` | Array | Matrix | Object | Co-ordinates of second point 39 | 40 | ### Returns 41 | 42 | Type | Description 43 | ---- | ----------- 44 | Number | BigNumber | Returns the distance from two/three points 45 | 46 | 47 | ## Examples 48 | 49 | ```js 50 | distance([0,0], [4,4]) // Returns 5.6569 51 | distance( 52 | {pointOneX: 0, pointOneY: 0}, 53 | {pointTwoX: 10, pointTwoY: 10}) // Returns 14.142135623730951 54 | distance([1, 0, 1], [4, -2, 2]) // Returns 3.74166 55 | distance( 56 | {pointOneX: 4, pointOneY: 5, pointOneZ: 8}, 57 | {pointTwoX: 2, pointTwoY: 7, pointTwoZ: 9}) // Returns 3 58 | distance([[1, 2], [1, 2], [1, 3]]) // Returns [0, 1, 1] 59 | distance([[1,2,4], [1,2,6], [8,1,3]]) // Returns [2, 7.14142842854285, 7.681145747868608] 60 | distance([10, 10], [8, 1, 3]) // Returns 11.535230316796387 61 | distance([10, 10], [2, 3], [-8, 0]) // Returns 8.759953130362847 62 | distance( 63 | {pointX: 1, pointY: 4}, 64 | {lineOnePtX: 6, lineOnePtY: 3}, 65 | {lineTwoPtX: 2, lineTwoPtY: 8}) // Returns 2.720549372624744 66 | distance([2, 3, 1], [1, 1, 2, 5, 0, 1]) // Returns 2.3204774044612857 67 | distance( 68 | {pointX: 2, pointY: 3, pointZ: 1}, 69 | {x0: 1, y0: 1, z0: 2, a: 5, b: 0, c: 1} // Returns 2.3204774044612857 70 | ``` 71 | 72 | 73 | -------------------------------------------------------------------------------- /docs/functions/divide.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function divide 4 | 5 | Divide two values, `x / y`. 6 | To divide matrices, `x` is multiplied with the inverse of `y`: `x * inv(y)`. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | divide(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Numerator 20 | `y` | number | BigNumber | Fraction | Complex | Array | Matrix | Denominator 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Quotient, `x / y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | divide(2, 3); // returns number 0.6666666666666666 33 | 34 | var a = complex(5, 14); 35 | var b = complex(4, 1); 36 | divide(a, b); // returns Complex 2 + 3i 37 | 38 | var c = [[7, -6], [13, -4]]; 39 | var d = [[1, 2], [4, 3]]; 40 | divide(c, d); // returns Array [[-9, 4], [-11, 6]] 41 | 42 | var e = unit('18 km'); 43 | divide(e, 4.5); // returns Unit 4 km 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [multiply](multiply.md) 50 | -------------------------------------------------------------------------------- /docs/functions/dot.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function dot 4 | 5 | Calculate the dot product of two vectors. The dot product of 6 | `A = [a1, a2, a3, ..., an]` and `B = [b1, b2, b3, ..., bn]` is defined as: 7 | 8 | dot(A, B) = a1 * b1 + a2 * b2 + a3 * b3 + ... + an * bn 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | dot(x, y) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | Array | Matrix | First vector 22 | `y` | Array | Matrix | Second vector 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | number | Returns the dot product of `x` and `y` 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | dot([2, 4, 1], [2, 2, 3]); // returns number 15 35 | multiply([2, 4, 1], [2, 2, 3]); // returns number 15 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [multiply](multiply.md), 42 | [cross](cross.md) 43 | -------------------------------------------------------------------------------- /docs/functions/dotDivide.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function dotDivide 4 | 5 | Divide two matrices element wise. The function accepts both matrices and 6 | scalar values. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | dotDivide(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Numerator 20 | `y` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Denominator 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Quotient, `x ./ y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | dotDivide(2, 4); // returns 0.5 33 | 34 | a = [[9, 5], [6, 1]]; 35 | b = [[3, 2], [5, 2]]; 36 | 37 | dotDivide(a, b); // returns [[3, 2.5], [1.2, 0.5]] 38 | divide(a, b); // returns [[1.75, 0.75], [-1.75, 2.25]] 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [divide](divide.md), 45 | [multiply](multiply.md), 46 | [dotMultiply](dotMultiply.md) 47 | -------------------------------------------------------------------------------- /docs/functions/dotMultiply.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function dotMultiply 4 | 5 | Multiply two matrices element wise. The function accepts both matrices and 6 | scalar values. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | dotMultiply(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Left hand value 20 | `y` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Right hand value 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Multiplication of `x` and `y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | dotMultiply(2, 4); // returns 8 33 | 34 | a = [[9, 5], [6, 1]]; 35 | b = [[3, 2], [5, 2]]; 36 | 37 | dotMultiply(a, b); // returns [[27, 10], [30, 2]] 38 | multiply(a, b); // returns [[52, 28], [23, 14]] 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [multiply](multiply.md), 45 | [divide](divide.md), 46 | [dotDivide](dotDivide.md) 47 | -------------------------------------------------------------------------------- /docs/functions/dotPow.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function dotPow 4 | 5 | Calculates the power of x to y element wise. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | dotPow(x, y) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | The base 19 | `y` | number | BigNumber | Complex | Unit | Array | Matrix | The exponent 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Complex | Unit | Array | Matrix | The value of `x` to the power `y` 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | dotPow(2, 3); // returns number 8 32 | 33 | var a = [[1, 2], [4, 3]]; 34 | dotPow(a, 2); // returns Array [[1, 4], [16, 9]] 35 | pow(a, 2); // returns Array [[9, 8], [16, 17]] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [pow](pow.md), 42 | [sqrt](sqrt.md), 43 | [multiply](multiply.md) 44 | -------------------------------------------------------------------------------- /docs/functions/equal.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function equal 4 | 5 | Test whether two values are equal. 6 | 7 | The function tests whether the relative difference between x and y is 8 | smaller than the configured epsilon. The function cannot be used to 9 | compare values smaller than approximately 2.22e-16. 10 | 11 | For matrices, the function is evaluated element wise. 12 | In case of complex numbers, x.re must equal y.re, and x.im must equal y.im. 13 | 14 | Values `null` and `undefined` are compared strictly, thus `null` is only 15 | equal to `null` and nothing else, and `undefined` is only equal to 16 | `undefined` and nothing else. 17 | 18 | 19 | ## Syntax 20 | 21 | ```js 22 | equal(x, y) 23 | ``` 24 | 25 | ### Parameters 26 | 27 | Parameter | Type | Description 28 | --------- | ---- | ----------- 29 | `x` | number | BigNumber | boolean | Complex | Unit | string | Array | Matrix | First value to compare 30 | `y` | number | BigNumber | boolean | Complex | Unit | string | Array | Matrix | Second value to compare 31 | 32 | ### Returns 33 | 34 | Type | Description 35 | ---- | ----------- 36 | boolean | Array | Matrix | Returns true when the compared values are equal, else returns false 37 | 38 | 39 | ## Examples 40 | 41 | ```js 42 | equal(2 + 2, 3); // returns false 43 | equal(2 + 2, 4); // returns true 44 | 45 | var a = unit('50 cm'); 46 | var b = unit('5 m'); 47 | equal(a, b); // returns true 48 | 49 | var c = [2, 5, 1]; 50 | var d = [2, 7, 1]; 51 | 52 | equal(c, d); // returns [true, false, true] 53 | deepEqual(c, d); // returns false 54 | 55 | equal(0, null); // returns false 56 | ``` 57 | 58 | 59 | ## See also 60 | 61 | [unequal](unequal.md), 62 | [smaller](smaller.md), 63 | [smallerEq](smallerEq.md), 64 | [larger](larger.md), 65 | [largerEq](largerEq.md), 66 | [compare](compare.md), 67 | [deepEqual](deepEqual.md) 68 | -------------------------------------------------------------------------------- /docs/functions/exp.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function exp 4 | 5 | Calculate the exponent of a value. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | exp(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Complex | Array | Matrix | A number or matrix to exponentiate 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Complex | Array | Matrix | Exponent of `x` 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | exp(2); // returns number 7.3890560989306495 32 | pow(e, 2); // returns number 7.3890560989306495 33 | log(exp(2)); // returns number 2 34 | 35 | exp([1, 2, 3]); 36 | // returns Array [ 37 | // 2.718281828459045, 38 | // 7.3890560989306495, 39 | // 20.085536923187668 40 | // ] 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [log](log.md), 47 | [pow](pow.md) 48 | -------------------------------------------------------------------------------- /docs/functions/eye.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function eye 4 | 5 | Create a 2-dimensional identity matrix with size m x n or n x n. 6 | The matrix has ones on the diagonal and zeros elsewhere. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | eye(n) 13 | eye(n, format) 14 | eye(m, n) 15 | eye(m, n, format) 16 | eye([m, n]) 17 | eye([m, n], format) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `size` | ...number | Matrix | Array | The size for the matrix 25 | `format` | string | The Matrix storage format 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | Matrix | Array | number | A matrix with ones on the diagonal. 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | eye(3); // returns [[1, 0, 0], [0, 1, 0], [0, 0, 1]] 38 | eye(3, 2); // returns [[1, 0], [0, 1], [0, 0]] 39 | 40 | var A = [[1, 2, 3], [4, 5, 6]]; 41 | eye(size(A)); // returns [[1, 0, 0], [0, 1, 0]] 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [diag](diag.md), 48 | [ones](ones.md), 49 | [zeros](zeros.md), 50 | [size](size.md), 51 | [range](range.md) 52 | -------------------------------------------------------------------------------- /docs/functions/factorial.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function factorial 4 | 5 | Compute the factorial of a value 6 | 7 | Factorial only supports an integer value as argument. 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | factorial(n) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `n` | number | BigNumber | Array | Matrix | An integer number 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Array | Matrix | The factorial of `n` 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | factorial(5); // returns 120 34 | factorial(3); // returns 6 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [combinations](combinations.md), 41 | [gamma](gamma.md), 42 | [permutations](permutations.md) 43 | -------------------------------------------------------------------------------- /docs/functions/filter.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function filter 4 | 5 | Filter the items in an array or one dimensional matrix. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | filter(x, test) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | Matrix | Array | A one dimensional matrix or array to filter 19 | `test` | Function | RegExp | A function or regular expression to test items. All entries for which `test` returns true are returned. When `test` is a function, it is invoked with three parameters: the value of the element, the index of the element, and the matrix/array being traversed. The function must return a boolean. 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | Matrix | Array | Returns the filtered matrix. 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | function isPositive (x) { 32 | return x > 0; 33 | } 34 | filter([6, -2, -1, 4, 3], isPositive); // returns [6, 4, 3] 35 | 36 | filter(["23", "foo", "100", "55", "bar"], /[0-9]+/); // returns ["23", "100", "55"] 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [sort](sort.md) 43 | -------------------------------------------------------------------------------- /docs/functions/fix.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function fix 4 | 5 | Round a value towards zero. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | fix(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Number to be rounded 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Fraction | Complex | Array | Matrix | Rounded value 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | fix(3.2); // returns number 3 32 | fix(3.8); // returns number 3 33 | fix(-4.2); // returns number -4 34 | fix(-4.7); // returns number -4 35 | 36 | var c = complex(3.2, -2.7); 37 | fix(c); // returns Complex 3 - 2i 38 | 39 | fix([3.2, 3.8, -4.7]); // returns Array [3, 3, -4] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [ceil](ceil.md), 46 | [floor](floor.md), 47 | [round](round.md) 48 | -------------------------------------------------------------------------------- /docs/functions/flatten.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function flatten 4 | 5 | Flatten a multi dimensional matrix into a single dimensional matrix. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | flatten(x) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | Matrix | Array | Matrix to be flattened 19 | 20 | ### Returns 21 | 22 | Type | Description 23 | ---- | ----------- 24 | Matrix | Array | Returns the flattened matrix 25 | 26 | 27 | ## Examples 28 | 29 | ```js 30 | flatten([[1,2], [3,4]]); // returns [1, 2, 3, 4] 31 | ``` 32 | 33 | 34 | ## See also 35 | 36 | [concat](concat.md), 37 | [resize](resize.md), 38 | [size](size.md), 39 | [squeeze](squeeze.md) 40 | -------------------------------------------------------------------------------- /docs/functions/floor.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function floor 4 | 5 | Round a value towards minus infinity. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | floor(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Number to be rounded 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Fraction | Complex | Array | Matrix | Rounded value 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | floor(3.2); // returns number 3 32 | floor(3.8); // returns number 3 33 | floor(-4.2); // returns number -5 34 | floor(-4.7); // returns number -5 35 | 36 | var c = complex(3.2, -2.7); 37 | floor(c); // returns Complex 3 - 3i 38 | 39 | floor([3.2, 3.8, -4.7]); // returns Array [3, 3, -5] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [ceil](ceil.md), 46 | [fix](fix.md), 47 | [round](round.md) 48 | -------------------------------------------------------------------------------- /docs/functions/fraction.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function fraction 4 | 5 | Create a fraction convert a value to a fraction. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | fraction(numerator, denominator) 12 | fraction({n: numerator, d: denominator}) 13 | fraction(matrix: Array | Matrix) Turn all matrix entries 14 | into fractions 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `args` | number | string | Fraction | BigNumber | Array | Matrix | Arguments specifying the numerator and denominator of the fraction 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | Fraction | Array | Matrix | Returns a fraction 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | fraction(1, 3); 34 | fraction('2/3'); 35 | fraction({n: 2, d: 3}); 36 | fraction([0.2, 0.25, 1.25]); 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [bignumber](bignumber.md), 43 | [number](number.md), 44 | [string](string.md), 45 | [unit](unit.md) 46 | -------------------------------------------------------------------------------- /docs/functions/gamma.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function gamma 4 | 5 | Compute the gamma function of a value using Lanczos approximation for 6 | small values, and an extended Stirling approximation for large values. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | gamma(n) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `n` | number | Array | Matrix | A real or complex number 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Array | Matrix | The gamma of `n` 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | gamma(5); // returns 24 34 | gamma(-0.5); // returns -3.5449077018110335 35 | gamma(i); // returns -0.15494982830180973 - 0.49801566811835596i 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [combinations](combinations.md), 42 | [factorial](factorial.md), 43 | [permutations](permutations.md) 44 | -------------------------------------------------------------------------------- /docs/functions/gcd.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function gcd 4 | 5 | Calculate the greatest common divisor for two or more values or arrays. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | gcd(a, b) 14 | gcd(a, b, c, ...) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `args` | ... number | BigNumber | Fraction | Array | Matrix | Two or more integer numbers 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Fraction | Array | Matrix | The greatest common divisor 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | gcd(8, 12); // returns 4 34 | gcd(-4, 6); // returns 2 35 | gcd(25, 15, -10); // returns 5 36 | 37 | gcd([8, -4], [12, 6]); // returns [4, 2] 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [lcm](lcm.md), 44 | [xgcd](xgcd.md) 45 | -------------------------------------------------------------------------------- /docs/functions/hypot.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function hypot 4 | 5 | Calculate the hypotenusa of a list with values. The hypotenusa is defined as: 6 | 7 | hypot(a, b, c, ...) = sqrt(a^2 + b^2 + c^2 + ...) 8 | 9 | For matrix input, the hypotenusa is calculated for all values in the matrix. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | hypot(a, b, ...) 16 | hypot([a, b, c, ...]) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `args` | ... number | BigNumber | 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | number | BigNumber | Returns the hypothenusa of the input values. 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | hypot(3, 4); // 5 36 | hypot(3, 4, 5); // 7.0710678118654755 37 | hypot([3, 4, 5]); // 7.0710678118654755 38 | hypot(-2); // 2 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [abs](abs.md), 45 | [norm](norm.md) 46 | -------------------------------------------------------------------------------- /docs/functions/im.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function im 4 | 5 | Get the imaginary part of a complex number. 6 | For a complex number `a + bi`, the function returns `b`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | im(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Array | Matrix | A complex number or array with complex numbers 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Array | Matrix | The imaginary part of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var a = complex(2, 3); 34 | re(a); // returns number 2 35 | im(a); // returns number 3 36 | 37 | re(complex('-5.2i')); // returns number -5.2 38 | re(complex(2.4)); // returns number 0 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [re](re.md), 45 | [conj](conj.md), 46 | [abs](abs.md), 47 | [arg](arg.md) 48 | -------------------------------------------------------------------------------- /docs/functions/intersect.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function intersect 4 | 5 | Calculates the point of intersection of two lines in two or three dimensions 6 | and of a line and a plane in three dimensions. The inputs are in the form of 7 | arrays or 1 dimensional matrices. The line intersection functions return null 8 | if the lines do not meet. 9 | 10 | Note: Fill the plane coefficients as `x + y + z = c` and not as `x + y + z + c = 0`. 11 | 12 | 13 | ## Syntax 14 | 15 | ```js 16 | intersect(endPoint1Line1, endPoint2Line1, endPoint1Line2, endPoint2Line2) 17 | intersect(endPoint1, endPoint2, planeCoefficients) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `w` | Array | Matrix | Co-ordinates of first end-point of first line 25 | `x` | Array | Matrix | Co-ordinates of second end-point of first line 26 | `y` | Array | Matrix | Co-ordinates of first end-point of second line OR Co-efficients of the plane's equation 27 | `z` | Array | Matrix | Co-ordinates of second end-point of second line OR null if the calculation is for line and plane 28 | 29 | ### Returns 30 | 31 | Type | Description 32 | ---- | ----------- 33 | Array | Returns the point of intersection of lines/lines-planes 34 | 35 | 36 | ## Examples 37 | 38 | ```js 39 | intersect([0, 0], [10, 10], [10, 0], [0, 10]); // Returns [5, 5] 40 | intersect([0, 0, 0], [10, 10, 0], [10, 0, 0], [0, 10, 0]); // Returns [5, 5, 0] 41 | intersect([1, 0, 1], [4, -2, 2], [1, 1, 1, 6]); // Returns [7, -4, 3] 42 | ``` 43 | 44 | 45 | -------------------------------------------------------------------------------- /docs/functions/inv.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function inv 4 | 5 | Calculate the inverse of a square matrix. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | inv(x) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | number | Complex | Array | Matrix | Matrix to be inversed 19 | 20 | ### Returns 21 | 22 | Type | Description 23 | ---- | ----------- 24 | number | Complex | Array | Matrix | The inverse of `x`. 25 | 26 | 27 | ## Examples 28 | 29 | ```js 30 | inv([[1, 2], [3, 4]]); // returns [[-2, 1], [1.5, -0.5]] 31 | inv(4); // returns 0.25 32 | 1 / 4; // returns 0.25 33 | ``` 34 | 35 | 36 | ## See also 37 | 38 | [det](det.md), 39 | [transpose](transpose.md) 40 | -------------------------------------------------------------------------------- /docs/functions/isInteger.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isInteger 4 | 5 | Test whether a value is an integer number. 6 | The function supports `number`, `BigNumber`, and `Fraction`. 7 | 8 | The function is evaluated element-wise in case of Array or Matrix input. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | isInteger(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Fraction | Array | Matrix | Value to be tested 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | boolean | Returns true when `x` contains a numeric, integer value. Throws an error in case of an unknown data type. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | isInteger(2); // returns true 34 | isInteger(0); // returns true 35 | isInteger(0.5); // returns false 36 | isInteger(bignumber(500)); // returns true 37 | isInteger(fraction(4)); // returns true 38 | isInteger('3'); // returns true 39 | isInteger([3, 0.5, -2]); // returns [true, false, true] 40 | isInteger(complex('2-4i'); // throws an error 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [isNumeric](isNumeric.md), 47 | [isPositive](isPositive.md), 48 | [isNegative](isNegative.md), 49 | [isZero](isZero.md) 50 | -------------------------------------------------------------------------------- /docs/functions/isNaN.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isNaN 4 | 5 | Test whether a value is NaN (not a number). 6 | The function supports types `number`, `BigNumber`, `Fraction`, `Unit` and `Complex`. 7 | 8 | The function is evaluated element-wise in case of Array or Matrix input. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | isNaN(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Fraction | Unit | Array | Matrix | Value to be tested 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | boolean | Returns true when `x` is NaN. Throws an error in case of an unknown data type. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | isNaN(3); // returns false 34 | isNaN(NaN); // returns true 35 | isNaN(0); // returns false 36 | isNaN(bignumber(NaN)); // returns true 37 | isNaN(bignumber(0)); // returns false 38 | isNaN(fraction(-2, 5)); // returns false 39 | isNaN('-2'); // returns false 40 | isNaN([2, 0, -3, NaN]'); // returns [false, false, false, true] 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [isNumeric](isNumeric.md), 47 | [isNegative](isNegative.md), 48 | [isPositive](isPositive.md), 49 | [isZero](isZero.md), 50 | [isInteger](isInteger.md) 51 | -------------------------------------------------------------------------------- /docs/functions/isNegative.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isNegative 4 | 5 | Test whether a value is negative: smaller than zero. 6 | The function supports types `number`, `BigNumber`, `Fraction`, and `Unit`. 7 | 8 | The function is evaluated element-wise in case of Array or Matrix input. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | isNegative(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Fraction | Unit | Array | Matrix | Value to be tested 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | boolean | Returns true when `x` is larger than zero. Throws an error in case of an unknown data type. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | isNegative(3); // returns false 34 | isNegative(-2); // returns true 35 | isNegative(0); // returns false 36 | isNegative(-0); // returns false 37 | isNegative(bignumber(2)); // returns false 38 | isNegative(fraction(-2, 5)); // returns true 39 | isNegative('-2'); // returns true 40 | isNegative([2, 0, -3]'); // returns [false, false, true] 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [isNumeric](isNumeric.md), 47 | [isPositive](isPositive.md), 48 | [isZero](isZero.md), 49 | [isInteger](isInteger.md) 50 | -------------------------------------------------------------------------------- /docs/functions/isNumeric.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isNumeric 4 | 5 | Test whether a value is an numeric value. 6 | 7 | The function is evaluated element-wise in case of Array or Matrix input. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | isNumeric(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | * | Value to be tested 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | boolean | Returns true when `x` is a `number`, `BigNumber`, `Fraction`, or `boolean`. Returns false for other types. Throws an error in case of unknown types. 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | isNumeric(2); // returns true 33 | isNumeric(0); // returns true 34 | isNumeric(bignumber(500)); // returns true 35 | isNumeric(fraction(4)); // returns true 36 | isNumeric(complex('2-4i'); // returns false 37 | isNumeric('3'); // returns false 38 | isNumeric([2.3, 'foo', false]); // returns [true, false, true] 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [isZero](isZero.md), 45 | [isPositive](isPositive.md), 46 | [isNegative](isNegative.md), 47 | [isInteger](isInteger.md) 48 | -------------------------------------------------------------------------------- /docs/functions/isPositive.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isPositive 4 | 5 | Test whether a value is positive: larger than zero. 6 | The function supports types `number`, `BigNumber`, `Fraction`, and `Unit`. 7 | 8 | The function is evaluated element-wise in case of Array or Matrix input. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | isPositive(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Fraction | Unit | Array | Matrix | Value to be tested 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | boolean | Returns true when `x` is larger than zero. Throws an error in case of an unknown data type. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | isPositive(3); // returns true 34 | isPositive(-2); // returns false 35 | isPositive(0); // returns false 36 | isPositive(-0); // returns false 37 | isPositive(0.5); // returns true 38 | isPositive(bignumber(2)); // returns true 39 | isPositive(fraction(-2, 5)); // returns false 40 | isPositive(fraction(1,3)); // returns false 41 | isPositive('2'); // returns true 42 | isPositive([2, 0, -3]'); // returns [true, false, false] 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [isNumeric](isNumeric.md), 49 | [isZero](isZero.md), 50 | [isNegative](isNegative.md), 51 | [isInteger](isInteger.md) 52 | -------------------------------------------------------------------------------- /docs/functions/isPrime.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isPrime 4 | 5 | Test whether a value is prime: has no divisors other than itself and one. 6 | The function supports type `number`, `bignumber`. 7 | 8 | The function is evaluated element-wise in case of Array or Matrix input. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | isPrime(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Array | Matrix | Value to be tested 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | boolean | Returns true when `x` is larger than zero. Throws an error in case of an unknown data type. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | isPrime(3); // returns true 34 | isPrime(-2); // returns false 35 | isPrime(0); // returns false 36 | isPrime(-0); // returns false 37 | isPrime(0.5); // returns false 38 | isPrime('2'); // returns true 39 | isPrime([2, 17, 100]'); // returns [true, true, false] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [isNumeric](isNumeric.md), 46 | [isZero](isZero.md), 47 | [isNegative](isNegative.md), 48 | [isInteger](isInteger.md) 49 | -------------------------------------------------------------------------------- /docs/functions/isZero.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function isZero 4 | 5 | Test whether a value is zero. 6 | The function can check for zero for types `number`, `BigNumber`, `Fraction`, 7 | `Complex`, and `Unit`. 8 | 9 | The function is evaluated element-wise in case of Array or Matrix input. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | isZero(x) 16 | ``` 17 | 18 | ### Parameters 19 | 20 | Parameter | Type | Description 21 | --------- | ---- | ----------- 22 | `x` | number | BigNumber | Complex | Fraction | Unit | Array | Matrix | Value to be tested 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | boolean | Returns true when `x` is zero. Throws an error in case of an unknown data type. 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | isZero(0); // returns true 35 | isZero(2); // returns false 36 | isZero(0.5); // returns false 37 | isZero(bignumber(0)); // returns true 38 | isZero(fraction(0)); // returns true 39 | isZero(fraction(1,3)); // returns false 40 | isZero(complex('2 - 4i'); // returns false 41 | isZero(complex('0i'); // returns true 42 | isZero('0'); // returns true 43 | isZero('2'); // returns false 44 | isZero([2, 0, -3]'); // returns [false, true, false] 45 | ``` 46 | 47 | 48 | ## See also 49 | 50 | [isNumeric](isNumeric.md), 51 | [isPositive](isPositive.md), 52 | [isNegative](isNegative.md), 53 | [isInteger](isInteger.md) 54 | -------------------------------------------------------------------------------- /docs/functions/kldivergence.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function kldivergence 4 | 5 | Calculate the Kullback-Leibler (KL) divergence between two distributions 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | kldivergence(x, y) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `q` | Array | Matrix | First vector 19 | `p` | Array | Matrix | Second vector 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | Returns distance between q and p 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | kldivergence([0.7,0.5,0.4], [0.2,0.9,0.5]); //returns 0.24376698773121153 32 | 33 | ``` 34 | 35 | 36 | -------------------------------------------------------------------------------- /docs/functions/larger.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function larger 4 | 5 | Test whether value x is larger than y. 6 | 7 | The function returns true when x is larger than y and the relative 8 | difference between x and y is larger than the configured epsilon. The 9 | function cannot be used to compare values smaller than approximately 2.22e-16. 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | larger(x, y) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `x` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | First value to compare 25 | `y` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | Second value to compare 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | boolean | Array | Matrix | Returns true when the x is larger than y, else returns false 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | larger(2, 3); // returns false 38 | larger(5, 2 + 2); // returns true 39 | 40 | var a = unit('5 cm'); 41 | var b = unit('2 inch'); 42 | larger(a, b); // returns false 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [equal](equal.md), 49 | [unequal](unequal.md), 50 | [smaller](smaller.md), 51 | [smallerEq](smallerEq.md), 52 | [largerEq](largerEq.md), 53 | [compare](compare.md) 54 | -------------------------------------------------------------------------------- /docs/functions/largerEq.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function largerEq 4 | 5 | Test whether value x is larger or equal to y. 6 | 7 | The function returns true when x is larger than y or the relative 8 | difference between x and y is smaller than the configured epsilon. The 9 | function cannot be used to compare values smaller than approximately 2.22e-16. 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | largerEq(x, y) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `x` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | First value to compare 25 | `y` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | Second value to compare 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | boolean | Array | Matrix | Returns true when the x is larger or equal to y, else returns false 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | larger(2, 1 + 1); // returns false 38 | largerEq(2, 1 + 1); // returns true 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [equal](equal.md), 45 | [unequal](unequal.md), 46 | [smaller](smaller.md), 47 | [smallerEq](smallerEq.md), 48 | [larger](larger.md), 49 | [compare](compare.md) 50 | -------------------------------------------------------------------------------- /docs/functions/lcm.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function lcm 4 | 5 | Calculate the least common multiple for two or more values or arrays. 6 | 7 | lcm is defined as: 8 | 9 | lcm(a, b) = abs(a * b) / gcd(a, b) 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | lcm(a, b) 18 | lcm(a, b, c, ...) 19 | ``` 20 | 21 | ### Parameters 22 | 23 | Parameter | Type | Description 24 | --------- | ---- | ----------- 25 | `args` | ... number | BigNumber | Array | Matrix | Two or more integer numbers 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | number | BigNumber | Array | Matrix | The least common multiple 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | lcm(4, 6); // returns 12 38 | lcm(6, 21); // returns 42 39 | lcm(6, 21, 5); // returns 210 40 | 41 | lcm([4, 6], [6, 21]); // returns [12, 42] 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [gcd](gcd.md), 48 | [xgcd](xgcd.md) 49 | -------------------------------------------------------------------------------- /docs/functions/leftShift.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function leftShift 4 | 5 | Bitwise left logical shift of a value x by y number of bits, `x << y`. 6 | For matrices, the function is evaluated element wise. 7 | For units, the function is evaluated on the best prefix base. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | leftShift(x, y) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Array | Matrix | Value to be shifted 21 | `y` | number | BigNumber | Amount of shifts 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Array | Matrix | `x` shifted left `y` times 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | leftShift(1, 2); // returns number 4 34 | 35 | leftShift([1, 2, 3], 4); // returns Array [16, 32, 64] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [leftShift](leftShift.md), 42 | [bitNot](bitNot.md), 43 | [bitOr](bitOr.md), 44 | [bitXor](bitXor.md), 45 | [rightArithShift](rightArithShift.md), 46 | [rightLogShift](rightLogShift.md) 47 | -------------------------------------------------------------------------------- /docs/functions/log.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function log 4 | 5 | Calculate the logarithm of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | log(x) 14 | log(x, base) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Array | Matrix | Value for which to calculate the logarithm. 22 | `base` | number | BigNumber | Complex | Optional base for the logarithm. If not provided, the natural logarithm of `x` is calculated. Default value: e. 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | number | BigNumber | Complex | Array | Matrix | Returns the logarithm of `x` 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | log(3.5); // returns 1.252762968495368 35 | exp(log(2.4)); // returns 2.4 36 | 37 | pow(10, 4); // returns 10000 38 | log(10000, 10); // returns 4 39 | log(10000) / log(10); // returns 4 40 | 41 | log(1024, 2); // returns 10 42 | pow(2, 10); // returns 1024 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [exp](exp.md), 49 | [log10](log10.md) 50 | -------------------------------------------------------------------------------- /docs/functions/log10.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function log10 4 | 5 | Calculate the 10-base logarithm of a value. This is the same as calculating `log(x, 10)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | log10(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Array | Matrix | Value for which to calculate the logarithm. 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | Returns the 10-base logarithm of `x` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | log10(0.00001); // returns -5 33 | log10(10000); // returns 4 34 | log(10000) / log(10); // returns 4 35 | pow(10, 4); // returns 10000 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [exp](exp.md), 42 | [log](log.md) 43 | -------------------------------------------------------------------------------- /docs/functions/lsolve.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function lsolve 4 | 5 | Solves the linear equation system by forwards substitution. Matrix must be a lower triangular matrix. 6 | 7 | `L * x = b` 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | lsolve(L, b); 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `L` | Matrix, Array | A N x N matrix or array (L) 21 | `b` | Matrix, Array | A column vector with the b values 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | DenseMatrix | Array | A column vector with the linear system solution (x) 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var a = [[-2, 3], [2, 1]]; 34 | var b = [11, 9]; 35 | var x = lsolve(a, b); // [[-5.5], [20]] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [lup](lup.md), 42 | [slu](slu.md), 43 | [usolve](usolve.md), 44 | [lusolve](lusolve.md) 45 | -------------------------------------------------------------------------------- /docs/functions/lup.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function lup 4 | 5 | Calculate the Matrix LU decomposition with partial pivoting. Matrix `A` is decomposed in two matrices (`L`, `U`) and a 6 | row permutation vector `p` where `A[p,:] = L * U` 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | lup(A); 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `A` | Matrix | Array | A two dimensional matrix or array for which to get the LUP decomposition. 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | Array<Matrix> | The lower triangular matrix, the upper triangular matrix and the permutation matrix. 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | var m = [[2, 1], [1, 4]]; 32 | var r = lup(); 33 | // r = { 34 | // L: [[1, 0], [0.5, 1]], 35 | // U: [[2, 1], [0, 3.5]], 36 | // P: [0, 1] 37 | // } 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [slu](slu.md), 44 | [lsolve](lsolve.md), 45 | [lusolve](lusolve.md), 46 | [usolve](usolve.md) 47 | -------------------------------------------------------------------------------- /docs/functions/lusolve.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function lusolve 4 | 5 | Solves the linear system `A * x = b` where `A` is an [n x n] matrix and `b` is a [n] column vector. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | lusolve(A, b) // returns column vector with the solution to the linear system A * x = b 12 | lusolve(lup, b) // returns column vector with the solution to the linear system A * x = b, lup = lup(A) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `A` | Matrix | Array | Object | Invertible Matrix or the Matrix LU decomposition 20 | `b` | Matrix | Array | Column Vector 21 | `order` | number | The Symbolic Ordering and Analysis order, see slu for details. Matrix must be a SparseMatrix 22 | `threshold` | Number | Partial pivoting threshold (1 for partial pivoting), see slu for details. Matrix must be a SparseMatrix. 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | DenseMatrix | Array | Column vector with the solution to the linear system A * x = b 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | var m = [[1, 0, 0, 0], [0, 2, 0, 0], [0, 0, 3, 0], [0, 0, 0, 4]]; 35 | 36 | var x = lusolve(m, [-1, -1, -1, -1]); // x = [[-1], [-0.5], [-1/3], [-0.25]] 37 | 38 | var f = lup(m); 39 | var x1 = lusolve(f, [-1, -1, -1, -1]); // x1 = [[-1], [-0.5], [-1/3], [-0.25]] 40 | var x2 = lusolve(f, [1, 2, 1, -1]); // x2 = [[1], [1], [1/3], [-0.25]] 41 | 42 | var a = [[-2, 3], [2, 1]]; 43 | var b = [11, 9]; 44 | var x = lusolve(a, b); // [[-5.5], [20]] 45 | ``` 46 | 47 | 48 | ## See also 49 | 50 | [lup](lup.md), 51 | [slu](slu.md), 52 | [lsolve](lsolve.md), 53 | [usolve](usolve.md) 54 | -------------------------------------------------------------------------------- /docs/functions/matrix.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function matrix 4 | 5 | Create a Matrix. The function creates a new `type.Matrix` object from 6 | an `Array`. A Matrix has utility functions to manipulate the data in the 7 | matrix, like getting the size and getting or setting values in the matrix. 8 | Supported storage formats are 'dense' and 'sparse'. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | matrix() // creates an empty matrix using default storage format (dense). 15 | matrix(data) // creates a matrix with initial data using default storage format (dense). 16 | matrix('dense') // creates an empty matrix using the given storage format. 17 | matrix(data, 'dense') // creates a matrix with initial data using the given storage format. 18 | matrix(data, 'sparse') // creates a sparse matrix with initial data. 19 | matrix(data, 'sparse', 'number') // creates a sparse matrix with initial data, number data type. 20 | ``` 21 | 22 | ### Parameters 23 | 24 | Parameter | Type | Description 25 | --------- | ---- | ----------- 26 | `data` | Array | Matrix | A multi dimensional array 27 | `format` | string | The Matrix storage format 28 | 29 | ### Returns 30 | 31 | Type | Description 32 | ---- | ----------- 33 | Matrix | The created matrix 34 | 35 | 36 | ## Examples 37 | 38 | ```js 39 | var m = matrix([[1, 2], [3, 4]]); 40 | m.size(); // Array [2, 2] 41 | m.resize([3, 2], 5); 42 | m.valueOf(); // Array [[1, 2], [3, 4], [5, 5]] 43 | m.get([1, 0]) // number 3 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [bignumber](bignumber.md), 50 | [boolean](boolean.md), 51 | [complex](complex.md), 52 | [number](number.md), 53 | [string](string.md), 54 | [unit](unit.md), 55 | [sparse](sparse.md) 56 | -------------------------------------------------------------------------------- /docs/functions/max.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function max 4 | 5 | Compute the maximum value of a matrix or a list with values. 6 | In case of a multi dimensional array, the maximum of the flattened array 7 | will be calculated. When `dim` is provided, the maximum over the selected 8 | dimension will be calculated. Parameter `dim` is zero-based. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | max(a, b, c, ...) 15 | max(A) 16 | max(A, dim) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `args` | ... * | A single matrix or or multiple scalar values 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | * | The maximum value 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | max(2, 1, 4, 3); // returns 4 36 | max([2, 1, 4, 3]); // returns 4 37 | 38 | // maximum over a specified dimension (zero-based) 39 | max([[2, 5], [4, 3], [1, 7]], 0); // returns [4, 7] 40 | max([[2, 5], [4, 3]], [1, 7], 1); // returns [5, 4, 7] 41 | 42 | max(2.7, 7.1, -4.5, 2.0, 4.1); // returns 7.1 43 | min(2.7, 7.1, -4.5, 2.0, 4.1); // returns -4.5 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [mean](mean.md), 50 | [median](median.md), 51 | [min](min.md), 52 | [prod](prod.md), 53 | [std](std.md), 54 | [sum](sum.md), 55 | [var](var.md) 56 | -------------------------------------------------------------------------------- /docs/functions/mean.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function mean 4 | 5 | Compute the mean value of matrix or a list with values. 6 | In case of a multi dimensional array, the mean of the flattened array 7 | will be calculated. When `dim` is provided, the maximum over the selected 8 | dimension will be calculated. Parameter `dim` is zero-based. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | mean(a, b, c, ...) 15 | mean(A) 16 | mean(A, dim) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `args` | ... * | A single matrix or or multiple scalar values 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | * | The mean of all values 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | mean(2, 1, 4, 3); // returns 2.5 36 | mean([1, 2.7, 3.2, 4]); // returns 2.725 37 | 38 | mean([[2, 5], [6, 3], [1, 7]], 0); // returns [3, 5] 39 | mean([[2, 5], [6, 3], [1, 7]], 1); // returns [3.5, 4.5, 4] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [median](median.md), 46 | [min](min.md), 47 | [max](max.md), 48 | [sum](sum.md), 49 | [prod](prod.md), 50 | [std](std.md), 51 | [var](var.md) 52 | -------------------------------------------------------------------------------- /docs/functions/median.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function median 4 | 5 | Compute the median of a matrix or a list with values. The values are 6 | sorted and the middle value is returned. In case of an even number of 7 | values, the average of the two middle values is returned. 8 | Supported types of values are: Number, BigNumber, Unit 9 | 10 | In case of a (multi dimensional) array or matrix, the median of all 11 | elements will be calculated. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | median(a, b, c, ...) 18 | median(A) 19 | ``` 20 | 21 | ### Parameters 22 | 23 | Parameter | Type | Description 24 | --------- | ---- | ----------- 25 | `args` | ... * | A single matrix or or multiple scalar values 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | * | The median 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | median(5, 2, 7); // returns 5 38 | median([3, -1, 5, 7]); // returns 4 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [mean](mean.md), 45 | [min](min.md), 46 | [max](max.md), 47 | [sum](sum.md), 48 | [prod](prod.md), 49 | [std](std.md), 50 | [var](var.md) 51 | -------------------------------------------------------------------------------- /docs/functions/min.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function min 4 | 5 | Compute the maximum value of a matrix or a list of values. 6 | In case of a multi dimensional array, the maximum of the flattened array 7 | will be calculated. When `dim` is provided, the maximum over the selected 8 | dimension will be calculated. Parameter `dim` is zero-based. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | min(a, b, c, ...) 15 | min(A) 16 | min(A, dim) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `args` | ... * | A single matrix or or multiple scalar values 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | * | The minimum value 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | min(2, 1, 4, 3); // returns 1 36 | min([2, 1, 4, 3]); // returns 1 37 | 38 | // maximum over a specified dimension (zero-based) 39 | min([[2, 5], [4, 3], [1, 7]], 0); // returns [1, 3] 40 | min([[2, 5], [4, 3], [1, 7]], 1); // returns [2, 3, 1] 41 | 42 | max(2.7, 7.1, -4.5, 2.0, 4.1); // returns 7.1 43 | min(2.7, 7.1, -4.5, 2.0, 4.1); // returns -4.5 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [mean](mean.md), 50 | [median](median.md), 51 | [max](max.md), 52 | [prod](prod.md), 53 | [std](std.md), 54 | [sum](sum.md), 55 | [var](var.md) 56 | -------------------------------------------------------------------------------- /docs/functions/mod.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function mod 4 | 5 | Calculates the modulus, the remainder of an integer division. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | The modulus is defined as: 10 | 11 | x - y * floor(x / y) 12 | 13 | See http://en.wikipedia.org/wiki/Modulo_operation. 14 | 15 | 16 | ## Syntax 17 | 18 | ```js 19 | mod(x, y) 20 | ``` 21 | 22 | ### Parameters 23 | 24 | Parameter | Type | Description 25 | --------- | ---- | ----------- 26 | `x` | number | BigNumber | Fraction | Array | Matrix | Dividend 27 | `y` | number | BigNumber | Fraction | Array | Matrix | Divisor 28 | 29 | ### Returns 30 | 31 | Type | Description 32 | ---- | ----------- 33 | number | BigNumber | Fraction | Array | Matrix | Returns the remainder of `x` divided by `y`. 34 | 35 | 36 | ## Examples 37 | 38 | ```js 39 | mod(8, 3); // returns 2 40 | mod(11, 2); // returns 1 41 | 42 | function isOdd(x) { 43 | return mod(x, 2) != 0; 44 | } 45 | 46 | isOdd(2); // returns false 47 | isOdd(3); // returns true 48 | ``` 49 | 50 | 51 | ## See also 52 | 53 | [divide](divide.md) 54 | -------------------------------------------------------------------------------- /docs/functions/mode.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function mode 4 | 5 | Computes the mode of a set of numbers or a list with values(numbers or characters). 6 | If there are more than one modes, it returns a list of those values. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | mode(a, b, c, ...) 13 | mode(A) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `args` | ... * | A single matrix 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | * | The mode of all values 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | mode(2, 1, 4, 3, 1); // returns [1] 33 | mode([1, 2.7, 3.2, 4, 2.7]); // returns [2.7] 34 | mode(1, 4, 6, 1, 6) // returns [1, 6] 35 | mode('a','a','b','c') // returns ["a"] 36 | mode(1, 1.5, 'abc') // returns [1, 1.5, "abc"] 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [median](median.md), 43 | [](.md), 44 | [mean](mean.md) 45 | -------------------------------------------------------------------------------- /docs/functions/multinomial.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function multinomial 4 | 5 | Multinomial Coefficients compute the number of ways of picking a1, a2, ..., ai unordered outcomes from `n` possibilities. 6 | 7 | multinomial takes one array of integers as an argument. 8 | The following condition must be enforced: every ai <= 0 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | multinomial(a) // a is an array type 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `a` | number[] | BigNumber[] | Integer numbers of objects in the subset 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | Number | BigNumber | Multinomial coefficient. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | multinomial([1,2,1]); // returns 12 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [combinations](combinations.md), 40 | [factorial](factorial.md) 41 | -------------------------------------------------------------------------------- /docs/functions/multiply.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function multiply 4 | 5 | Multiply two values, `x * y`. 6 | For matrices, the matrix product is calculated. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | multiply(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | First value to multiply 20 | `y` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Second value to multiply 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Multiplication of `x` and `y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | multiply(4, 5.2); // returns number 20.8 33 | 34 | var a = complex(2, 3); 35 | var b = complex(4, 1); 36 | multiply(a, b); // returns Complex 5 + 14i 37 | 38 | var c = [[1, 2], [4, 3]]; 39 | var d = [[1, 2, 3], [3, -4, 7]]; 40 | multiply(c, d); // returns Array [[7, -6, 17], [13, -4, 33]] 41 | 42 | var e = unit('2.1 km'); 43 | multiply(3, e); // returns Unit 6.3 km 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [divide](divide.md) 50 | -------------------------------------------------------------------------------- /docs/functions/norm.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function norm 4 | 5 | Calculate the norm of a number, vector or matrix. 6 | 7 | The second parameter p is optional. If not provided, it defaults to 2. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | norm(x) 14 | norm(x, p) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Array | Matrix | Value for which to calculate the norm 22 | `p` | number | BigNumber | string | Vector space. Supported numbers include Infinity and -Infinity. Supported strings are: 'inf', '-inf', and 'fro' (The Frobenius norm) Default value: 2. 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | number | BigNumber | the p-norm 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | abs(-3.5); // returns 3.5 35 | norm(-3.5); // returns 3.5 36 | 37 | norm(complex(3, -4)); // returns 5 38 | 39 | norm([1, 2, -3], Infinity); // returns 3 40 | norm([1, 2, -3], -Infinity); // returns 1 41 | 42 | norm([3, 4], 2); // returns 5 43 | 44 | norm([[1, 2], [3, 4]], 1) // returns 6 45 | norm([[1, 2], [3, 4]], 'inf'); // returns 7 46 | norm([[1, 2], [3, 4]], 'fro'); // returns 5.477225575051661 47 | ``` 48 | 49 | 50 | ## See also 51 | 52 | [abs](abs.md), 53 | [hypot](hypot.md) 54 | -------------------------------------------------------------------------------- /docs/functions/not.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function not 4 | 5 | Logical `not`. Flips boolean value of a given parameter. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | not(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | First value to check 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | boolean | Array | Matrix | Returns true when input is a zero or empty value. 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | not(2); // returns false 32 | not(0); // returns true 33 | not(true); // returns false 34 | 35 | a = [2, -7, 0]; 36 | not(a); // returns [false, false, true] 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [and](and.md), 43 | [or](or.md), 44 | [xor](xor.md) 45 | -------------------------------------------------------------------------------- /docs/functions/nthRoot.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function nthRoot 4 | 5 | Calculate the nth root of a value. 6 | The principal nth root of a positive real number A, is the positive real 7 | solution of the equation 8 | 9 | x^root = A 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | nthRoot(a) 18 | nthRoot(a, root) 19 | ``` 20 | 21 | ### Parameters 22 | 23 | Parameter | Type | Description 24 | --------- | ---- | ----------- 25 | `a` | number | BigNumber | Array | Matrix | Complex | Value for which to calculate the nth root 26 | `root` | number | BigNumber | The root. Default value: 2. 27 | 28 | ### Returns 29 | 30 | Type | Description 31 | ---- | ----------- 32 | number | Complex | Array | Matrix | Returns the nth root of `a` 33 | 34 | 35 | ## Examples 36 | 37 | ```js 38 | nthRoot(9, 2); // returns 3, as 3^2 == 9 39 | sqrt(9); // returns 3, as 3^2 == 9 40 | nthRoot(64, 3); // returns 4, as 4^3 == 64 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [sqrt](sqrt.md), 47 | [pow](pow.md) 48 | -------------------------------------------------------------------------------- /docs/functions/number.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function number 4 | 5 | Create a number or convert a string, boolean, or unit to a number. 6 | When value is a matrix, all elements will be converted to number. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | number(value) 13 | number(unit, valuelessUnit) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `value` | string | number | BigNumber | Fraction | boolean | Array | Matrix | Unit | null | Value to be converted 21 | `valuelessUnit` | Unit | string | A valueless unit, used to convert a unit to a number 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Array | Matrix | The created number 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | number(2); // returns number 2 34 | number('7.2'); // returns number 7.2 35 | number(true); // returns number 1 36 | number([true, false, true, true]); // returns [1, 0, 1, 1] 37 | number(unit('52cm'), 'm'); // returns 0.52 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [bignumber](bignumber.md), 44 | [boolean](boolean.md), 45 | [complex](complex.md), 46 | [matrix](matrix.md), 47 | [string](string.md), 48 | [unit](unit.md) 49 | -------------------------------------------------------------------------------- /docs/functions/ones.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function ones 4 | 5 | Create a matrix filled with ones. The created matrix can have one or 6 | multiple dimensions. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | ones(m) 13 | ones(m, format) 14 | ones(m, n) 15 | ones(m, n, format) 16 | ones([m, n]) 17 | ones([m, n], format) 18 | ones([m, n, p, ...]) 19 | ones([m, n, p, ...], format) 20 | ``` 21 | 22 | ### Parameters 23 | 24 | Parameter | Type | Description 25 | --------- | ---- | ----------- 26 | `size` | ...number | Array | The size of each dimension of the matrix 27 | `format` | string | The Matrix storage format 28 | 29 | ### Returns 30 | 31 | Type | Description 32 | ---- | ----------- 33 | Array | Matrix | number | A matrix filled with ones 34 | 35 | 36 | ## Examples 37 | 38 | ```js 39 | ones(3); // returns [1, 1, 1] 40 | ones(3, 2); // returns [[1, 1], [1, 1], [1, 1]] 41 | ones(3, 2, 'dense'); // returns Dense Matrix [[1, 1], [1, 1], [1, 1]] 42 | 43 | var A = [[1, 2, 3], [4, 5, 6]]; 44 | ones(size(A)); // returns [[1, 1, 1], [1, 1, 1]] 45 | ``` 46 | 47 | 48 | ## See also 49 | 50 | [zeros](zeros.md), 51 | [eye](eye.md), 52 | [size](size.md), 53 | [range](range.md) 54 | -------------------------------------------------------------------------------- /docs/functions/or.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function or 4 | 5 | Logical `or`. Test if at least one value is defined with a nonzero/nonempty value. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | or(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | First value to check 20 | `y` | number | BigNumber | Complex | Unit | Array | Matrix | Second value to check 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | boolean | Array | Matrix | Returns true when one of the inputs is defined with a nonzero/nonempty value. 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | or(2, 4); // returns true 33 | 34 | a = [2, 5, 0]; 35 | b = [0, 22, 0]; 36 | c = 0; 37 | 38 | or(a, b); // returns [true, true, false] 39 | or(b, c); // returns [false, true, false] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [and](and.md), 46 | [not](not.md), 47 | [xor](xor.md) 48 | -------------------------------------------------------------------------------- /docs/functions/partitionSelect.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function partitionSelect 4 | 5 | Partition-based selection of an array or 1D matrix. 6 | Will find the kth smallest value, and mutates the input array. 7 | Uses Quickselect. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | partitionSelect(x, k) 14 | partitionSelect(x, k, compare) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | Matrix | Array | A one dimensional matrix or array to sort 22 | `k` | Number | The kth smallest value to be retrieved; zero-based index 23 | `compare` | Function | 'asc' | 'desc' | An optional comparator function. The function is called as `compare(a, b)`, and must return 1 when a > b, -1 when a < b, and 0 when a == b. Default value: 'asc'. 24 | 25 | ### Returns 26 | 27 | Type | Description 28 | ---- | ----------- 29 | * | Returns the kth lowest value. 30 | 31 | 32 | ## Examples 33 | 34 | ```js 35 | partitionSelect([5, 10, 1], 2); // returns 10 36 | partitionSelect(['C', 'B', 'A', 'D'], 1); // returns 'B' 37 | 38 | function sortByLength (a, b) { 39 | return a.length - b.length; 40 | } 41 | partitionSelect(['Langdon', 'Tom', 'Sara'], 2, sortByLength); // returns 'Langdon' 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [sort](sort.md) 48 | -------------------------------------------------------------------------------- /docs/functions/permutations.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function permutations 4 | 5 | Compute the number of ways of obtaining an ordered subset of `k` elements 6 | from a set of `n` elements. 7 | 8 | Permutations only takes integer arguments. 9 | The following condition must be enforced: k <= n. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | permutations(n) 16 | permutations(n, k) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `n` | number | BigNumber | The number of objects in total 24 | `k` | number | BigNumber | The number of objects in the subset 25 | 26 | ### Returns 27 | 28 | Type | Description 29 | ---- | ----------- 30 | number | BigNumber | The number of permutations 31 | 32 | 33 | ## Examples 34 | 35 | ```js 36 | permutations(5); // 120 37 | permutations(5, 3); // 60 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [combinations](combinations.md), 44 | [factorial](factorial.md) 45 | -------------------------------------------------------------------------------- /docs/functions/pickRandom.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function pickRandom 4 | 5 | Random pick a value from a one dimensional array. 6 | Array element is picked using a random function with uniform distribution. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | pickRandom(array) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `array` | Array | A one dimensional array 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | One of the elements of the provided input array 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | pickRandom([3, 6, 12, 2]); // returns one of the values in the array 32 | ``` 33 | 34 | 35 | ## See also 36 | 37 | [random](random.md), 38 | [randomInt](randomInt.md) 39 | -------------------------------------------------------------------------------- /docs/functions/pow.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function pow 4 | 5 | Calculates the power of x to y, `x ^ y`. 6 | Matrix exponentiation is supported for square matrices `x`, and positive 7 | integer exponents `y`. 8 | 9 | For cubic roots of negative numbers, the function returns the principal 10 | root by default. In order to let the function return the real root, 11 | js can be configured with `config({predictable: true})`. 12 | To retrieve all cubic roots of a value, use `cbrt(x, true)`. 13 | 14 | 15 | ## Syntax 16 | 17 | ```js 18 | pow(x, y) 19 | ``` 20 | 21 | ### Parameters 22 | 23 | Parameter | Type | Description 24 | --------- | ---- | ----------- 25 | `x` | number | BigNumber | Complex | Array | Matrix | The base 26 | `y` | number | BigNumber | Complex | The exponent 27 | 28 | ### Returns 29 | 30 | Type | Description 31 | ---- | ----------- 32 | number | BigNumber | Complex | Array | Matrix | The value of `x` to the power `y` 33 | 34 | 35 | ## Examples 36 | 37 | ```js 38 | pow(2, 3); // returns number 8 39 | 40 | var a = complex(2, 3); 41 | pow(a, 2) // returns Complex -5 + 12i 42 | 43 | var b = [[1, 2], [4, 3]]; 44 | pow(b, 2); // returns Array [[9, 8], [16, 17]] 45 | ``` 46 | 47 | 48 | ## See also 49 | 50 | [multiply](multiply.md), 51 | [sqrt](sqrt.md), 52 | [cbrt](cbrt.md), 53 | [nthRoot](nthRoot.md) 54 | -------------------------------------------------------------------------------- /docs/functions/prod.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function prod 4 | 5 | Compute the product of a matrix or a list with values. 6 | In case of a (multi dimensional) array or matrix, the sum of all 7 | elements will be calculated. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | prod(a, b, c, ...) 14 | prod(A) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `args` | ... * | A single matrix or or multiple scalar values 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | * | The product of all values 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | multiply(2, 3); // returns 6 34 | prod(2, 3); // returns 6 35 | prod(2, 3, 4); // returns 24 36 | prod([2, 3, 4]); // returns 24 37 | prod([[2, 5], [4, 3]]); // returns 120 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [mean](mean.md), 44 | [median](median.md), 45 | [min](min.md), 46 | [max](max.md), 47 | [sum](sum.md), 48 | [std](std.md), 49 | [var](var.md) 50 | -------------------------------------------------------------------------------- /docs/functions/quantileSeq.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function quantileSeq 4 | 5 | Compute the prob order quantile of a matrix or a list with values. 6 | The sequence is sorted and the middle value is returned. 7 | Supported types of sequence values are: Number, BigNumber, Unit 8 | Supported types of probability are: Number, BigNumber 9 | 10 | In case of a (multi dimensional) array or matrix, the prob order quantile 11 | of all elements will be calculated. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | quantileSeq(A, prob[, sorted]) 18 | quantileSeq(A, [prob1, prob2, ...][, sorted]) 19 | quantileSeq(A, N[, sorted]) 20 | ``` 21 | 22 | ### Parameters 23 | 24 | Parameter | Type | Description 25 | --------- | ---- | ----------- 26 | `data` | Array, Matrix | A single matrix or Array 27 | `probOrN` | Number, BigNumber, Array | prob is the order of the quantile, while N is the amount of evenly distributed steps of probabilities; only one of these options can be provided 28 | `sorted` | Boolean | =false is data sorted in ascending order 29 | 30 | ### Returns 31 | 32 | Type | Description 33 | ---- | ----------- 34 | Number, BigNumber, Unit, Array | Quantile(s) 35 | 36 | 37 | ## Examples 38 | 39 | ```js 40 | quantileSeq([3, -1, 5, 7], 0.5); // returns 4 41 | quantileSeq([3, -1, 5, 7], [1/3, 2/3]); // returns [3, 5] 42 | quantileSeq([3, -1, 5, 7], 2); // returns [3, 5] 43 | quantileSeq([-1, 3, 5, 7], 0.5, true); // returns 4 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [median](median.md), 50 | [mean](mean.md), 51 | [min](min.md), 52 | [max](max.md), 53 | [sum](sum.md), 54 | [prod](prod.md), 55 | [std](std.md), 56 | [var](var.md) 57 | -------------------------------------------------------------------------------- /docs/functions/random.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function random 4 | 5 | Return a random number larger or equal to `min` and smaller than `max` 6 | using a uniform distribution. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | random() // generate a random number between 0 and 1 13 | random(max) // generate a random number between 0 and max 14 | random(min, max) // generate a random number between min and max 15 | random(size) // generate a matrix with random numbers between 0 and 1 16 | random(size, max) // generate a matrix with random numbers between 0 and max 17 | random(size, min, max) // generate a matrix with random numbers between min and max 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `size` | Array | Matrix | If provided, an array or matrix with given size and filled with random values is returned 25 | `min` | number | Minimum boundary for the random value, included 26 | `max` | number | Maximum boundary for the random value, excluded 27 | 28 | ### Returns 29 | 30 | Type | Description 31 | ---- | ----------- 32 | number | Array | Matrix | A random number 33 | 34 | 35 | ## Examples 36 | 37 | ```js 38 | random(); // returns a random number between 0 and 1 39 | random(100); // returns a random number between 0 and 100 40 | random(30, 40); // returns a random number between 30 and 40 41 | random([2, 3]); // returns a 2x3 matrix with random numbers between 0 and 1 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [randomInt](randomInt.md), 48 | [pickRandom](pickRandom.md) 49 | -------------------------------------------------------------------------------- /docs/functions/randomInt.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function randomInt 4 | 5 | Return a random integer number larger or equal to `min` and smaller than `max` 6 | using a uniform distribution. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | randomInt(max) // generate a random integer between 0 and max 13 | randomInt(min, max) // generate a random integer between min and max 14 | randomInt(size) // generate a matrix with random integer between 0 and 1 15 | randomInt(size, max) // generate a matrix with random integer between 0 and max 16 | randomInt(size, min, max) // generate a matrix with random integer between min and max 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `size` | Array | Matrix | If provided, an array or matrix with given size and filled with random values is returned 24 | `min` | number | Minimum boundary for the random value, included 25 | `max` | number | Maximum boundary for the random value, excluded 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | number | Array | Matrix | A random integer value 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | randomInt(100); // returns a random integer between 0 and 100 38 | randomInt(30, 40); // returns a random integer between 30 and 40 39 | randomInt([2, 3]); // returns a 2x3 matrix with random integers between 0 and 1 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [random](random.md), 46 | [pickRandom](pickRandom.md) 47 | -------------------------------------------------------------------------------- /docs/functions/range.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function range 4 | 5 | Create an array from a range. 6 | By default, the range end is excluded. This can be customized by providing 7 | an extra parameter `includeEnd`. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | range(str [, includeEnd]) // Create a range from a string, 14 | // where the string contains the 15 | // start, optional step, and end, 16 | // separated by a colon. 17 | range(start, end [, includeEnd]) // Create a range with start and 18 | // end and a step size of 1. 19 | range(start, end, step [, includeEnd]) // Create a range with start, step, 20 | // and end. 21 | ``` 22 | 23 | ### Where 24 | 25 | - `str: string` 26 | A string 'start:end' or 'start:step:end' 27 | - `start: {number | BigNumber}` 28 | Start of the range 29 | - `end: number | BigNumber` 30 | End of the range, excluded by default, included when parameter includeEnd=true 31 | - `step: number | BigNumber` 32 | Step size. Default value is 1. 33 | - `includeEnd: boolean` 34 | Option to specify whether to include the end or not. False by default. 35 | 36 | ### Parameters 37 | 38 | Parameter | Type | Description 39 | --------- | ---- | ----------- 40 | `args` | * | Parameters describing the ranges `start`, `end`, and optional `step`. 41 | 42 | ### Returns 43 | 44 | Type | Description 45 | ---- | ----------- 46 | Array | Matrix | range 47 | 48 | 49 | ## Examples 50 | 51 | ```js 52 | range(2, 6); // [2, 3, 4, 5] 53 | range(2, -3, -1); // [2, 1, 0, -1, -2] 54 | range('2:1:6'); // [2, 3, 4, 5] 55 | range(2, 6, true); // [2, 3, 4, 5, 6] 56 | ``` 57 | 58 | 59 | ## See also 60 | 61 | [ones](ones.md), 62 | [zeros](zeros.md), 63 | [size](size.md), 64 | [subset](subset.md) 65 | -------------------------------------------------------------------------------- /docs/functions/re.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function re 4 | 5 | Get the real part of a complex number. 6 | For a complex number `a + bi`, the function returns `a`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | re(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Array | Matrix | A complex number or array with complex numbers 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Array | Matrix | The real part of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var a = complex(2, 3); 34 | re(a); // returns number 2 35 | im(a); // returns number 3 36 | 37 | re(complex('-5.2i')); // returns number 0 38 | re(complex(2.4)); // returns number 2.4 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [im](im.md), 45 | [conj](conj.md), 46 | [abs](abs.md), 47 | [arg](arg.md) 48 | -------------------------------------------------------------------------------- /docs/functions/resize.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function resize 4 | 5 | Resize a matrix 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | resize(x, size) 12 | resize(x, size, defaultValue) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | Array | Matrix | * | Matrix to be resized 20 | `size` | Array | Matrix | One dimensional array with numbers 21 | `defaultValue` | number | string | Zero by default, except in case of a string, in that case defaultValue = ' ' Default value: 0. 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | * | Array | Matrix | A resized clone of matrix `x` 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | resize([1, 2, 3, 4, 5], [3]); // returns Array [1, 2, 3] 34 | resize([1, 2, 3], [5], 0); // returns Array [1, 2, 3, 0, 0] 35 | resize(2, [2, 3], 0); // returns Matrix [[2, 0, 0], [0, 0, 0]] 36 | resize("hello", [8], "!"); // returns string 'hello!!!' 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [size](size.md), 43 | [squeeze](squeeze.md), 44 | [subset](subset.md) 45 | -------------------------------------------------------------------------------- /docs/functions/rightArithShift.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function rightArithShift 4 | 5 | Bitwise right arithmetic shift of a value x by y number of bits, `x >> y`. 6 | For matrices, the function is evaluated element wise. 7 | For units, the function is evaluated on the best prefix base. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | rightArithShift(x, y) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Array | Matrix | Value to be shifted 21 | `y` | number | BigNumber | Amount of shifts 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Array | Matrix | `x` sign-filled shifted right `y` times 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | rightArithShift(4, 2); // returns number 1 34 | 35 | rightArithShift([16, -32, 64], 4); // returns Array [1, -2, 3] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [bitAnd](bitAnd.md), 42 | [bitNot](bitNot.md), 43 | [bitOr](bitOr.md), 44 | [bitXor](bitXor.md), 45 | [rightArithShift](rightArithShift.md), 46 | [rightLogShift](rightLogShift.md) 47 | -------------------------------------------------------------------------------- /docs/functions/rightLogShift.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function rightLogShift 4 | 5 | Bitwise right logical shift of value x by y number of bits, `x >>> y`. 6 | For matrices, the function is evaluated element wise. 7 | For units, the function is evaluated on the best prefix base. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | rightLogShift(x, y) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Array | Matrix | Value to be shifted 21 | `y` | number | Amount of shifts 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Array | Matrix | `x` zero-filled shifted right `y` times 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | rightLogShift(4, 2); // returns number 1 34 | 35 | rightLogShift([16, -32, 64], 4); // returns Array [1, 2, 3] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [bitAnd](bitAnd.md), 42 | [bitNot](bitNot.md), 43 | [bitOr](bitOr.md), 44 | [bitXor](bitXor.md), 45 | [leftShift](leftShift.md), 46 | [rightLogShift](rightLogShift.md) 47 | -------------------------------------------------------------------------------- /docs/functions/round.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function round 4 | 5 | Round a value towards the nearest integer. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | round(x) 13 | round(x, n) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Number to be rounded 21 | `n` | number | BigNumber | Array | Number of decimals Default value: 0. 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Fraction | Complex | Array | Matrix | Rounded value 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | round(3.2); // returns number 3 34 | round(3.8); // returns number 4 35 | round(-4.2); // returns number -4 36 | round(-4.7); // returns number -5 37 | round(pi, 3); // returns number 3.142 38 | round(123.45678, 2); // returns number 123.46 39 | 40 | var c = complex(3.2, -2.7); 41 | round(c); // returns Complex 3 - 3i 42 | 43 | round([3.2, 3.8, -4.7]); // returns Array [3, 4, -5] 44 | ``` 45 | 46 | 47 | ## See also 48 | 49 | [ceil](ceil.md), 50 | [fix](fix.md), 51 | [floor](floor.md) 52 | -------------------------------------------------------------------------------- /docs/functions/sec.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sec 4 | 5 | Calculate the secant of a value, defined as `sec(x) = 1/cos(x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | sec(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | Complex | Unit | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | Complex | Array | Matrix | Secant of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | sec(2); // returns number -2.4029979617223822 33 | 1 / cos(2); // returns number -2.4029979617223822 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [cos](cos.md), 40 | [csc](csc.md), 41 | [cot](cot.md) 42 | -------------------------------------------------------------------------------- /docs/functions/sech.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sech 4 | 5 | Calculate the hyperbolic secant of a value, 6 | defined as `sech(x) = 1 / cosh(x)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | sech(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | Complex | Array | Matrix | Hyperbolic secant of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | // sech(x) = 1/ cosh(x) 34 | sech(0.5); // returns 0.886818883970074 35 | 1 / cosh(0.5); // returns 0.886818883970074 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [cosh](cosh.md), 42 | [csch](csch.md), 43 | [coth](coth.md) 44 | -------------------------------------------------------------------------------- /docs/functions/sign.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sign 4 | 5 | Compute the sign of a value. The sign of a value x is: 6 | 7 | - 1 when x > 1 8 | - -1 when x < 0 9 | - 0 when x == 0 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | sign(x) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | The number for which to determine the sign 25 | 26 | ### Returns 27 | 28 | Type | Description 29 | ---- | ----------- 30 | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | e The sign of `x` 31 | 32 | 33 | ## Examples 34 | 35 | ```js 36 | sign(3.5); // returns 1 37 | sign(-4.2); // returns -1 38 | sign(0); // returns 0 39 | 40 | sign([3, 5, -2, 0, 2]); // returns [1, 1, -1, 0, 1] 41 | ``` 42 | 43 | 44 | ## See also 45 | 46 | [abs](abs.md) 47 | -------------------------------------------------------------------------------- /docs/functions/sin.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sin 4 | 5 | Calculate the sine of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | sin(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | Sine of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | sin(2); // returns number 0.9092974268256813 33 | sin(pi / 4); // returns number 0.7071067811865475 34 | sin(unit(90, 'deg')); // returns number 1 35 | sin(unit(30, 'deg')); // returns number 0.5 36 | 37 | var angle = 0.2; 38 | pow(sin(angle), 2) + pow(cos(angle), 2); // returns number ~1 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [cos](cos.md), 45 | [tan](tan.md) 46 | -------------------------------------------------------------------------------- /docs/functions/sinh.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sinh 4 | 5 | Calculate the hyperbolic sine of a value, 6 | defined as `sinh(x) = 1/2 * (exp(x) - exp(-x))`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | sinh(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Complex | Array | Matrix | Hyperbolic sine of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | sinh(0.5); // returns number 0.5210953054937474 34 | ``` 35 | 36 | 37 | ## See also 38 | 39 | [cosh](cosh.md), 40 | [tanh](tanh.md) 41 | -------------------------------------------------------------------------------- /docs/functions/size.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function size 4 | 5 | Calculate the size of a matrix or scalar. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | size(x) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | boolean | number | Complex | Unit | string | Array | Matrix | A matrix 19 | 20 | ### Returns 21 | 22 | Type | Description 23 | ---- | ----------- 24 | Array | Matrix | A vector with size of `x`. 25 | 26 | 27 | ## Examples 28 | 29 | ```js 30 | size(2.3); // returns [] 31 | size('hello world'); // returns [11] 32 | 33 | var A = [[1, 2, 3], [4, 5, 6]]; 34 | size(A); // returns [2, 3] 35 | size(range(1,6)); // returns [5] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [resize](resize.md), 42 | [squeeze](squeeze.md), 43 | [subset](subset.md) 44 | -------------------------------------------------------------------------------- /docs/functions/slu.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function slu 4 | 5 | Calculate the Sparse Matrix LU decomposition with full pivoting. Sparse Matrix `A` is decomposed in two matrices (`L`, `U`) and two permutation vectors (`pinv`, `q`) where 6 | 7 | `P * A * Q = L * U` 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | slu(A, order, threshold); 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `A` | SparseMatrix | A two dimensional sparse matrix for which to get the LU decomposition. 21 | `order` | Number | The Symbolic Ordering and Analysis order: 0 - Natural ordering, no permutation vector q is returned 1 - Matrix must be square, symbolic ordering and analisis is performed on M = A + A' 2 - Symbolic ordering and analisis is performed on M = A' * A. Dense columns from A' are dropped, A recreated from A'. This is appropriatefor LU factorization of unsymmetric matrices. 3 - Symbolic ordering and analisis is performed on M = A' * A. This is best used for LU factorization is matrix M has no dense rows. A dense row is a row with more than 10*sqr(columns) entries. 22 | `threshold` | Number | Partial pivoting threshold (1 for partial pivoting) 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | Object | The lower triangular matrix, the upper triangular matrix and the permutation vectors. 29 | 30 | 31 | ## See also 32 | 33 | [lup](lup.md), 34 | [lsolve](lsolve.md), 35 | [usolve](usolve.md), 36 | [lusolve](lusolve.md) 37 | -------------------------------------------------------------------------------- /docs/functions/smaller.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function smaller 4 | 5 | Test whether value x is smaller than y. 6 | 7 | The function returns true when x is smaller than y and the relative 8 | difference between x and y is smaller than the configured epsilon. The 9 | function cannot be used to compare values smaller than approximately 2.22e-16. 10 | 11 | For matrices, the function is evaluated element wise. 12 | 13 | 14 | ## Syntax 15 | 16 | ```js 17 | smaller(x, y) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `x` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | First value to compare 25 | `y` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | Second value to compare 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | boolean | Array | Matrix | Returns true when the x is smaller than y, else returns false 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | smaller(2, 3); // returns true 38 | smaller(5, 2 * 2); // returns false 39 | 40 | var a = unit('5 cm'); 41 | var b = unit('2 inch'); 42 | smaller(a, b); // returns true 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [equal](equal.md), 49 | [unequal](unequal.md), 50 | [smallerEq](smallerEq.md), 51 | [smaller](smaller.md), 52 | [smallerEq](smallerEq.md), 53 | [compare](compare.md) 54 | -------------------------------------------------------------------------------- /docs/functions/smallerEq.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function smallerEq 4 | 5 | Test whether value x is smaller or equal to y. 6 | 7 | The function returns true when x is smaller than y or the relative 8 | difference between x and y is smaller than the configured epsilon. The 9 | function cannot be used to compare values smaller than approximately 2.22e-16. 10 | For matrices, the function is evaluated element wise. 11 | 12 | 13 | ## Syntax 14 | 15 | ```js 16 | smallerEq(x, y) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `x` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | First value to compare 24 | `y` | number | BigNumber | Fraction | boolean | Unit | string | Array | Matrix | Second value to compare 25 | 26 | ### Returns 27 | 28 | Type | Description 29 | ---- | ----------- 30 | boolean | Array | Matrix | Returns true when the x is smaller than y, else returns false 31 | 32 | 33 | ## Examples 34 | 35 | ```js 36 | smaller(1 + 2, 3); // returns false 37 | smallerEq(1 + 2, 3); // returns true 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [equal](equal.md), 44 | [unequal](unequal.md), 45 | [smaller](smaller.md), 46 | [larger](larger.md), 47 | [largerEq](largerEq.md), 48 | [compare](compare.md) 49 | -------------------------------------------------------------------------------- /docs/functions/sort.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sort 4 | 5 | Sort the items in a matrix. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | sort(x) 12 | sort(x, compare) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | Matrix | Array | A one dimensional matrix or array to sort 20 | `compare` | Function | 'asc' | 'desc' | An optional _comparator function. The function is called as `compare(a, b)`, and must return 1 when a > b, -1 when a < b, and 0 when a == b. Default value: 'asc'. 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | Matrix | Array | Returns the sorted matrix. 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | sort([5, 10, 1]); // returns [1, 5, 10] 33 | sort(['C', 'B', 'A', 'D']); // returns ['A', 'B', 'C', 'D'] 34 | 35 | function sortByLength (a, b) { 36 | return a.length - b.length; 37 | } 38 | sort(['Langdon', 'Tom', 'Sara'], sortByLength); // returns ['Tom', 'Sara', 'Langdon'] 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [filter](filter.md) 45 | -------------------------------------------------------------------------------- /docs/functions/sparse.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sparse 4 | 5 | Create a Sparse Matrix. The function creates a new `type.Matrix` object from 6 | an `Array`. A Matrix has utility functions to manipulate the data in the 7 | matrix, like getting the size and getting or setting values in the matrix. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | sparse() // creates an empty sparse matrix. 14 | sparse(data) // creates a sparse matrix with initial data. 15 | sparse(data, 'number') // creates a sparse matrix with initial data, number datatype. 16 | ``` 17 | 18 | ### Parameters 19 | 20 | Parameter | Type | Description 21 | --------- | ---- | ----------- 22 | `data` | Array | Matrix | A two dimensional array 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | Matrix | The created matrix 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | var m = sparse([[1, 2], [3, 4]]); 35 | m.size(); // Array [2, 2] 36 | m.resize([3, 2], 5); 37 | m.valueOf(); // Array [[1, 2], [3, 4], [5, 5]] 38 | m.get([1, 0]) // number 3 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [bignumber](bignumber.md), 45 | [boolean](boolean.md), 46 | [complex](complex.md), 47 | [number](number.md), 48 | [string](string.md), 49 | [unit](unit.md), 50 | [matrix](matrix.md) 51 | -------------------------------------------------------------------------------- /docs/functions/splitUnit.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function splitUnit 4 | 5 | Returns an array of units whose sum is equal to this unit 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | splitUnit(unit: Unit, parts: Array.) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `parts` | Array | An array of strings or valueless units. 19 | 20 | ### Returns 21 | 22 | Type | Description 23 | ---- | ----------- 24 | Array | An array of units. 25 | 26 | 27 | ## Examples 28 | 29 | ```js 30 | splitUnit(new Unit(1, 'm'), ['feet', 'inch']); 31 | // [ 3 feet, 3.3700787401575 inch ] 32 | ``` 33 | 34 | 35 | ## See also 36 | 37 | [unit](unit.md) 38 | -------------------------------------------------------------------------------- /docs/functions/sqrt.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sqrt 4 | 5 | Calculate the square root of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | sqrt(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Array | Matrix | Unit | Value for which to calculate the square root. 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | Unit | Returns the square root of `x` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | sqrt(25); // returns 5 33 | square(5); // returns 25 34 | sqrt(-4); // returns Complex 2i 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [square](square.md), 41 | [multiply](multiply.md), 42 | [cube](cube.md), 43 | [cbrt](cbrt.md) 44 | -------------------------------------------------------------------------------- /docs/functions/square.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function square 4 | 5 | Compute the square of a value, `x * x`. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | square(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | Number for which to calculate the square 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | BigNumber | Fraction | Complex | Array | Matrix | Unit | Squared value 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | square(2); // returns number 4 32 | square(3); // returns number 9 33 | pow(3, 2); // returns number 9 34 | multiply(3, 3); // returns number 9 35 | 36 | square([1, 2, 3, 4]); // returns Array [1, 4, 9, 16] 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [multiply](multiply.md), 43 | [cube](cube.md), 44 | [sqrt](sqrt.md), 45 | [pow](pow.md) 46 | -------------------------------------------------------------------------------- /docs/functions/squeeze.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function squeeze 4 | 5 | Squeeze a matrix, remove inner and outer singleton dimensions from a matrix. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | squeeze(x) 12 | ``` 13 | 14 | ### Parameters 15 | 16 | Parameter | Type | Description 17 | --------- | ---- | ----------- 18 | `x` | Matrix | Array | Matrix to be squeezed 19 | 20 | ### Returns 21 | 22 | Type | Description 23 | ---- | ----------- 24 | Matrix | Array | Squeezed matrix 25 | 26 | 27 | ## Examples 28 | 29 | ```js 30 | squeeze([3]); // returns 3 31 | squeeze([[3]]); // returns 3 32 | 33 | var A = zeros(3, 1); // returns [[0], [0], [0]] (size 3x1) 34 | squeeze(A); // returns [0, 0, 0] (size 3) 35 | 36 | var B = zeros(1, 3); // returns [[0, 0, 0]] (size 1x3) 37 | squeeze(B); // returns [0, 0, 0] (size 3) 38 | 39 | // only inner and outer dimensions are removed 40 | var C = zeros(2, 1, 3); // returns [[[0, 0, 0]], [[0, 0, 0]]] (size 2x1x3) 41 | squeeze(C); // returns [[[0, 0, 0]], [[0, 0, 0]]] (size 2x1x3) 42 | ``` 43 | 44 | 45 | ## See also 46 | 47 | [subset](subset.md) 48 | -------------------------------------------------------------------------------- /docs/functions/std.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function std 4 | 5 | Compute the standard deviation of a matrix or a list with values. 6 | The standard deviations is defined as the square root of the variance: 7 | `std(A) = sqrt(var(A))`. 8 | In case of a (multi dimensional) array or matrix, the standard deviation 9 | over all elements will be calculated. 10 | 11 | Optionally, the type of normalization can be specified as second 12 | parameter. The parameter `normalization` can be one of the following values: 13 | 14 | - 'unbiased' (default) The sum of squared errors is divided by (n - 1) 15 | - 'uncorrected' The sum of squared errors is divided by n 16 | - 'biased' The sum of squared errors is divided by (n + 1) 17 | 18 | 19 | ## Syntax 20 | 21 | ```js 22 | std(a, b, c, ...) 23 | std(A) 24 | std(A, normalization) 25 | ``` 26 | 27 | ### Parameters 28 | 29 | Parameter | Type | Description 30 | --------- | ---- | ----------- 31 | `array` | Array | Matrix | A single matrix or or multiple scalar values 32 | `normalization` | string | Determines how to normalize the variance. Choose 'unbiased' (default), 'uncorrected', or 'biased'. Default value: 'unbiased'. 33 | 34 | ### Returns 35 | 36 | Type | Description 37 | ---- | ----------- 38 | * | The standard deviation 39 | 40 | 41 | ## Examples 42 | 43 | ```js 44 | std(2, 4, 6); // returns 2 45 | std([2, 4, 6, 8]); // returns 2.581988897471611 46 | std([2, 4, 6, 8], 'uncorrected'); // returns 2.23606797749979 47 | std([2, 4, 6, 8], 'biased'); // returns 2 48 | 49 | std([[1, 2, 3], [4, 5, 6]]); // returns 1.8708286933869707 50 | ``` 51 | 52 | 53 | ## See also 54 | 55 | [mean](mean.md), 56 | [median](median.md), 57 | [max](max.md), 58 | [min](min.md), 59 | [prod](prod.md), 60 | [sum](sum.md), 61 | [var](var.md) 62 | -------------------------------------------------------------------------------- /docs/functions/stirlingS2.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function stirlingS2 4 | 5 | The Stirling numbers of the second kind, counts the number of ways to partition 6 | a set of n labelled objects into k nonempty unlabelled subsets. 7 | stirlingS2 only takes integer arguments. 8 | The following condition must be enforced: k <= n. 9 | 10 | If n = k or k = 1, then s(n,k) = 1 11 | 12 | 13 | ## Syntax 14 | 15 | ```js 16 | stirlingS2(n, k) 17 | ``` 18 | 19 | ### Parameters 20 | 21 | Parameter | Type | Description 22 | --------- | ---- | ----------- 23 | `n` | Number | BigNumber | Total number of objects in the set 24 | `k` | Number | BigNumber | Number of objects in the subset 25 | 26 | ### Returns 27 | 28 | Type | Description 29 | ---- | ----------- 30 | Number | BigNumber | S(n,k) 31 | 32 | 33 | ## Examples 34 | 35 | ```js 36 | stirlingS2(5, 3); //returns 25 37 | ``` 38 | -------------------------------------------------------------------------------- /docs/functions/string.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function string 4 | 5 | Create a string or convert any object into a string. 6 | Elements of Arrays and Matrices are processed element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | string(value) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `value` | * | Array | Matrix | null | A value to convert to a string 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | string | Array | Matrix | The created string 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | string(4.2); // returns string '4.2' 32 | string(complex(3, 2); // returns string '3 + 2i' 33 | 34 | var u = unit(5, 'km'); 35 | string(u.to('m')); // returns string '5000 m' 36 | 37 | string([true, false]); // returns ['true', 'false'] 38 | ``` 39 | 40 | 41 | ## See also 42 | 43 | [bignumber](bignumber.md), 44 | [boolean](boolean.md), 45 | [complex](complex.md), 46 | [matrix](matrix.md), 47 | [number](number.md), 48 | [unit](unit.md) 49 | -------------------------------------------------------------------------------- /docs/functions/subset.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function subset 4 | 5 | Get or set a subset of a matrix or string. 6 | 7 | 8 | ## Syntax 9 | 10 | ```js 11 | subset(value, index) // retrieve a subset 12 | subset(value, index, replacement [, defaultValue]) // replace a subset 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `matrix` | Array | Matrix | string | An array, matrix, or string 20 | `index` | Index | An index containing ranges for each dimension 21 | `replacement` | * | An array, matrix, or scalar. If provided, the subset is replaced with replacement. If not provided, the subset is returned 22 | `defaultValue` | * | Default value, filled in on new entries when the matrix is resized. If not provided, matrix elements will be left undefined. Default value: undefined. 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | Array | Matrix | string | Either the retrieved subset or the updated matrix. 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | // get a subset 35 | var d = [[1, 2], [3, 4]]; 36 | subset(d, index(1, 0)); // returns 3 37 | subset(d, index([0, 2], 1)); // returns [[2], [4]] 38 | 39 | // replace a subset 40 | var e = []; 41 | var f = subset(e, index(0, [0, 2]), [5, 6]); // f = [[5, 6]] 42 | var g = subset(f, index(1, 1), 7, 0); // g = [[5, 6], [0, 7]] 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [size](size.md), 49 | [resize](resize.md), 50 | [squeeze](squeeze.md) 51 | -------------------------------------------------------------------------------- /docs/functions/subtract.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function subtract 4 | 5 | Subtract two values, `x - y`. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | subtract(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Initial value 20 | `y` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Value to subtract from `x` 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Subtraction of `x` and `y` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | subtract(5.3, 2); // returns number 3.3 33 | 34 | var a = complex(2, 3); 35 | var b = complex(4, 1); 36 | subtract(a, b); // returns Complex -2 + 2i 37 | 38 | subtract([5, 7, 4], 4); // returns Array [1, 3, 0] 39 | 40 | var c = unit('2.1 km'); 41 | var d = unit('500m'); 42 | subtract(c, d); // returns Unit 1.6 km 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [add](add.md) 49 | -------------------------------------------------------------------------------- /docs/functions/sum.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function sum 4 | 5 | Compute the sum of a matrix or a list with values. 6 | In case of a (multi dimensional) array or matrix, the sum of all 7 | elements will be calculated. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | sum(a, b, c, ...) 14 | sum(A) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `args` | ... * | A single matrix or or multiple scalar values 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | * | The sum of all values 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | sum(2, 1, 4, 3); // returns 10 34 | sum([2, 1, 4, 3]); // returns 10 35 | sum([[2, 5], [4, 3], [1, 7]]); // returns 22 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [mean](mean.md), 42 | [median](median.md), 43 | [min](min.md), 44 | [max](max.md), 45 | [prod](prod.md), 46 | [std](std.md), 47 | [var](var.md) 48 | -------------------------------------------------------------------------------- /docs/functions/tan.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function tan 4 | 5 | Calculate the tangent of a value. `tan(x)` is equal to `sin(x) / cos(x)`. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | tan(x) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Function input 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | number | BigNumber | Complex | Array | Matrix | Tangent of x 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | tan(0.5); // returns number 0.5463024898437905 33 | sin(0.5) / cos(0.5); // returns number 0.5463024898437905 34 | tan(pi / 4); // returns number 1 35 | tan(unit(45, 'deg')); // returns number 1 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [atan](atan.md), 42 | [sin](sin.md), 43 | [cos](cos.md) 44 | -------------------------------------------------------------------------------- /docs/functions/tanh.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function tanh 4 | 5 | Calculate the hyperbolic tangent of a value, 6 | defined as `tanh(x) = (exp(2 * x) - 1) / (exp(2 * x) + 1)`. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | tanh(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | Function input 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Complex | Array | Matrix | Hyperbolic tangent of x 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | // tanh(x) = sinh(x) / cosh(x) = 1 / coth(x) 34 | tanh(0.5); // returns 0.46211715726000974 35 | sinh(0.5) / cosh(0.5); // returns 0.46211715726000974 36 | 1 / coth(0.5); // returns 0.46211715726000974 37 | ``` 38 | 39 | 40 | ## See also 41 | 42 | [sinh](sinh.md), 43 | [cosh](cosh.md), 44 | [coth](coth.md) 45 | -------------------------------------------------------------------------------- /docs/functions/to.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function to 4 | 5 | Change the unit of a value. 6 | 7 | For matrices, the function is evaluated element wise. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | to(x, unit) 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `x` | Unit | Array | Matrix | The unit to be converted. 21 | `unit` | Unit | Array | Matrix | New unit. Can be a string like "cm" or a unit without value. 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | Unit | Array | Matrix | value with changed, fixed unit. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | to(unit('2 inch'), 'cm'); // returns Unit 5.08 cm 34 | to(unit('2 inch'), unit(null, 'cm')); // returns Unit 5.08 cm 35 | to(unit(16, 'bytes'), 'bits'); // returns Unit 128 bits 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [unit](unit.md) 42 | -------------------------------------------------------------------------------- /docs/functions/trace.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function trace 4 | 5 | Calculate the trace of a matrix: the sum of the elements on the main 6 | diagonal of a square matrix. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | trace(x) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | Array | Matrix | A matrix 20 | 21 | ### Returns 22 | 23 | Type | Description 24 | ---- | ----------- 25 | number | The trace of `x` 26 | 27 | 28 | ## Examples 29 | 30 | ```js 31 | trace([[1, 2], [3, 4]]); // returns 5 32 | 33 | var A = [ 34 | [1, 2, 3], 35 | [-1, 2, 3], 36 | [2, 0, 3] 37 | ] 38 | trace(A); // returns 6 39 | ``` 40 | 41 | 42 | ## See also 43 | 44 | [diag](diag.md) 45 | -------------------------------------------------------------------------------- /docs/functions/transpose.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function transpose 4 | 5 | Transpose a matrix. All values of the matrix are reflected over its 6 | main diagonal. Only applicable to two dimensional matrices containing 7 | a vector (i.e. having size `[1,n]` or `[n,1]`). One dimensional 8 | vectors and scalars return the input unchanged. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | transpose(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | Array | Matrix | Matrix to be transposed 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | Array | Matrix | The transposed matrix 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var A = [[1, 2, 3], [4, 5, 6]]; 34 | transpose(A); // returns [[1, 4], [2, 5], [3, 6]] 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [diag](diag.md), 41 | [inv](inv.md), 42 | [subset](subset.md), 43 | [squeeze](squeeze.md) 44 | -------------------------------------------------------------------------------- /docs/functions/unaryMinus.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function unaryMinus 4 | 5 | Inverse the sign of a value, apply a unary minus operation. 6 | 7 | For matrices, the function is evaluated element wise. Boolean values and 8 | strings will be converted to a number. For complex numbers, both real and 9 | complex value are inverted. 10 | 11 | 12 | ## Syntax 13 | 14 | ```js 15 | unaryMinus(x) 16 | ``` 17 | 18 | ### Parameters 19 | 20 | Parameter | Type | Description 21 | --------- | ---- | ----------- 22 | `x` | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Number to be inverted. 23 | 24 | ### Returns 25 | 26 | Type | Description 27 | ---- | ----------- 28 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Returns the value with inverted sign. 29 | 30 | 31 | ## Examples 32 | 33 | ```js 34 | unaryMinus(3.5); // returns -3.5 35 | unaryMinus(-4.2); // returns 4.2 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [add](add.md), 42 | [subtract](subtract.md), 43 | [unaryPlus](unaryPlus.md) 44 | -------------------------------------------------------------------------------- /docs/functions/unaryPlus.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function unaryPlus 4 | 5 | Unary plus operation. 6 | Boolean values and strings will be converted to a number, numeric values will be returned as is. 7 | 8 | For matrices, the function is evaluated element wise. 9 | 10 | 11 | ## Syntax 12 | 13 | ```js 14 | unaryPlus(x) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `x` | number | BigNumber | Fraction | string | Complex | Unit | Array | Matrix | Input value 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | number | BigNumber | Fraction | Complex | Unit | Array | Matrix | Returns the input value when numeric, converts to a number when input is non-numeric. 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | unaryPlus(3.5); // returns 3.5 34 | unaryPlus(1); // returns 1 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [unaryMinus](unaryMinus.md), 41 | [add](add.md), 42 | [subtract](subtract.md) 43 | -------------------------------------------------------------------------------- /docs/functions/unequal.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function unequal 4 | 5 | Test whether two values are unequal. 6 | 7 | The function tests whether the relative difference between x and y is 8 | larger than the configured epsilon. The function cannot be used to compare 9 | values smaller than approximately 2.22e-16. 10 | 11 | For matrices, the function is evaluated element wise. 12 | In case of complex numbers, x.re must unequal y.re, or x.im must unequal y.im. 13 | 14 | Values `null` and `undefined` are compared strictly, thus `null` is unequal 15 | with everything except `null`, and `undefined` is unequal with everying 16 | except. `undefined`. 17 | 18 | 19 | ## Syntax 20 | 21 | ```js 22 | unequal(x, y) 23 | ``` 24 | 25 | ### Parameters 26 | 27 | Parameter | Type | Description 28 | --------- | ---- | ----------- 29 | `x` | number | BigNumber | Fraction | boolean | Complex | Unit | string | Array | Matrix | undefined | First value to compare 30 | `y` | number | BigNumber | Fraction | boolean | Complex | Unit | string | Array | Matrix | undefined | Second value to compare 31 | 32 | ### Returns 33 | 34 | Type | Description 35 | ---- | ----------- 36 | boolean | Array | Matrix | Returns true when the compared values are unequal, else returns false 37 | 38 | 39 | ## Examples 40 | 41 | ```js 42 | unequal(2 + 2, 3); // returns true 43 | unequal(2 + 2, 4); // returns false 44 | 45 | var a = unit('50 cm'); 46 | var b = unit('5 m'); 47 | unequal(a, b); // returns false 48 | 49 | var c = [2, 5, 1]; 50 | var d = [2, 7, 1]; 51 | 52 | unequal(c, d); // returns [false, true, false] 53 | deepEqual(c, d); // returns false 54 | 55 | unequal(0, null); // returns true 56 | ``` 57 | 58 | 59 | ## See also 60 | 61 | [equal](equal.md), 62 | [deepEqual](deepEqual.md), 63 | [smaller](smaller.md), 64 | [smallerEq](smallerEq.md), 65 | [larger](larger.md), 66 | [largerEq](largerEq.md), 67 | [compare](compare.md) 68 | -------------------------------------------------------------------------------- /docs/functions/unit.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function unit 4 | 5 | Create a unit. Depending on the passed arguments, the function 6 | will create and return a new type.Unit object. 7 | When a matrix is provided, all elements will be converted to units. 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | unit(unit : string) 14 | unit(value : number, unit : string) 15 | ``` 16 | 17 | ### Parameters 18 | 19 | Parameter | Type | Description 20 | --------- | ---- | ----------- 21 | `args` | * | Array | Matrix | A number and unit. 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | Unit | Array | Matrix | The created unit 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var a = unit(5, 'cm'); // returns Unit 50 mm 34 | var b = unit('23 kg'); // returns Unit 23 kg 35 | a.to('m'); // returns Unit 0.05 m 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [bignumber](bignumber.md), 42 | [boolean](boolean.md), 43 | [complex](complex.md), 44 | [matrix](matrix.md), 45 | [number](number.md), 46 | [string](string.md), 47 | [createUnit](createUnit.md) 48 | -------------------------------------------------------------------------------- /docs/functions/usolve.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function usolve 4 | 5 | Solves the linear equation system by backward substitution. Matrix must be an upper triangular matrix. 6 | 7 | `U * x = b` 8 | 9 | 10 | ## Syntax 11 | 12 | ```js 13 | usolve(U, b); 14 | ``` 15 | 16 | ### Parameters 17 | 18 | Parameter | Type | Description 19 | --------- | ---- | ----------- 20 | `U` | Matrix, Array | A N x N matrix or array (U) 21 | `b` | Matrix, Array | A column vector with the b values 22 | 23 | ### Returns 24 | 25 | Type | Description 26 | ---- | ----------- 27 | DenseMatrix | Array | A column vector with the linear system solution (x) 28 | 29 | 30 | ## Examples 31 | 32 | ```js 33 | var a = [[-2, 3], [2, 1]]; 34 | var b = [11, 9]; 35 | var x = usolve(a, b); // [[8], [9]] 36 | ``` 37 | 38 | 39 | ## See also 40 | 41 | [lup](lup.md), 42 | [slu](slu.md), 43 | [usolve](usolve.md), 44 | [lusolve](lusolve.md) 45 | -------------------------------------------------------------------------------- /docs/functions/var.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function var 4 | 5 | Compute the variance of a matrix or a list with values. 6 | In case of a (multi dimensional) array or matrix, the variance over all 7 | elements will be calculated. 8 | 9 | Optionally, the type of normalization can be specified as second 10 | parameter. The parameter `normalization` can be one of the following values: 11 | 12 | - 'unbiased' (default) The sum of squared errors is divided by (n - 1) 13 | - 'uncorrected' The sum of squared errors is divided by n 14 | - 'biased' The sum of squared errors is divided by (n + 1) 15 | 16 | Note that older browser may not like the variable name `var`. In that 17 | case, the function can be called as `math['var'](...)` instead of 18 | `var(...)`. 19 | 20 | 21 | ## Syntax 22 | 23 | ```js 24 | var(a, b, c, ...) 25 | var(A) 26 | var(A, normalization) 27 | ``` 28 | 29 | ### Parameters 30 | 31 | Parameter | Type | Description 32 | --------- | ---- | ----------- 33 | `array` | Array | Matrix | A single matrix or or multiple scalar values 34 | `normalization` | string | Determines how to normalize the variance. Choose 'unbiased' (default), 'uncorrected', or 'biased'. Default value: 'unbiased'. 35 | 36 | ### Returns 37 | 38 | Type | Description 39 | ---- | ----------- 40 | * | The variance 41 | 42 | 43 | ## Examples 44 | 45 | ```js 46 | var(2, 4, 6); // returns 4 47 | var([2, 4, 6, 8]); // returns 6.666666666666667 48 | var([2, 4, 6, 8], 'uncorrected'); // returns 5 49 | var([2, 4, 6, 8], 'biased'); // returns 4 50 | 51 | var([[1, 2, 3], [4, 5, 6]]); // returns 3.5 52 | ``` 53 | 54 | 55 | ## See also 56 | 57 | [mean](mean.md), 58 | [median](median.md), 59 | [max](max.md), 60 | [min](min.md), 61 | [prod](prod.md), 62 | [std](std.md), 63 | [sum](sum.md) 64 | -------------------------------------------------------------------------------- /docs/functions/xgcd.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function xgcd 4 | 5 | Calculate the extended greatest common divisor for two values. 6 | See http://en.wikipedia.org/wiki/Extended_Euclidean_algorithm. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | xgcd(a, b) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `a` | number | BigNumber | An integer number 20 | `b` | number | BigNumber | An integer number 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | Array | Returns an array containing 3 integers `[div, m, n]` where `div = gcd(a, b)` and `a*m + b*n = div` 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | xgcd(8, 12); // returns [4, -1, 1] 33 | gcd(8, 12); // returns 4 34 | xgcd(36163, 21199); // returns [1247, -7, 12] 35 | ``` 36 | 37 | 38 | ## See also 39 | 40 | [gcd](gcd.md), 41 | [lcm](lcm.md) 42 | -------------------------------------------------------------------------------- /docs/functions/xor.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function xor 4 | 5 | Logical `xor`. Test whether one and only one value is defined with a nonzero/nonempty value. 6 | For matrices, the function is evaluated element wise. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | xor(x, y) 13 | ``` 14 | 15 | ### Parameters 16 | 17 | Parameter | Type | Description 18 | --------- | ---- | ----------- 19 | `x` | number | BigNumber | Complex | Unit | Array | Matrix | First value to check 20 | `y` | number | BigNumber | Complex | Unit | Array | Matrix | Second value to check 21 | 22 | ### Returns 23 | 24 | Type | Description 25 | ---- | ----------- 26 | boolean | Array | Matrix | Returns true when one and only one input is defined with a nonzero/nonempty value. 27 | 28 | 29 | ## Examples 30 | 31 | ```js 32 | xor(2, 4); // returns false 33 | 34 | a = [2, 0, 0]; 35 | b = [2, 7, 0]; 36 | c = 0; 37 | 38 | xor(a, b); // returns [false, true, false] 39 | xor(a, c); // returns [true, false, false] 40 | ``` 41 | 42 | 43 | ## See also 44 | 45 | [and](and.md), 46 | [not](not.md), 47 | [or](or.md) 48 | -------------------------------------------------------------------------------- /docs/functions/zeros.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Function zeros 4 | 5 | Create a matrix filled with zeros. The created matrix can have one or 6 | multiple dimensions. 7 | 8 | 9 | ## Syntax 10 | 11 | ```js 12 | zeros(m) 13 | zeros(m, format) 14 | zeros(m, n) 15 | zeros(m, n, format) 16 | zeros([m, n]) 17 | zeros([m, n], format) 18 | ``` 19 | 20 | ### Parameters 21 | 22 | Parameter | Type | Description 23 | --------- | ---- | ----------- 24 | `size` | ...number | Array | The size of each dimension of the matrix 25 | `format` | string | The Matrix storage format 26 | 27 | ### Returns 28 | 29 | Type | Description 30 | ---- | ----------- 31 | Array | Matrix | A matrix filled with zeros 32 | 33 | 34 | ## Examples 35 | 36 | ```js 37 | zeros(3); // returns [0, 0, 0] 38 | zeros(3, 2); // returns [[0, 0], [0, 0], [0, 0]] 39 | zeros(3, 'dense'); // returns [0, 0, 0] 40 | 41 | var A = [[1, 2, 3], [4, 5, 6]]; 42 | zeros(size(A)); // returns [[0, 0, 0], [0, 0, 0]] 43 | ``` 44 | 45 | 46 | ## See also 47 | 48 | [ones](ones.md), 49 | [eye](eye.md), 50 | [size](size.md), 51 | [range](range.md) 52 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Mathlion 2 | 3 | Mathlion is a Kibana extension that enables equation parsing and advanced math under Timelion, which is part of Kibana. 4 | 5 | Mathlion is developed by [Fermium LABS](https://fermiumlabs.com/) 6 | 7 | ## Usage 8 | 9 | ### .math() 10 | 11 | Function | Description | Type 12 | :------- | :------------------------------------------- | :-------- 13 | `math()` | Parse mathematical equations and expressions | Chainable 14 | 15 | Examples: 16 | 17 | ```js 18 | .es(*).math("a=source") //the variable "a" now contains the elasticsearch query. 19 | .nop().math("a") //this row now equals the former elasticsearch query 20 | 21 | .es(*).math("source") //return the .es(*) query 22 | .es(*).math("source+5") // add 5 to the .es(*) query 23 | 24 | .nop().math("a=a+2 ; a=a+3 ") //adds 5 to a 25 | .nop().math("a=a+2 ; a=a+3 ; a ") //adds 5 to a and displays a+5 26 | 27 | .es(*).math("a=source") //this query is invisible and does not generate an axis 28 | .es(*).math("a=source; a") //this query does 29 | 30 | .nop().math("sqrt(3^2 + 4^2)") //returns 5 31 | 32 | //Calculate power comsumption based on measured current and stimated voltage (in Europe) 33 | .nop().math("electricPower(v,i)=(v*i)") 34 | .es(metric=avg:current).math(machineCurrent=source) 35 | .nop().math("elascPower(230,machineCurrent)") 36 | 37 | //plot the horizontal statistical mean and variance 38 | .es(*).math("me=mean(source); va=var(source)") 39 | .value(1).math(me*source) 40 | .value(1).math("(me+sqrt(va))*source") 41 | .value(1).math("(me-sqrt(va))*source") 42 | 43 | ``` 44 | 45 | As you may have understood, `source` inside a mathematical expression returns the value of the precedent function. It acts as a local variable, and never exit the boundaries of the function you write it in. 46 | 47 | The variable will now be accessible from the `math()` functions. Internally every variable is considered a mathematical array. 48 | 49 | When you're working in Timelion each variable will be accessible from the whole Timelion sheet you're working in. Beware that you need to start a new chain for the variable to be accessible. 50 | 51 | In Kibana dashboards variables are separated between plots. 52 | 53 | ```js 54 | //this works 55 | .es(*).math("a=source") 56 | .nop().math("a") 57 | 58 | //Error: Undefine symbol a 59 | .es(*).math("a=source").math("a") //the two functions can't see each other 60 | 61 | //A better solution 62 | .es(*).math("a=source; a") 63 | ``` 64 | 65 | ### .nop() 66 | 67 | Function | Description | Type 68 | :------- | :----------------------------------------------------------------------------------------------- | :--------- 69 | `.nop()` | A fake datasource that returns no value at all. It's similar to `.value(0)` | Datasource 70 | 71 | Examples: 72 | 73 | ```js 74 | .nop() //returns nothing at all 75 | .nop().math(variable) //retrieve variable 76 | ``` 77 | 78 | ### Equations examples 79 | 80 | You can do farly complex stuff inside a math function: 81 | 82 | ```js 83 | mode(a) //compute the mode of the whole set of data in "a" in your window and display it as an y axis 84 | (a>0) ? (a=1) : (a=-1) //if is positive a=1, else a=-1\. A will be modified only temporarely for this equation 85 | 86 | delta(a,b,c)=(b^2-4*a*c) //create a new function you can reuse 87 | 88 | a=2; a=a+1 // a is now 3, the sub-expressions are evaluated sequentially The last is the one considered in the end 89 | a=1 ; a=2; a+1 // exactly same as before, but returns directly 3 instead of a=3 90 | 91 | ``` 92 | 93 | 94 | 95 | # Thanks 96 | 97 | Mathlion is based on [Math.js](http://mathjs.org) 98 | -------------------------------------------------------------------------------- /docs/installation.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | Copy the last installation url for your version of Kibana from [the repository releases](https://github.com/fermiumlabs/mathlion/releases/latest). The file follows the naming `mathlion-major.minor.patch.zip` where the version indicated it's the one in Kibana. 4 | 5 | Remember that starting from Kibana 5.0 you always need an update version of every plugin for it to start as indicated [here](https://siren.solutions/in-kibana-5-all-your-plugins-will-break-at-each-and-every-update/). 6 | 7 | ```sh 8 | #Kibana >= 5.x 9 | ./bin/kibana-plugin install https://github.com/fermiumlabs/mathlion/releases/download/version_name/mathlion-major.minor.patch_for_kibana-major.minor.patch.zip 10 | 11 | #Kibana 4 12 | ./bin/kibana --install mathlion -u https://github.com/fermiumlabs/mathlion/releases/download/version_name/mathlion-major.minor.patch_for_kibana-4.X.zip 13 | ``` 14 | 15 | You have to download the 4.x version for Kibana 4 and the specific version to match your Kibana version if you have Kibana >=5.x 16 | -------------------------------------------------------------------------------- /docs/release.md: -------------------------------------------------------------------------------- 1 | # release 2 | 3 | To create a new release: 4 | 5 | 1. Update the supported Elasticsearc/Kibana versions in both package.json and travis.yml. 6 | 2. Move the "Deploy" variable in travis.yml to the newest version. 7 | -------------------------------------------------------------------------------- /functions/enviroment/math-enviroment.js: -------------------------------------------------------------------------------- 1 | var _ = require('lodash'); 2 | var math = require('mathjs'); 3 | 4 | //allocate math environments based on the progressive number of the request 5 | var enviroment = new Object(); 6 | module.exports.initSubEnviroment = function (envName) { 7 | enviroment[envName] = { 8 | 'scope' : [], 9 | 'last_request' : 0 10 | }; 11 | enviroment[envName].scope = new Object(); 12 | enviroment[envName].last_request = Date.now() / 1000; 13 | 14 | }; 15 | module.exports.getScope = function (envName) { 16 | return (enviroment.hasOwnProperty(envName)) ? enviroment[envName].scope : null; 17 | }; 18 | module.exports.setScope = function (envName,scope) { 19 | _.extend(enviroment[envName].scope ,scope); 20 | }; 21 | module.exports.updateRequest = function (envName) { 22 | enviroment[envName].last_request = Date.now() / 1000; 23 | }; 24 | module.exports.exists = function (envName) { 25 | return enviroment.hasOwnProperty(envName); 26 | }; 27 | //destroy elements older than 10 seconds 28 | var interval = setInterval (function (enviroment) { 29 | var now = Date.now() / 1000; 30 | for (var key in enviroment) { 31 | if (typeof enviroment[key] !== 'function' && now - enviroment[key].last_request > 10) { 32 | delete enviroment[key]; 33 | } 34 | } 35 | } , 10000,enviroment); 36 | -------------------------------------------------------------------------------- /functions/math.js: -------------------------------------------------------------------------------- 1 | var alter = require('../../../src/core_plugins/timelion/server/lib/alter.js'); 2 | var Chainable = require('../../../src/core_plugins/timelion/server/lib/classes/chainable'); 3 | var _ = require('lodash'); 4 | var math = require('mathjs'); 5 | var mathenviroment = require('./enviroment/math-enviroment'); 6 | 7 | module.exports = new Chainable('math', { 8 | args: [ 9 | { 10 | name: 'inputSeries', 11 | types: ['seriesList'] 12 | }, 13 | { 14 | name: 'function', 15 | types: ['string'], 16 | help: 'The function to evaluate. Use \"source\" to refer to the preceding chainable. Check out mathlion.docs.fermiumlabs.com' 17 | }, 18 | { 19 | name: 'label', 20 | types: ['string', 'null'] 21 | } 22 | ], 23 | help: 'Advanced math parsing.', 24 | fn: function mathChain(args, tlConfig) { 25 | var envName = tlConfig.server._sources[0]._requestCounter.value + ' '; //Name of the enviroment (# of the request) 26 | 27 | var target = tlConfig.getTargetSeries(); //target series 28 | var inputequation = args.byName.function; //equation to evaluate 29 | var label = args.byName.label; //label for the plot 30 | var isAssign = (inputequation.split(';').slice(-1)[0].indexOf('=') != -1); 31 | var unit = ''; 32 | //initiate mathematical environment (scope) 33 | if(!mathenviroment.exists(envName)){ 34 | mathenviroment.initSubEnviroment(envName); 35 | } 36 | mathenviroment.updateRequest(envName); 37 | 38 | /* 39 | Evaluate the user's input string 40 | If the function is expected to be plotted return the result 41 | Else, if the user it's just doing math, return the original datasource array 42 | */ 43 | function evaluate(equation,scope) { 44 | /* 45 | Parse and elaborate the string to convert normal operators to vector operators 46 | Prevent various problems with numbers formatting 47 | */ 48 | var vectoreq = equation.split('*').join('.*').split('/').join('./').split('^').join('.^'); 49 | vectoreq = vectoreq.split('..*').join('.*').split('../').join('./').split('..^').join('.^'); 50 | //check if eachseries is being elaborated 51 | var evaluated = math.eval(vectoreq,scope);//evaluate the new value/function in the scope 52 | /* 53 | Dealing with mathjs result cases: 54 | 1) With ResultSet results it gets the entries[0] array which is the actual elaboration 55 | 2) Converting Unit objects to their value in said measure 56 | 3) With single value result it plots an horizontal line at that height 57 | */ 58 | if (evaluated.hasOwnProperty('entries')) { 59 | evaluated = evaluated.entries[0]; 60 | } 61 | if (math.typeof(evaluated[0]) == 'Unit') { 62 | //math.autoscale(evaluated); 63 | unit = ' [' + evaluated[0].toJSON().unit + ']'; 64 | evaluated = _.map(evaluated,function(ev){ 65 | return math.number(ev,ev.toJSON().unit); 66 | }); 67 | 68 | } 69 | if (math.typeof(evaluated) == 'Unit') { 70 | unit = ' [' + evaluated.toJSON().unit + ']'; 71 | evaluated = math.number(evaluated,evaluated.toJSON().unit); 72 | } 73 | if (math.typeof(evaluated) == 'number' && !isAssign) { 74 | evaluated = new Array(scope['source'].length).fill(evaluated); 75 | } 76 | return (isAssign) ? scope['source'] : evaluated;//return the correct thing to display 77 | 78 | } 79 | 80 | return alter(args, function (eachSeries) { 81 | var times = _.map(eachSeries.data, 0); //x axis 82 | var val = _.map(eachSeries.data, 1); //y axis 83 | 84 | mathenviroment.setScope(envName,{'source':val}); //add source to the enviroment 85 | 86 | //evaluate the input equation inside the updated scope 87 | var values = evaluate(inputequation,mathenviroment.getScope(envName)); 88 | 89 | eachSeries.data = _.zip(times, values); //update series with new values 90 | 91 | //pretty print equation to string (for the axis label) 92 | var eq = (isAssign) ? eachSeries.label : inputequation.split(';').slice(-1)[0].split('source').join(eachSeries.label); 93 | eachSeries.label = label != null ? label : eq; 94 | eachSeries.label = eachSeries.label + unit; 95 | return eachSeries; 96 | }); 97 | } 98 | }); 99 | -------------------------------------------------------------------------------- /functions/nop.js: -------------------------------------------------------------------------------- 1 | var alter = require('../../../src/core_plugins/timelion/server/lib/alter.js'); 2 | var Datasource = require('../../../src/core_plugins/timelion/server/lib/classes/datasource'); 3 | var _ = require('lodash'); 4 | module.exports = new Datasource('nop', { 5 | args: [ ], 6 | help: 'No operation. Is equivalent to value(0)', 7 | fn: function nop(args, tlConfig) { 8 | var target = tlConfig.getTargetSeries(); 9 | var data = _.map(target, function(bucket){ 10 | return [bucket[0],null]; 11 | }); 12 | return Promise.resolve({ 13 | type: 'seriesList', 14 | list: [ 15 | { 16 | data: data, 17 | type: 'series', 18 | label: null, 19 | fit: args.byName.fit || 'average' 20 | } 21 | ] 22 | }); 23 | } 24 | }); 25 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | module.exports = function (kibana) { 2 | return new kibana.Plugin({ 3 | name: 'mathlion', 4 | require: ['timelion'], 5 | init: function (server) { 6 | server.plugins.timelion.addFunction(require('./functions/nop')); 7 | server.plugins.timelion.addFunction(require('./functions/math')); 8 | } 9 | }); 10 | }; 11 | -------------------------------------------------------------------------------- /logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Fermium/mathlion/9d461e32ea7ec31c1637ab1b06c90ed166c0b68b/logo.png -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "mathlion", 3 | "version": "0.2.11", 4 | "kibanas": [ 5 | "5.0.0-beta1", 6 | "5.0.0", 7 | "5.0.1", 8 | "5.0.2", 9 | "5.1.1", 10 | "5.1.2", 11 | "5.2.0", 12 | "5.2.1", 13 | "5.2.2", 14 | "5.3.0", 15 | "5.4.3", 16 | "5.5.0", 17 | "5.6.0", 18 | "5.6.4" 19 | ], 20 | "repository": { 21 | "type": "git", 22 | "url": "https://github.com/fermiumlabs/mathlion" 23 | }, 24 | "license": "Apache-2.0", 25 | "description": "Advanced math extension for Timelion", 26 | "main": "gulpfile.js", 27 | "scripts": { 28 | "start": "gulp dev", 29 | "build": "gulp build", 30 | "package": "gulp package", 31 | "test": "gulp test" 32 | }, 33 | "devDependencies": { 34 | "@elastic/eslint-config-kibana": "^0.2.1", 35 | "babel-eslint": "^7.1.1", 36 | "bluebird": "^3.1.1", 37 | "eslint": "^3.11.1", 38 | "eslint-plugin-mocha": "^4.7.0", 39 | "glob": "^7.0.5", 40 | "gulp": "^3.9.0", 41 | "gulp-eslint": "^3.0.1", 42 | "gulp-gzip": "^1.2.0", 43 | "gulp-tar": "^1.8.0", 44 | "gulp-util": "^3.0.7", 45 | "gulp-zip": "^3.2.0", 46 | "mkdirp": "^0.5.1", 47 | "rimraf": "^2.5.0", 48 | "rsync": "^0.5.0" 49 | }, 50 | "dependencies": { 51 | "babel-register": "^6.3.13", 52 | "jsonfile": "^2.3.1", 53 | "lodash": "^4.17.2", 54 | "mathjs": "^3.5.2" 55 | } 56 | } 57 | -------------------------------------------------------------------------------- /test.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e 3 | 4 | printf "\n\n uploading the plugin\n" 5 | TRANSFER_URL=$(./transfer upload target/mathlion-*-${ELASTIC_VERSION}.zip) 6 | 7 | printf "\n\ninstalling the plugin\n" 8 | ./kibana/bin/kibana-plugin install $TRANSFER_URL 9 | 10 | printf "\n\nstarting kibana in the background\n" 11 | nohup bash -c "./kibana/bin/kibana --no-ssl >&1 &" 12 | 13 | printf "\n\nWaiting one minute..." 14 | sleep 60 15 | 16 | printf "\nWaiting another minute..." 17 | sleep 60 18 | 19 | printf "\nWaiting another minute..." 20 | sleep 60 21 | 22 | printf "\n\nKibana log:\n" 23 | cat nohup.out 24 | 25 | printf "\n\ntesting for errors...\n" 26 | if grep --ignore-case -q "error" nohup.out; then 27 | printf "\nerror!\n" && exit 1 28 | fi 29 | 30 | if grep -q "Skipping non-plugin directory" nohup.out; then 31 | printf "\nerror!\n" && exit 1 32 | fi 33 | 34 | printf "No errors found\n" 35 | printf "Download tested zip file at:\n" 36 | printf "\nYOU MAY DOWNLOAD THE TESTED .ZIP AT:\n" 37 | printf "$TRANSFER_URL" 38 | --------------------------------------------------------------------------------