@stdlib/stdlib

Standard library.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@stdlib/stdlib
3,9614990.2.02 months ago7 years agoMinified + gzip package size for @stdlib/stdlib in KB

Readme








<div class="image" align="center">
    <br>
    <br>
    <a href="https://stdlib.io/" />
        <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@9f7d30f089ecc458a8b836a75afab75caf5c0b36/docs/assets/logo_banner.svg" alt="stdlib logo">
    </a>
    <br>
    <br>
    <br>
    <br>
</div>




We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib.
stdlib (/ˈstændərd lɪb/ipa-english "standard lib") is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js. The library provides a collection of robust, high performance libraries for mathematics, statistics, data processing, streams, and more and includes many of the utilities you would expect from a standard library.
What sets stdlib apart is its fully decomposable architecture, allowing you to swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.
When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.
Want to join us in bringing numerical computing to the web? Start by starring the project. :star2:
Explore this GitHub repository for stdlib's source code and documentation. For help developing stdlib, see the development guidestdlib-development.
Thank you for being a part of our community! Your support is invaluable to us!

Resources

External Resources

Features

<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@203839353bc74297fe641207270f7917d2bda560/docs/assets/readme/base_special_math.png" alt="Demo showcasing special math functions">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@e13885087939c064c69aa43ee80ea52710de5591/docs/assets/readme/base_dists.png" alt="Demo showcasing probability distributions">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@83dcd0fad98883320a8b1efc801b2fc1ed2a003d/docs/assets/readme/base_prngs.png" alt="Demo showcasing PRNGs">
</div>
  • 200+ general utilities@stdlib/utils for data transformation, functional programming, and asynchronous control flow.
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@e6eeea31e49d6db1b6f57ae59d2988d4b427e285/docs/assets/readme/utils.png" alt="Demo showcasing general utilities">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@6970c8b4eb546a10712734d225c15863db9b2c92/docs/assets/readme/assert.png" alt="Demo showcasing assertion utilities">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@f71a38e62247e31dc47d248f6f1b3e434abeb971/docs/assets/readme/datasets.png" alt="Demo showcasing sample datasets">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@39d75174b24ea2a84828d9624643776a164478e4/docs/assets/readme/plot.png" alt="Demo showcasing plot API">
</div>
  • Native add-ons for interfacing with BLAS libraries, with pure JavaScript fallbacks.
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@efede6af3ef957da08838903b0558441263adf85/docs/assets/readme/base_blas.png" alt="Demo showcasing BLAS APIs">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@4833049f8d1895585bd51ec6fa97b8ca0d37c6fb/docs/assets/readme/benchmark.gif" alt="Demo showcasing benchmark framework">
</div>
  • REPL environment with integrated help and examples.
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@3864ae6f86bbc215956c0e667d82d49a6eaca780/docs/assets/readme/repl.gif" alt="Demo showcasing REPL environment">
</div>
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@e54894a93697653dda22d11cd0aec1ccb292b7b8/docs/assets/readme/bundled.png" alt="Demo showcasing browser support">
</div>
  • Every function is accompanied by TypeScripttypescript declaration files, ensuring type safety and facilitating intelligent code completion in IDEs.
<div class="image" align="center">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@f5f1f915a7178d9bc76a95d34afd799e6092ec3a/docs/assets/readme/typescript.png" alt="Demo showcasing TypeScript declaration files" >
</div>

Installation

To accommodate various use cases, stdlib can be consumed in multiple ways. The preferred means of consumption depends on your individual use case. We've provided some user stories to help you identify the best approach. 😃
While this project's installation instructions defaults to using npmnpm for package management, installation via other package managers, such as yarnyarn, should be a matter of simply swapping out npmnpm commands with those of the relevant package manager.

User Stories

  • I want to perform data analysis and data science tasks in JavaScript and Node.js, similar to how I might use Python, Julia, R, and MATLAB.
