ndarray-ts

A lightweight N-dimensional array (ndarray) library for TypeScript and JavaScript, inspired by NumPy. This package provides a foundational NdArray class for efficient numerical operations on multi-dimensional data.

🚀 Features

ndarray-ts aims to provide core functionalities for working with N-dimensional arrays, including:

• Flexible Array Creation: Initialize arrays with custom data and shapes, or use convenience methods like zeros(), ones(), and arange().
• Multi-dimensional Indexing: Easily access and modify elements using multi-dimensional indices (e.g., arr.get(row, col), arr.set([row, col], value)).
• Reshaping: Change the dimensions of an array without altering its underlying data, as long as the total number of elements remains constant.
• Element-wise Arithmetic Operations: Perform addition, subtraction, multiplication, and division with other NdArray instances or scalar values.
• Matrix Multiplication (Dot Product): Supports dot product for 2D arrays.
• TypeScript Support: Fully typed for a better development experience.

📦 Installation

You can install ndarray-ts using npm:

npm install ndarray-ts
# or
yarn add ndarray-ts

💡 Usage

Here's how you can use the NdArray class in your TypeScript or JavaScript projects:

Importing the Library

import { NdArray } from "ndarray-ts";
// For CommonJS (Node.js):
const { NdArray } = require("ndarray-ts");

Array Creation

// Create a 2x3 array from a flat data array
const arr1 = new NdArray([1, 2, 3, 4, 5, 6], [2, 3]);
console.log("arr1 (2x3):\n", arr1.toString());
/*
Output:
NdArray(shape=2,3, data=[
  [1, 2, 3]
  [4, 5, 6]
])
*/

// Create a 3x2 array filled with zeros
const zerosArr = NdArray.zeros([3, 2]);
console.log("\nzerosArr (3x2):\n", zerosArr.toString());
/*
Output:
NdArray(shape=3,2, data=[
  [0, 0]
  [0, 0]
  [0, 0]
])
*/

// Create a 1D array with values from 10 (inclusive) to 20 (exclusive), stepping by 3
const rangeArr = NdArray.arange(10, 20, 3);
console.log("\nrangeArr (arange 10-20 step 3):\n", rangeArr.toString());
/*
Output:
NdArray(shape=6, data=[
  [10, 13, 16, 19]
])
*/

Accessing and Modifying Elements

const arr = new NdArray([10, 11, 12, 13, 14, 15], [2, 3]);
console.log("Original array:\n", arr.toString());

// Get an element at specific indices
console.log("Element at [0, 1]:", arr.get(0, 1)); // Output: 11

// Set an element at specific indices
arr.set([1, 2], 99);
console.log("Array after setting [1, 2] to 99:\n", arr.toString());
/*
Output:
NdArray(shape=2,3, data=[
  [10, 11, 12]
  [13, 14, 99]
])
*/

Reshaping Arrays

const originalArr = new NdArray([1, 2, 3, 4, 5, 6], [2, 3]);
console.log("Original array (2x3):\n", originalArr.toString());

// Reshape to a 3x2 array
const reshapedArr = originalArr.reshape([3, 2]);
console.log("Reshaped array (3x2):\n", reshapedArr.toString());
/*
Output:
NdArray(shape=3,2, data=[
  [1, 2]
  [3, 4]
  [5, 6]
])
*/

// Attempting to reshape to an incompatible size will throw an error
try {
    originalArr.reshape([2, 2]);
} catch (error: any) {
    console.error("Reshape Error:", error.message);
    // Output: Reshape Error: Cannot reshape array of size 6 into shape 2,2 with size 4
}

Element-wise Operations

const a = new NdArray([10, 20, 30, 40], [2, 2]);
const b = new NdArray([1, 2, 3, 4], [2, 2]);

console.log("Array A:\n", a.toString());
console.log("Array B:\n", b.toString());

// Addition
const sumArr = a.add(b);
console.log("\nA + B:\n", sumArr.toString());
/*
Output:
NdArray(shape=2,2, data=[
  [11, 22]
  [33, 44]
])
*/

// Scalar Multiplication
const scalarMult = a.multiply(5);
console.log("\nA * 5 (scalar):\n", scalarMult.toString());
/*
Output:
NdArray(shape=2,2, data=[
  [50, 100]
  [150, 200]
])
*/

Matrix Multiplication (Dot Product)

const matA = new NdArray([1, 2, 3, 4], [2, 2]); // Represents [[1, 2], [3, 4]]
const matB = new NdArray([5, 6, 7, 8], [2, 2]); // Represents [[5, 6], [7, 8]]

console.log("Matrix A:\n", matA.toString());
console.log("Matrix B:\n", matB.toString());

const dotProduct = matA.dot(matB);
console.log("\nMatrix A . Matrix B:\n", dotProduct.toString());
/*
Output:
NdArray(shape=2,2, data=[
  [19, 22]
  [43, 50]
])
*/
// Calculation:
// [[(1*5)+(2*7), (1*6)+(2*8)],
//  [(3*5)+(4*7), (3*6)+(4*8)]]
// = [[5+14, 6+16],
//    [15+28, 18+32]]
// = [[19, 22],
//    [43, 50]]

📖 API Reference

class NdArray

• constructor(data: number[], shape: number[]): Creates a new NdArray.
• static zeros(shape: number[]): NdArray: Creates an array filled with zeros.
• static ones(shape: number[]): NdArray: Creates an array filled with ones.
• static arange(start: number, stop: number, step?: number): NdArray: Creates an array with evenly spaced values.
• get(...indices: number[]): number: Retrieves the element at the given indices.
• set(indices: number[], value: number): void: Sets the element at the given indices.
• reshape(newShape: number[]): NdArray: Returns a new NdArray with the specified shape.
• add(other: NdArray | number): NdArray: Element-wise addition.
• subtract(other: NdArray | number): NdArray: Element-wise subtraction.
• multiply(other: NdArray | number): NdArray: Element-wise multiplication.
• divide(other: NdArray | number): NdArray: Element-wise division.
• dot(other: NdArray): NdArray: Matrix multiplication (for 2D arrays).
• toString(): string: Returns a string representation of the array.

🤝 Contributing

Contributions are welcome! If you have suggestions for improvements, new features, or bug fixes, please open an issue or submit a pull request on the GitHub repository.

❤️ Support & Share

If you find ndarray-ts helpful, please consider sharing your experience! Post about it on LinkedIn, Twitter, or any social media platform.

Tag me or the project so we can feature your post!!

Or simply drop me an email at: [email protected] – I’d love to hear how you are using this package!

Your support helps others discover this library and keeps the project growing!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.