README.md (8980B)
1  2 3 [https://mathjs.org](https://mathjs.org) 4 5 Math.js is an extensive math library for JavaScript and Node.js. It features a flexible expression parser with support for symbolic computation, comes with a large set of built-in functions and constants, and offers an integrated solution to work with different data types like numbers, big numbers, complex numbers, fractions, units, and matrices. Powerful and easy to use. 6 7 [](https://www.npmjs.com/package/mathjs) 8 [](https://www.npmjs.com/package/mathjs) 9 [](https://github.com/josdejong/mathjs/actions) 10 [](https://github.com/josdejong/mathjs/graphs/commit-activity) 11 [](https://github.com/josdejong/mathjs/blob/master/LICENSE) 12 [](https://app.fossa.io/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs?ref=badge_shield) 13 [](https://codecov.io/gh/josdejong/mathjs) 14 [](https://github.com/sponsors/josdejong) 15 16 ## Features 17 18 - Supports numbers, big numbers, complex numbers, fractions, units, strings, arrays, and matrices. 19 - Is compatible with JavaScript's built-in Math library. 20 - Contains a flexible expression parser. 21 - Does symbolic computation. 22 - Comes with a large set of built-in functions and constants. 23 - Can be used as a command line application as well. 24 - Runs on any JavaScript engine. 25 - Is easily extensible. 26 - Open source. 27 28 ## Usage 29 30 Math.js can be used in both node.js and in the browser. 31 32 Install math.js using [npm](https://www.npmjs.com/package/mathjs): 33 34 npm install mathjs 35 36 Or download mathjs via one of the CDN's listed on the downloads page: 37 38 [https://mathjs.org/download.html](https://mathjs.org/download.html#download) 39 40 Math.js can be used similar to JavaScript's built-in Math library. Besides that, 41 math.js can evaluate 42 [expressions](https://mathjs.org/docs/expressions/index.html) 43 and supports 44 [chained operations](https://mathjs.org/docs/core/chaining.html). 45 46 ```js 47 import { 48 atan2, chain, derivative, e, evaluate, log, pi, pow, round, sqrt 49 } from 'mathjs' 50 51 // functions and constants 52 round(e, 3) // 2.718 53 atan2(3, -3) / pi // 0.75 54 log(10000, 10) // 4 55 sqrt(-4) // 2i 56 pow([[-1, 2], [3, 1]], 2) // [[7, 0], [0, 7]] 57 derivative('x^2 + x', 'x') // 2 * x + 1 58 59 // expressions 60 evaluate('12 / (2.3 + 0.7)') // 4 61 evaluate('12.7 cm to inch') // 5 inch 62 evaluate('sin(45 deg) ^ 2') // 0.5 63 evaluate('9 / 3 + 2i') // 3 + 2i 64 evaluate('det([-1, 2; 3, 1])') // -7 65 66 // chaining 67 chain(3) 68 .add(4) 69 .multiply(2) 70 .done() // 14 71 ``` 72 73 See the [Getting Started](https://mathjs.org/docs/getting_started.html) for a more detailed tutorial. 74 75 76 ## Browser support 77 78 Math.js works on any ES5 compatible JavaScript engine: node.js, Chrome, Firefox, Safari, Edge, and IE11. 79 80 81 ## Documentation 82 83 - [Getting Started](https://mathjs.org/docs/getting_started.html) 84 - [Examples](https://mathjs.org/examples/index.html) 85 - [Overview](https://mathjs.org/docs/index.html) 86 - [History](https://mathjs.org/history.html) 87 88 89 ## Build 90 91 First clone the project from github: 92 93 git clone git://github.com/josdejong/mathjs.git 94 cd mathjs 95 96 Install the project dependencies: 97 98 npm install 99 100 Then, the project can be build by executing the build script via npm: 101 102 npm run build 103 104 This will build ESM output, CommonJS output, and the bundle math.js 105 from the source files and put them in the folder lib. 106 107 108 ## Develop 109 110 When developing new features for mathjs, it is good to be aware of the following background information. 111 112 ### Code 113 114 The code of `mathjs` is written in ES modules, and requires all files to have a real, relative path, meaning the files must have a `*.js` extension. Please configure adding file extensions on auto import in your IDE. 115 116 ### Architecture 117 118 What mathjs tries to achieve is to offer an environment where you can do calculations with mixed data types, 119 like multiplying a regular `number` with a `Complex` number or a `BigNumber`, and work with all of those in matrices. 120 Mathjs also allows to add a new data type, like say `BigInt`, with little effort. 121 122 The solution that mathjs uses has two main ingredients: 123 124 - **Typed functions**. All functions are created using [`typed-function`](https://github.com/josdejong/typed-function/). This makes it easier to (dynamically) create and extend a single function with new data types, automatically do type conversions on function inputs, etc. So, if you create function multiply for two `number`s, you can extend it with support for multiplying two `BigInts`. If you define a conversion from `BigInt` to `number`, the typed-function will automatically allow you to multiply a `BigInt` with a `number`. 125 126 - **Dependency injection**. When we have a function `multiply` with support for `BigInt`, thanks to the dependency injection, other functions using `multiply` under the hood, like `prod`, will automatically support `BigInt` too. This also works the other way around: if you don't need the heavyweight `multiply` (which supports BigNumbers, matrices, etc), and you just need a plain and simple number support, you can use a lightweight implementation of `multiply` just for numbers, and inject that in `prod` and other functions. 127 128 At the lowest level, mathjs has immutable factory functions which create immutable functions. The core function `math.create(...)` creates a new instance having functions created from all passed factory functions. A mathjs instance is a collection of created functions. It contains a function like `math.import` to allow extending the instance with new functions, which can then be used in the expression parser. 129 130 ### Build scripts 131 132 The build script currently generates two types of output: 133 134 - **any**, generate entry points to create full versions of all functions 135 - **number**: generating and entry points to create lightweight functions just supporting `number` 136 137 For each function, an object is generated containing the factory functions of all dependencies of the function. This allows to just load a specific set of functions, and not load or bundle any other functionality. So for example, to just create function `add` you can do `math.create(addDependencies)`. 138 139 140 ## Test 141 142 To execute tests for the library, install the project dependencies once: 143 144 npm install 145 146 Then, the tests can be executed: 147 148 npm test 149 150 Additionally, the tests can be run on FireFox using [headless mode](https://developer.mozilla.org/en-US/Firefox/Headless_mode): 151 152 npm run test:browser 153 154 To run the tests remotely on BrowserStack, first set the environment variables `BROWSER_STACK_USERNAME` and `BROWSER_STACK_ACCESS_KEY` with your username and access key and then execute: 155 156 npm run test:browserstack 157 158 You can separately run the code linter, though it is also executed with `npm test`: 159 160 npm run lint 161 162 To automatically fix linting issue, run: 163 164 npm run format 165 166 To test code coverage of the tests: 167 168 npm run coverage 169 170 To see the coverage results, open the generated report in your browser: 171 172 ./coverage/lcov-report/index.html 173 174 175 ### Continuous integration testing 176 177 Continuous integration tests are run on [Github Actions](https://github.com/josdejong/mathjs/actions) and [BrowserStack](https://www.browserstack.com) every time a commit is pushed to github. Github Actions runs the tests for different versions of node.js, and BrowserStack runs the tests on all major browsers. 178 179 [](https://www.browserstack.com) 180 181 Thanks Github Actions and BrowserStack for the generous free hosting of this open source project! 182 183 ## License 184 185 Copyright (C) 2013-2022 Jos de Jong <wjosdejong@gmail.com> 186 187 Licensed under the Apache License, Version 2.0 (the "License"); 188 you may not use this file except in compliance with the License. 189 You may obtain a copy of the License at 190 191 https://www.apache.org/licenses/LICENSE-2.0 192 193 Unless required by applicable law or agreed to in writing, software 194 distributed under the License is distributed on an "AS IS" BASIS, 195 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 196 See the License for the specific language governing permissions and 197 limitations under the License.