npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

phasor.js

v2.1.0

Published

Complex numbers done right

Downloads

11

Readme

Phasor.js

Coverage Status

Phasor.js is a wasm (via Rust) implementation of complex numbers that strives to yield correct results.

Example

import {i, rect} from 'phasor.js';

i(Math.PI).exp().add(rect(1)); // approximately rect(0);

Motivation

Phasor.js was originally developed as part of Steady to provide the core complex algebra primitives required in the implementation of algorithms that solve electrical circuits.

While it wasn't Steady's goal to implement complex numbers from scratch, circumstances proved it necessary given the fact that, at the time (Feb 2018), no alternative library available on NPM was able to correctly handle edge cases such as complex numbers with infinite magnitude.

For example, all four alternatives tested[a][b][c][d] compute ∞i × -∞i to NaN instead of and three of them also generally fail to prevent overflow/underflow even in trivial expressions such as 1E200i / 1E200i and 1E-200i / 1E-200i.

Phasor.js on the other hand successfully passes all of the following assertions.

i(Infinity).mul(i(-Infinity)).ulpsEq(rect(Infinity));
i(1E200).div(i(1E200)).ulpsEq(rect(1));
i(1E-200).div(i(1E-200)).ulpsEq(rect(1));

In 2020, Phasor.js was re-implemented from scratch in Rust.

API Reference

rect(re, im = 0)

Constructs a complex number given it's real and imaginary parts.

polar(mag, ang = 0)

Constructs a complex number given it's magnitude and angle.

i(im = 0)

Constructs a purely imaginary number.

Example:

i(42).ulpsEq(rect(0, 42));

p.real()

Extracts the real part of a complex number.

Example:

rect(3).real() === 3;
rect(3, 4).real() === 3;

p.imag()

Extracts the imaginary part of a complex number.

Example:

rect(3).real() === 0;
rect(3, 4).imag() === 4;

p.norm()

Extracts the magnitude of a complex number.

Example:

rect(3, 4).norm() === 5;

p.angle()

Extracts the angle of a complex number.

Example:

rect(3, 4).angle() === Math.atan2(4, 3);

absDiffEq(c1, c2, e = Number.EPSILON)

Compares two complex numbers for approximate equality, optionally taking a positive residue.

relativeEq(c1, c2, e = Number.EPSILON, rel = Number.EPSILON)

Compares two complex numbers for approximate equality, optionally taking a positive residue and a maximum relative distance.

ulpsEq(c1, c2, e = Number.EPSILON, ulps = 4)

Compares two complex numbers for approximate equality, optionally taking a positive residue and the maximum distance of Units in the Last Place.

p.add(q)

Computes the addition of two complex numbers.

Example:

rect(3).add(rect(0, 4)).ulpsEq(rect(3, 4));

p.sub(q)

Computes the subtraction of two complex numbers.

Example:

rect(3).sub(rect(0, 4)).ulpsEq(rect(3, -4));

p.mul(q)

Computes the multiplication of two complex numbers.

Example:

rect(3).mul(rect(0, 4)).ulpsEq(i(12));

p.div(q)

Computes the division of two complex numbers.

Example:

rect(3).div(rect(0, 4)).ulpsEq(i(-0.75));

p.neg()

Computes the opposite of a complex number.

Example:

rect(3, 4).neg().ulpsEq(rect(-3, -4));

p.conj()

Computes the conjugate of a complex number.

Example:

rect(3, 4).conj().ulpsEq(rect(3, -4));

p.recip()

Computes the reciprocal of a complex number.

Example:

rect(3, 4).recip().ulpsEq(rect(3 / 25, -4 / 25));

p.exp()

Computes the exponential of a complex number.

Example:

rect(3, 4).exp().ulpsEq(polar(Math.exp(3), 4));

p.ln()

Computes the principal natural logarithm of a complex number.

Example:

rect(3, 4).ln().ulpsEq(rect(Math.log(5), Math.atan(4 / 3)));

p.log()