-   Install the entire project as a [command-line utility](#install_command_line_utility).
  • I am building a web application.
-   I plan on using [Browserify][browserify], [Webpack][webpack], and other bundlers for use in web browsers.

    -   Install [individual packages](#install_individual_packages). Installing the entire project is likely unnecessary and will lead to slower installation times.

-   I would like to **vendor** a custom bundle containing various stdlib functionality.

    -   Follow the steps for creating [custom bundles](#install_custom_bundles).

-   I would like to include stdlib functionality by just using a `script` tag.

    -   I would like to use ES Modules.
    
        -   Use an individual package's ES Module [build](#install_env_builds_esm).
        
    -   I would like to use a pre-built bundle (possibly via a CDN, such as [unpkg][unpkg] or [jsDelivr][jsdelivr]).
    
        -   Install (or consume via a CDN) an individual package's pre-built UMD [browser bundle](#install_env_builds_umd).

-   I am interested in using a substantial amount of functionality found in a top-level stdlib namespace and don't want to separately install hundreds of individual packages (e.g., if building an on-line calculator application and wanting all of stdlib's math functionality).

    -   Install one or more top-level [namespaces](#install_namespaces). Installing the entire project is likely unnecessary and will lead to slower installation times. Installing a top-level namespace is likely to mean installing functionality which will never be used; however, installing a top-level namespace is likely to be easier and less time-consuming than installing many individual packages separately.

        When bundling, installing a top-level namespace should not be a concern, as individual functionality can still be independently required/imported. Project installation times may, however, be somewhat slower.
-   I am interested in using various functionality found in stdlib.

    -   Install [individual packages](#install_individual_packages). Installing the entire project is likely unnecessary and will lead to slower installation times.

-   I would like to **vendor** stdlib functionality and avoid dependency trees.
    
    -   Install individual package UMD [bundles](#install_env_builds_nodejs).

-   I am interested in using a _substantial_ amount of functionality found in a top-level stdlib namespace and don't want to separately install hundreds of individual packages.

    -   Install one or more top-level [namespaces](#install_namespaces). Installing the entire project is likely unnecessary and will lead to slower installation times. Installing a top-level namespace is likely to mean installing functionality which will never be used; however, installing a top-level namespace is likely to be easier and less time-consuming than installing many individual packages separately.
  • I am using Deno.
-   Import [individual packages](#install_env_builds_deno) using pre-built Deno builds.
-   Consume a pre-built [browser bundles](#install_env_builds_umd) via a CDN, such as [unpkg][unpkg] or [jsDelivr][jsdelivr].
  • I want to hack at stdlib, possibly even creating customized builds to link to platform-specific native libraries (such as Intel's MKL or some other numerical library).
-   Install the project as a [system library](#install_system_library) by cloning this repository and following the [installation][stdlib-development] instructions as described in the [development guide][stdlib-development].

Complete Library

To install the entire project as a library or application dependency,

$ npm install @stdlib/stdlib

Once installed, stdlib packages can be individually required/imported to minimize load times and decrease bundle sizes. For example, to use require
var ndarray = require( '@stdlib/ndarray/array' );

var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>

and to use import

import ndarray from '@stdlib/ndarray/array';

var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>

Individual Packages

stdlib is designed to allow decomposition of the main project into individual packages which can be independently consumed. Accordingly, users of the project can avoid installing all project functionality and only install the exact functionality they need.
To install individual packages, replace forward slashes / after @stdlib/ with hyphens -. For example,

$ npm install @stdlib/ndarray-array

Once installed, individual packages can be required/imported. For example, to use require
var ndarray = require( '@stdlib/ndarray-array' );

var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>

and to use import

import ndarray from '@stdlib/ndarray-array';

var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>

Namespaces

stdlib is comprised of various top-level namespaces (i.e., collections of related functionality united by common themes). For example, to install all math functionality found in the top-level math namespace,

$ npm install @stdlib/math

Once installed, packages within a top-level namespace can be individually required/imported to minimize load times and decrease bundle sizes. For example, to use require
var sin = require( '@stdlib/math/base/special/sin' );

var v = sin( 3.14 );
// returns <number>

and to use import

import sin from '@stdlib/math/base/special/sin';

var v = sin( 3.14 );
// returns <number>

Note: installing nested namespaces found within top-level namespaces (e.g., math/base) is not supported. Consider installing individual packages or the relevant top-level namespace.

Command-line Utility

To install globally for use as a command-line utility and/or use the REPL@stdlib/repl,

$ npm install -g @stdlib/stdlib

which will expose the stdlib command. For example, to see available sub-commands

$ stdlib help

and to run the REPL@stdlib/repl

$ stdlib repl

Environment Builds

ES Modules

To use ES Modules via a <script> tag, use ES Module builds available in each package's repository via a dedicated esm branch (e.g., see the esm@stdlib/math-base-special-erf-esm branch for @stdlib/math-base-special-erf@stdlib/math-base-special-erf-esm). For example,

<script type="module">
import linspace from 'https://cdn.jsdelivr.net/gh/stdlib-js/array-base-linspace@esm/index.mjs';
import erf from 'https://cdn.jsdelivr.net/gh/stdlib-js/math-base-special-erf@esm/index.mjs';

const x = linspace( -10.0, 10.0, 100 );

for ( let i = 0; i < x.length; i++ ) {
    console.log( 'x: %d, erf(x): %d', x[ i ], erf( x[ i ] ) );
}
</script>

Deno

To use individual packages in Deno, use Deno builds available in each package's repository via a dedicated deno branch (e.g., see the deno@stdlib/ndarray-array-deno branch for @stdlib/ndarray-array@stdlib/ndarray-array-deno). For example,

import ndarray from 'https://cdn.jsdelivr.net/gh/stdlib-js/ndarray-array@deno/mod.js';

var arr = ndarray( [ [ 1, 2 ], [ 3, 4 ] ] );
// returns <ndarray>
````


<a name="install_env_builds_jquery"></a>

#### jQuery-like Bundle

For those wanting a jQuery-like bundle, one can use pre-built distributable UMD bundles for use in browser environments or as shared ("vendored") libraries in server environments available in each package's repository via a dedicated `umd` branch. See sections [UMD](#install_env_builds_umd) and [Node.js](#install_env_builds_nodejs) for more details.

<a name="install_env_builds_umd"></a>

#### UMD

To use UMD bundles either via a `<script>` tag or in [Observable][observable], use UMD **browser builds** available in each package's repository via a dedicated `umd` branch (e.g., see the [`umd`][@stdlib/math-base-special-erf-umd] branch for [`@stdlib/math-base-special-erf`][@stdlib/math-base-special-erf-umd]). For example,

<!-- run-disable -->

```html
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/stdlib-js/array-base-linspace@umd/browser.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/gh/stdlib-js/math-base-special-erf@umd/browser.js"></script>
<script type="text/javascript">
(function () {

var x = linspace( -10.0, 10.0, 100 );

for ( var i = 0; i < x.length; i++ ) {
    console.log( 'x: %d, erf(x): %d', x[ i ], erf( x[ i ] ) );
}

})();
</script>

Node.js

To vendor stdlib functionality and avoid installing dependency trees, use UMD server builds available in each package's repository via a dedicated umd branch (e.g., see the umd@stdlib/math-base-special-erf-umd branch for @stdlib/math-base-special-erf@stdlib/math-base-special-erf-umd). For example,

var linspace = require( '/path/to/vendor/umd/@stdlib/array-base-linspace' );
var erf = require( '/path/to/vendor/umd/@stdlib/math-base-special-erf' );

var x = linspace( -10.0, 10.0, 100 );

for ( var i = 0; i < x.length; i++ ) {
    console.log( 'x: %d, erf(x): %d', x[ i ], erf( x[ i ] ) );
}

Custom Bundles

To create a custom bundle based on project needs,
  1. follow the downloadstdlib-development, configurationstdlib-development, and installationstdlib-development instructions as described in the development guidestdlib-development.

  1. navigate to the local installation directory.

  1. run the following command to print help documentation for providing a list of stdlib package names to bundle
<!-- run-disable -->

```bash
$ NODE_PATH=./lib/node_modules node ./bin/cli bundle-pkg-list -- -h
```
  1. modify and run the above command with the list of packages to bundle
<!-- run-disable -->

```bash
$ NODE_PATH=./lib/node_modules node ./bin/cli bundle-pkg-list -- <pkg> <pkg> <pkg> ...
```



Upon generating a bundle, the bundle can be loaded via a <script> tag as described above for pre-built distributable UMD bundles.

System Library

To install as a system library (e.g., for the purposes of creating custom builds), follow the downloadstdlib-development, configurationstdlib-development, and installationstdlib-development instructions as described in the development guidestdlib-development.

Prerequisites

Installing and running stdlib for use in Node.jsnode-js requires the following prerequisites:

Most functionality in stdlib is implemented in JavaScript and no further prerequisites are required to use stdlib (i.e., you can safely avoid installing any additional prerequisites); however, some implementations try to capture performance benefits by using native bindingsnode-js-add-ons and/or WebAssemblywebassembly. While not required to run stdlib, as every stdlib implementation has a JavaScript fallback, the following dependencies are required for building native add-ons, including linking to BLAS and LAPACK libraries:

While not required to run stdlib, the following dependencies are required for automatically downloading external libraries:

The following external libraries can be automatically downloaded and compiled from source using make:

Contributing

First time contributor?

Already an expert?
  • Fork the repository.

  • Clone the forked repository
```bash
$ git clone --depth=1 https://github.com/<username>/stdlib.git
```

where `<username>` is your GitHub username.
  • Navigate to the stdlib directory
```bash
$ cd stdlib
```
  • Install dependencies
```bash
$ make install-node-modules
```
  • Initialize your stdlib development environment
```bash
$ make init
```

Sponsors

stdlib development is generously supported by the following sponsors...
<br>
<a href="https://labs.quansight.org/">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@2719e1d3ecab2cc29985bca35fd33594e65adb55/docs/assets/sponsors/quansight_labs_logo.png" alt="Quansight Labs">
</a>
<br>
<br>

Are you interested in supporting stdlib? If so, join our Open Collectiveopen-collective-stdlib!



Users

The following organizations and key stakeholders trust and depend on stdlib...
<br>
<a href="https://www.cmu.edu/">
    <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@1c8c7dbc9d081eeb13e16c62764f27a65c6553f8/docs/assets/misc/cmu_logo.png" alt="Carnegie Mellon University">
</a>
<br>
<br>

Does your organization or company use stdlib? If so, we'd love to hear from you!


Governance

For information about the governance of the stdlib project, see GOVERNANCE.mdstdlib-governance.

License

See LICENSEstdlib-license.

Copyright

Copyright © 2016-2024. The Stdlib Authorsstdlib-authors.



Status

Version


!git tagtag-imagetag-url !NPM versionnpm-imagenpm-url !Node.js versionnode-imagenode-url









Community

!Chatchat-imagechat-url