1 | ```
![math.js](https://raw.github.com/josdejong/mathjs/master/misc/img/mathjs.png)
``` |

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 | ```
[![Version](https://img.shields.io/npm/v/mathjs.svg)](https://www.npmjs.com/package/mathjs)
``` |

8 | ```
[![Downloads](https://img.shields.io/npm/dm/mathjs.svg)](https://www.npmjs.com/package/mathjs)
``` |

9 | ```
[![Build Status](https://github.com/josdejong/mathjs/workflows/Node.js%20CI/badge.svg)](https://github.com/josdejong/mathjs/actions)
``` |

10 | ```
[![Maintenance](https://img.shields.io/maintenance/yes/2024.svg)](https://github.com/josdejong/mathjs/graphs/commit-activity)
``` |

11 | ```
[![License](https://img.shields.io/github/license/josdejong/mathjs.svg)](https://github.com/josdejong/mathjs/blob/master/LICENSE)
``` |

12 | ```
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjosdejong%2Fmathjs?ref=badge_shield)
``` |

13 | ```
[![Codecov](https://codecov.io/gh/josdejong/mathjs/branch/develop/graph/badge.svg)](https://codecov.io/gh/josdejong/mathjs)
``` |

14 | ```
[![Github Sponsor](https://img.shields.io/github/sponsors/josdejong
``` |

15 | ```
)](https://github.com/sponsors/josdejong)
``` |

16 | ```
``` |

17 | ```
## Features
``` |

18 | ```
``` |

19 | ```
- Supports numbers, big numbers, complex numbers, fractions, units, strings, arrays, and matrices.
``` |

20 | ```
- Is compatible with JavaScript's built-in Math library.
``` |

21 | ```
- Contains a flexible expression parser.
``` |

22 | ```
- Does symbolic computation.
``` |

23 | ```
- Comes with a large set of built-in functions and constants.
``` |

24 | ```
- Can be used as a command line application as well.
``` |

25 | ```
- Runs on any JavaScript engine.
``` |

26 | ```
- Is easily extensible.
``` |

27 | ```
- Open source.
``` |

28 | ```
``` |

29 | ```
## Usage
``` |

30 | ```
``` |

31 | ```
Math.js can be used in both node.js and in the browser.
``` |

32 | ```
``` |

33 | ```
Install math.js using [npm](https://www.npmjs.com/package/mathjs):
``` |

34 | ```
``` |

35 | ```
npm install mathjs
``` |

36 | ```
``` |

37 | ```
Or download mathjs via one of the CDN's listed on the downloads page:
``` |

38 | ```
``` |

39 | ```
[https://mathjs.org/download.html](https://mathjs.org/download.html#download)
``` |

40 | ```
``` |

41 | ```
Math.js can be used similar to JavaScript's built-in Math library. Besides that,
``` |

42 | ```
math.js can evaluate
``` |

43 | ```
[expressions](https://mathjs.org/docs/expressions/index.html)
``` |

44 | ```
and supports
``` |

45 | ```
[chained operations](https://mathjs.org/docs/core/chaining.html).
``` |

46 | ```
``` |

47 | ```
```js
``` |

48 | ```
import {
``` |

49 | ```
atan2, chain, derivative, e, evaluate, log, pi, pow, round, sqrt
``` |

50 | ```
} from 'mathjs'
``` |

51 | ```
``` |

52 | ```
// functions and constants
``` |

53 | ```
round(e, 3) // 2.718
``` |

54 | ```
atan2(3, -3) / pi // 0.75
``` |

55 | ```
log(10000, 10) // 4
``` |

56 | ```
sqrt(-4) // 2i
``` |

57 | ```
pow([[-1, 2], [3, 1]], 2) // [[7, 0], [0, 7]]
``` |

58 | ```
derivative('x^2 + x', 'x') // 2 * x + 1
``` |

59 | ```
``` |

60 | ```
// expressions
``` |

61 | ```
evaluate('12 / (2.3 + 0.7)') // 4
``` |

62 | ```
evaluate('12.7 cm to inch') // 5 inch
``` |

63 | ```
evaluate('sin(45 deg) ^ 2') // 0.5
``` |

64 | ```
evaluate('9 / 3 + 2i') // 3 + 2i
``` |

65 | ```
evaluate('det([-1, 2; 3, 1])') // -7
``` |

66 | ```
``` |

67 | ```
// chaining
``` |

68 | ```
chain(3)
``` |

69 | ```
.add(4)
``` |

70 | ```
.multiply(2)
``` |

71 | ```
.done() // 14
``` |

72 | ```
```
``` |

