UNPKG

10.3 kBMarkdownView Raw
1![math.js](https://raw.github.com/josdejong/mathjs/master/misc/img/mathjs.png)
2
3[https://mathjs.org](https://mathjs.org)
4
5Math.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/2023.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://camo.githubusercontent.com/7d9333b097b2f54a8957d126ab82937811489c9b75c3850f609985cf94cd29fe/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2532302d53706f6e736f722532306d652532306f6e2532304769744875622d6f72616e6765)](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
30Math.js can be used in both node.js and in the browser.
31
32Install math.js using [npm](https://www.npmjs.com/package/mathjs):
33
34 npm install mathjs
35
36Or 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
40Math.js can be used similar to JavaScript's built-in Math library. Besides that,
41math.js can evaluate
42[expressions](https://mathjs.org/docs/expressions/index.html)
43and supports
44[chained operations](https://mathjs.org/docs/core/chaining.html).
45
46```js
47import {
48 atan2, chain, derivative, e, evaluate, log, pi, pow, round, sqrt
49} from 'mathjs'
50
51// functions and constants
52round(e, 3) // 2.718
53atan2(3, -3) / pi // 0.75
54log(10000, 10) // 4
55sqrt(-4) // 2i
56pow([[-1, 2], [3, 1]], 2) // [[7, 0], [0, 7]]
57derivative('x^2 + x', 'x') // 2 * x + 1
58
59// expressions
60evaluate('12 / (2.3 + 0.7)') // 4
61evaluate('12.7 cm to inch') // 5 inch
62evaluate('sin(45 deg) ^ 2') // 0.5
63evaluate('9 / 3 + 2i') // 3 + 2i
64evaluate('det([-1, 2; 3, 1])') // -7
65
66// chaining
67chain(3)
68 .add(4)
69 .multiply(2)
70 .done() // 14
71```
72
73See the [Getting Started](https://mathjs.org/docs/getting_started.html) for a more detailed tutorial.
74
75
76## Browser support
77
78Math.js works on any ES6 compatible JavaScript engine, including node.js, Chrome, Firefox, Safari, and Edge.
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
91First clone the project from github:
92
93 git clone git@github.com:josdejong/mathjs.git
94 cd mathjs
95
96Install the project dependencies:
97
98 npm install
99
100Then, the project can be build by executing the build script via npm:
101
102 npm run build
103
104This will build ESM output, CommonJS output, and the bundle math.js
105from the source files and put them in the folder lib.
106
107
108## Develop
109
110When developing new features for mathjs, it is good to be aware of the following background information.
111
112### Code
113
114The 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
118What mathjs tries to achieve is to offer an environment where you can do calculations with mixed data types,
119like multiplying a regular `number` with a `Complex` number or a `BigNumber`, and work with all of those in matrices.
120Mathjs also allows to add a new data type, like say `BigInt`, with little effort.
121
122The 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
128At 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### Implementing a new function
131
132A common case is to implement a new function. This involves the following steps:
133
134- 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`.
135- Write documentation on the function in the source code comment of `myNewFunction.js`. This documentation is used to auto generate documentation on the website.
136- 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`.
137- Write unit tests for the function in `./test/unit-tests/function/arithmetic/myNewFunction.test.js`.
138- Write a TypeScript definition for the new function in `./types/index.d.ts`, and write tests for it in `./types/index.ts`. Normally, two definitions need to be added: one for the static function `math.myNewFunction(...)` and one for the chained API `math.chain(...).myNewFunction(...)`.
139- Ensure the code style is ok by running `npm run lint` (run `npm run format` to fix the code style automatically).
140
141
142### Build scripts
143
144The build script currently generates two types of output:
145
146- **any**, generate entry points to create full versions of all functions
147- **number**: generating and entry points to create lightweight functions just supporting `number`
148
149For 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)`.
150
151
152## Test
153
154To execute tests for the library, install the project dependencies once:
155
156 npm install
157
158Then, the tests can be executed:
159
160 npm test
161
162Additionally, the tests can be run on FireFox using [headless mode](https://developer.mozilla.org/en-US/Firefox/Headless_mode):
163
164 npm run test:browser
165
166To 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:
167
168 npm run test:browserstack
169
170You can separately run the code linter, though it is also executed with `npm test`:
171
172 npm run lint
173
174To automatically fix linting issue, run:
175
176 npm run format
177
178To test code coverage of the tests:
179
180 npm run coverage
181
182To see the coverage results, open the generated report in your browser:
183
184 ./coverage/lcov-report/index.html
185
186
187### Continuous integration testing
188
189Continuous 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.
190
191[![BrowserStack](https://raw.github.com/josdejong/mathjs/master/misc/browserstack.png)](https://www.browserstack.com)
192
193Thanks Github Actions and BrowserStack for the generous free hosting of this open source project!
194
195## License
196
197Copyright (C) 2013-2023 Jos de Jong <wjosdejong@gmail.com>
198
199Licensed under the Apache License, Version 2.0 (the "License");
200you may not use this file except in compliance with the License.
201You may obtain a copy of the License at
202
203 https://www.apache.org/licenses/LICENSE-2.0
204
205Unless required by applicable law or agreed to in writing, software
206distributed under the License is distributed on an "AS IS" BASIS,
207WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
208See the License for the specific language governing permissions and
209limitations under the License.