Computes the principal logarithm of a complex number to an arbitrary base.

Example:

rect(3, 4).log(10).ulpsEq(rect(Math.log10(5), Math.atan(4 / 3) / Math.log(10)));

p.sinh()

Computes the hyperbolic sine of a complex number.

Example:

const p = rect(3, 4);
const q = polar(
    -Math.hypot(Math.sinh(3), Math.sin(4)),
    Math.atan2(Math.tan(4), Math.tanh(3)),
);

p.sinh().ulpsEq(q);

p.cosh()

Computes the hyperbolic cosine of a complex number.

Example:

const p = rect(3, 4);
const q = polar(
    -Math.hypot(Math.sinh(3), Math.cos(4)),
    Math.atan2(Math.tan(4), 1 / Math.tanh(3)),
);

p.cosh().ulpsEq(q);

p.isNaN()

Returns true if either the imaginary or real part (or both) of a complex number is NaN.

Example:

console.assert(!i(0).isNaN());
console.assert(!i(1).isNaN());
console.assert(!i(1E-315).isNaN())
console.assert(!i(Infinity).isNaN());
console.assert(i(NaN).isNaN());

p.isInfinite()

Returns true if the magnitude of a complex number is Infinity.

Example:

console.assert(!i(0).isInfinite());
console.assert(!i(1).isInfinite());
console.assert(!i(1E-315).isInfinite())
console.assert(i(Infinity).isInfinite());
console.assert(!i(NaN).isInfinite());

p.isFinite()

Returns true if a complex number is neither NaN nor infinite.

Example:

console.assert(i(0).isFinite());
console.assert(i(1).isFinite());
console.assert(i(1E-315).isFinite())
console.assert(!i(Infinity).isFinite());
console.assert(!i(NaN).isFinite());

p.isZero()

Returns true if the magnitude of a complex number is zero.

Example:

console.assert(i(0).isZero());
console.assert(!i(1).isZero());
console.assert(!i(1E-315).isZero())
console.assert(!i(Infinity).isZero());
console.assert(!i(NaN).isZero());

p.isSubnormal()

Returns true if the magnitude of a complex number is subnormal.

Example:

console.assert(!i(0).isSubnormal());
console.assert(!i(1).isSubnormal());
console.assert(i(1E-315).isSubnormal())
console.assert(!i(Infinity).isSubnormal());
console.assert(!i(NaN).isSubnormal());

p.isNormal()

Returns true if a complex number is not NaN, infinite, zero, or subnormal.

Example:

console.assert(!i(0).isNormal());
console.assert(i(1).isNormal());
console.assert(!i(1E-315).isNormal())
console.assert(!i(Infinity).isNormal());
console.assert(!i(NaN).isNormal());

p.isReal()

Returns true if a complex number is purely real.

Example:

console.assert(rect(3).isReal());
console.assert(!rect(0, 4).isReal());
console.assert(!rect(3, 4).isReal());

p.isImaginary()

Returns true if a complex number is purely imaginary.

Example:

console.assert(!rect(3).isImaginary());
console.assert(rect(0, 4).isImaginary());
console.assert(!rect(3, 4).isImaginary());

Under the Hood

Complex numbers are represented under the hood by their magnitude and the tangent of its angle, which might seem unusual, but it's one of the main reasons why Phasor.js is able to yield numerically correct results.

The tangent of an angle has many advantages from the point of view of numerical algorithms than angles expressed in radians, the most important one being the fact that it makes it possible to implement most algorithms, in particular the four fundamental operations (add, sub, mul and div), without relying on any trigonometric function, which are highly non-linear and a major source of numerical error.

Phasor.js essentially takes advantage of the following two trigonometric identities that rely on the less non-linear square root function:

cos(tan(α)) ≡ 1 / sqrt(1 + α^2)
sin(tan(α)) ≡ sign(α) / sqrt(1 + 1 / α^2)

These identities are particularly convenient, because those square roots in the denominators can take advantage of the hypot algorithm, which efficiently avoids unnecessary over/underflows.