73 | ```
``` |

74 | ```
See the [Getting Started](https://mathjs.org/docs/getting_started.html) for a more detailed tutorial.
``` |

75 | ```
``` |

76 | ```
``` |

77 | ```
## Browser support
``` |

78 | ```
``` |

79 | ```
Math.js works on any ES6 compatible JavaScript engine, including node.js, Chrome, Firefox, Safari, and Edge.
``` |

80 | ```
``` |

81 | ```
``` |

82 | ```
## Documentation
``` |

83 | ```
``` |

84 | ```
- [Getting Started](https://mathjs.org/docs/getting_started.html)
``` |

85 | ```
- [Examples](https://mathjs.org/examples/index.html)
``` |

86 | ```
- [Overview](https://mathjs.org/docs/index.html)
``` |

87 | ```
- [History](https://mathjs.org/history.html)
``` |

88 | ```
``` |

89 | ```
``` |

90 | ```
## Build
``` |

91 | ```
``` |

92 | ```
First clone the project from github:
``` |

93 | ```
``` |

94 | ```
git clone git@github.com:josdejong/mathjs.git
``` |

95 | ```
cd mathjs
``` |

96 | ```
``` |

97 | ```
Install the project dependencies:
``` |

98 | ```
``` |

99 | ```
npm install
``` |

100 | ```
``` |

101 | ```
Then, the project can be build by executing the build script via npm:
``` |

102 | ```
``` |

103 | ```
npm run build
``` |

104 | ```
``` |

105 | ```
This will build ESM output, CommonJS output, and the bundle math.js
``` |

106 | ```
from the source files and put them in the folder lib.
``` |

107 | ```
``` |

108 | ```
``` |

109 | ```
## Develop
``` |

110 | ```
``` |

111 | ```
When developing new features for mathjs, it is good to be aware of the following background information.
``` |

112 | ```
``` |

113 | ```
### Code
``` |

114 | ```
``` |

115 | ```
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.
``` |

116 | ```
``` |

117 | ```
### Architecture
``` |

118 | ```
``` |

119 | ```
What mathjs tries to achieve is to offer an environment where you can do calculations with mixed data types,
``` |

120 | ```
like multiplying a regular `number` with a `Complex` number or a `BigNumber`, and work with all of those in matrices.
``` |

121 | ```
Mathjs also allows to add a new data type, like say `BigInt`, with little effort.
``` |

122 | ```
``` |

123 | ```
The solution that mathjs uses has two main ingredients:
``` |

124 | ```
``` |

125 | ```
- **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`.
``` |

126 | ```
``` |

127 | ```
- **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.
``` |

128 | ```
``` |

129 | ```
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.
``` |

130 | ```
``` |

131 | ```
### Implementing a new function
``` |

132 | ```
``` |

133 | ```
A common case is to implement a new function. This involves the following steps:
``` |

134 | ```
``` |

135 | ```
- Implement the function in the right category, for example `./src/function/arithmetic/myNewFunction.js`, where you can replace `arithmetic` with the proper category, and `myNewFunction` with the name of the new function. Add the new function to the index files `./src/factoriesAny.js` and possibly `./src/factoriesNumber.js`.
``` |

136 | ```
- Write documentation on the function in the source code comment of `myNewFunction.js`. This documentation is used to auto generate documentation on the website.
``` |

137 | ```
- Write embedded documentation for the new function in `./src/expression/embeddedDocs/function/arithmetic/myNewFunction.js`. Add the new documentation to the index file `./src/expression/embeddedDocs/embeddedDocs.js`.
``` |

138 | ```
- Write unit tests for the function in `./test/unit-tests/function/arithmetic/myNewFunction.test.js`.
``` |

139 | ```
- Write the necessary TypeScript definitions for the new function in `./types/index.d.ts`, and write tests for it in `./test/typescript-tests/testTypes.ts`. This is described in [./types/EXPLANATION.md](./types/EXPLANATION.md).
``` |

140 | ```
- Ensure the code style is ok by running `npm run lint` (run `npm run format` to fix the code style automatically).
``` |

141 | ```
``` |

142 | ```
``` |

143 | ```
### Build scripts
``` |

144 | ```
``` |

145 | ```
The build script currently generates two types of output:
``` |

146 | ```
``` |

147 | ```
- **any**, generate entry points to create full versions of all functions
``` |

148 | ```
- **number**: generating and entry points to create lightweight functions just supporting `number`
``` |

149 | ```
``` |

150 | ```
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)`.
``` |

151 | ```
``` |

152 | ```
``` |

153 | ```
## Test
``` |

154 | ```
``` |

155 | ```
To execute tests for the library, install the project dependencies once:
``` |

156 | ```
``` |

157 | ```
npm install
``` |

158 | ```
``` |

159 | ```
Then, the tests can be executed:
``` |

160 | ```
``` |

161 | ```
npm test
``` |

162 | ```
``` |

163 | ```
Additionally, the tests can be run on FireFox using [headless mode](https://developer.mozilla.org/en-US/Firefox/Headless_mode):
``` |

164 | ```
``` |

165 | ```
npm run test:browser
``` |

166 | ```
``` |

167 | ```
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:
``` |

168 | ```
``` |

169 | ```
npm run test:browserstack
``` |

170 | ```
``` |

171 | ```
You can separately run the code linter, though it is also executed with `npm test`:
``` |

172 | ```
``` |

173 | ```
npm run lint
``` |

174 | ```
``` |

175 | ```
To automatically fix linting issue, run:
``` |

176 | ```
``` |

177 | ```
npm run format
``` |

178 | ```
``` |

179 | ```
To test code coverage of the tests:
``` |

180 | ```
``` |

181 | ```
npm run coverage
``` |

182 | ```
``` |

183 | ```
To see the coverage results, open the generated report in your browser:
``` |

184 | ```
``` |

185 | ```
./coverage/lcov-report/index.html
``` |

186 | ```
``` |

187 | ```
``` |

188 | ```
### Continuous integration testing
``` |

189 | ```
``` |

190 | ```
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.
``` |

191 | ```
``` |

192 | ```
[![BrowserStack](https://raw.github.com/josdejong/mathjs/master/misc/browserstack.png)](https://www.browserstack.com)
``` |

193 | ```
``` |

194 | ```
Thanks Github Actions and BrowserStack for the generous free hosting of this open source project!
``` |

195 | ```
``` |

196 | ```
## License
``` |

197 | ```
``` |

198 | ```
mathjs is published under the Apache 2.0 license:
``` |

199 | ```
``` |

200 | ```
```
``` |

201 | ```
Copyright (C) 2013-2024 Jos de Jong <wjosdejong@gmail.com>
``` |

202 | ```
``` |

203 | ```
Licensed under the Apache License, Version 2.0 (the "License");
``` |

204 | ```
you may not use this file except in compliance with the License.
``` |

205 | ```
You may obtain a copy of the License at
``` |

206 | ```
``` |

207 | ```
https://www.apache.org/licenses/LICENSE-2.0
``` |

208 | ```
``` |

209 | ```
Unless required by applicable law or agreed to in writing, software
``` |

210 | ```
distributed under the License is distributed on an "AS IS" BASIS,
``` |

211 | ```
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
``` |

212 | ```
See the License for the specific language governing permissions and
``` |

213 | ```
limitations under the License.
``` |

214 | ```
```
``` |

215 | ```
``` |

216 | ```
mathjs contains a JavaScript port of the [CSparse](https://github.com/DrTimothyAldenDavis/SuiteSparse/tree/dev/CSparse/Source) library, published under the LGPL-2.1+ license:
``` |

217 | ```
``` |

218 | ```
```
``` |

219 | ```
CSparse: a Concise Sparse matrix package.
``` |

220 | ```
Copyright (c) 2006, Timothy A. Davis.
``` |

221 | ```
http://www.suitesparse.com
``` |

222 | ```
``` |

223 | ```
--------------------------------------------------------------------------------
``` |

224 | ```
``` |

225 | ```
CSparse is free software; you can redistribute it and/or
``` |

226 | ```
modify it under the terms of the GNU Lesser General Public
``` |

227 | ```
License as published by the Free Software Foundation; either
``` |

228 | ```
version 2.1 of the License, or (at your option) any later version.
``` |

229 | ```
``` |

230 | ```
CSparse is distributed in the hope that it will be useful,
``` |

231 | ```
but WITHOUT ANY WARRANTY; without even the implied warranty of
``` |

232 | ```
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
``` |

233 | ```
Lesser General Public License for more details.
``` |

234 | ```
``` |

235 | ```
You should have received a copy of the GNU Lesser General Public
``` |

236 | ```
License along with this Module; if not, write to the Free Software
``` |

237 | ```
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
``` |

238 | ```
```
``` |