mabotkin/complex-js

Complex-js is a lightweight module that enables complex mathematics in JavaScript. It comes with every elementary function and all mathematical operators. It also includes many utility functions and common non-analytical functions such as the complex conjugate, the argument function, the absolute value function and many others.

Lastly, but most importantly, this module contains a compiler to parse human-readable expressions into native JavaScript functions. The compiler, accessible from Complex.parseFunction, accepts an arbitrary amount of parameters to pass to the function, specified by their human-readable names. Example usage can be found below in the section Parsing Human-Readable Expressions.

Although originally written for use in the browser, it can also now be used within Node.js.

Download

To install via npm, run:

npm install --save complex-js

To include this module in the Node.js environment, add the line:

var Complex = require('complex-js');

In the browser, use a script tag:

<script type="text/javascript" src="complex.min.js"></script>

Complex.js can now be included as an AMD module as well, and is available via bower:

bower install --save complex-js

Functions vs. Operators

Functions are denoted as Complex.staticMethod. For example, to evaluate the tangent of the imaginary unit, do the following:

console.log(Complex.tan(Complex(0, 1)));

All functions are static, meaning that they are called directly by the Complex namespace. Operators are non-static methods, which means they must be called by an instance of Complex. For example, to raise 1+5i to the power of 3 e^(pi i), do the following:

console.log(Complex(1, 5).pow(Complex.Polar(3, Math.PI)));

Notice how pow is a method of a Complex instance, and not of the namespace Complex. That's because it is an operator rather than a function in math. Non-static methods are denoted as Complex.prototype.nonStaticMethod. Now you can use symbolic operators as well. These include addition (+), subtraction (-), multiplication (*), division (/), modulii (%), powers (^), and equalities (=). Below is a couple examples.

// 1+5i
var onePlusFiveI = Complex(1, 0)['+'](Complex(0, 5));
// e^(pi i)*3
var negThree = Complex.exp(Complex(0, Math.PI))['*'](Complex(3, 0));

Coordinate Notation

Complex.js supports both cartesian and exponential notation. In order to declare a Complex number with cartesian coordinates, you can call the default constructor with the following arguments:

var onePlusFiveI = Complex(1, 5);

Declaring it with the new keyword is optional, since the constructor detects and corrects instantiation automatically. Optionally, you may supply the absolute value and the argument of the Complex number as well for the 3rd and 4th parameters, though this is not recommended. Exponential notation is supported through the secondary Polar constructor as such:

var negOne = Complex.Polar(1, Math.PI);

Note that this constructor does not support the new keyword and should never be called with it, as it does so internally.

Similarly, both notations are supported in the Complex.prototype.toString method. Simply call toString() for exponential (the default), or toString(true) for cartesian notation.

These strings can be used to reconstruct the Complex instances, but that will be covered in the next section.

Parsing Human-Readable Expressions

Complex.js also includes a compiler for human-readable expressions, which is very useful for constructing functions callable from JavaScript. Since it supports virtually any common notations and fully supports order of operations, it's very easy to use. It even normalizes implied multiplication and non-parenthetical grouping by default. A simple use-case example is below.

HTML:

<!DOCTYPE html>
	<head>
		<script type="text/javascript" src="complex.min.js"></script>
	</head>
	<body>
		<div>
			<span>Evaluate:</span>
			<input type="text" id="calc" value="(5+i)^(3e-5+10*sin(5i))"/>
		</div>
		<div>
			<span>Cartesian:</span>
			<span id="ans-cart"></span>
		</div>
		<div>
			<span>Exponential:</span>
			<span id="ans-expo"></span>
		</div>
		<script type="text/javascript">
			...
		</script>
	</body>
</html>

JavaScript:

var input = document.getElementById('calc'),
	cart = document.getElementById('ans-cart'),
	expo = document.getElementById('ans-expo');

input.addEventListener('change', function () {
	try {
		    //will throw an error if input is invalid
		var calc = Complex.parseFunction(input.value),
			//evaluate the compiled function for the answer
			ans = calc();

		//use the toString method
		cart.innerHTML = ans.toString(true);
		expo.innerHTML = ans.toString();
	} catch(error) {
		//if the parser throws an error, clear outputs and alert error
		cart.innerHTML = '';
		expo.innerHTML = '';
		alert(error.message);
	}
});

Note that the compiler creates a function rather than evaluating the expression that is compiled immediately. The function returned is high-performace, since it caches all constant expressions in the string so that they don't need to be re-evaluated with each call.

The following is an example where the compiler provides parameters for the compiled function:

// Node.js
var Complex = require('complex-js'),
	paramA = Complex(5, 1),
	paramB = Complex(3e-5, 0),
	paramC = Complex.Polar(5, Math.PI / 2),
	// human-readable variable names in expression
	complexFunc = 'a^(b+10*sin(c))',
	// array of parameters for function is order-dependent
	jsFunc = Complex.parseFunction(complexFunc, ['b', 'a', 'c']),
	// how to pass parameters to compiled function
	output = jsFunc(paramB, paramA, paramC);

// output cartesian form as string
console.log(output.toString(true));
// -1.85444755246657E-64+1.5844569641866693E-64 i

The Complex.parseFunction method can also reconstruct a Complex number from a string created by Complex.toString. See below for a demonstration:

var fivePlusIStr = Complex(5, 1).toString(true), //store as cartesian
    fivePlusI = (Complex.parseFunction(fivePlusIStr))();

console.log(Complex(5, 1).equals(fivePlusI));
// true

Documentation

Constants

For convenience, but also used in many of the trigonometric methods.

Complex.ZERO - zero
Complex.ONE - one
Complex.I - i
Complex.NEG_I - negative i
Complex.PI - irrational constant "π"
Complex.E - irrational constant "e"
Complex.TWO - two
Complex.TWO_I - two i

Constructors

Complex(real, imag[, abs[, arg]])

The cartesian constructor for instances of the Complex class. Optionally call with new, but not required.

Arguments

real - A Number specifying the real value of the Complex number.
imag - A Number specifying the imaginary value of the Complex number.
abs - An optional Number specifying the absolute value of the Complex number. Not recommended unless accurately calculated.
arg - An optional Number specifying the argument of the Complex number. Not recommended unless accurately calculated.

Complex.Polar(abs, arg)

The exponential constructor for instances of the Complex class. Note Do not call this constructor with new.

Arguments

abs - A Number specifying the absolute value of the Complex number.
arg - A Number specifying the argument of the Complex number.

Note In order to access the components from the instance, examine the following demo code:

var complex = Complex(Math.random()*2-1,Math.random()*2-1);
console.log(
	complex.real(), // real part
	complex.imag(), // imaginary part
	complex.abs(),  // absolute value
	complex.arg()   // argument
);

Non-Static Methods

Complex.prototype.toString([cartesian])

The toString method for the Complex class. Outputs to exponential or cartesian form.

Arguments

cartesian - An optional Boolean specifying the output form. If truthy, it outputs as cartesian, otherwise it outputs as exponential.

Examples

var c1 = Complex(-3,0),
	c2 = Complex(0,-1),
	c3 = Complex(3,4),
	c4 = Complex(-2,-5);

console.log(c1.toString());
// "3 e^(3.141592653589793 i)"

console.log(c2.toString(true));
// "-i"

console.log(c3.toString());
// "5 e^(0.9272952180016123 i)"

console.log(c4.toString(true));
// "-2-5 i"

Complex.prototype.equals(complex)

Compares two complex numbers and determines whether they are approximately equal, taking into consideration truncation error.

Arguments

complex - An instance of the Complex class to which to compare.

Complex.prototype.re(), Complex.prototype.real()

Returns the real component as a Number.

Complex.prototype.im(), Complex.prototype.imag()

Returns the imaginary component as a Number.

Complex.prototype.abs(), Complex.prototype.mag()

Returns the magnitude as a Number.

Complex.prototype.arg(), Complex.prototype.angle()

Returns the argument as a Number.

Complex.prototype.rAdd(real)

Adds a Complex number and a Number.

Arguments

real - A Number to add.

Complex.prototype.add(complex), Complex.prototype['+'](complex)

Adds two Complex numbers.

Arguments

complex - An instance of the Complex class to add.

Complex.prototype.rSub(real)

Subtracts a Number from a Complex number.

Arguments

real - A Number to subtract.

Complex.prototype.sub(complex), Complex.prototype['-'](complex)

Subtracts a Complex number from another.

Arguments

complex - An instance of the Complex class to subtract.

Complex.prototype.rMult(real)

Multiplies a Complex number and a Number.

Arguments

real - A Number to multiply.

Complex.prototype.mult(complex), Complex.prototype['*'](complex)

Multiplies two Complex numbers.

Arguments

complex - An instance of the Complex class to multiply.

Complex.prototype.rDiv(real)

Divides a Complex number by a Number.

Arguments

real - A Number by which to divide.

Complex.prototype.div(complex), Complex.prototype['/'](complex)

Divides a Complex number by another.

Arguments

complex - An instance of the Complex class by which to divide.

Complex.prototype.rMod(real)

Applies a Real Modulus to a Complex number by cartesian coordinates.

Arguments

real - A Number to for the modulus.

Complex.prototype.mod(complex), Complex.prototype['%'](complex)

Applies a Complex Modulus to a Complex number by cartesian coordinates.

Arguments

complex - An instance of the Complex class for the modulus.

Complex.prototype.rPow(real)

Raises a Complex number to a Real power.

Arguments

real - A Number by which to raise.

Complex.prototype.pow(complex), Complex.prototype['^'](complex)

Raises a Complex number to a Complex power.

Arguments

complex - An instance of the Complex class by which to raise.

Static Methods

Complex.neg(complex)

Returns the negative of complex.

Arguments

complex - An instance of the Complex class to negate.

Complex.re(complex)

Returns the real component of complex as an instance of Complex. The real value is stored in the real component of the returned instance.

Arguments

complex - An instance of the Complex class.

Complex.im(complex)

Returns the imaginary component of complex as an instance of Complex. The imaginary value is stored in the real component of the returned instance.

Arguments

complex - An instance of the Complex class.

Complex.abs(complex)

Returns the absolute value of complex. The absolute value is stored in the real component of the returned instance.

Arguments

complex - An instance of the Complex class.

Complex.arg(complex)

Returns the argument of complex. The argument is stored in the real component of the returned instance.

Arguments

complex - An instance of the Complex class.

Complex.conj(complex)

Returns the conjugate of complex.

Arguments

complex - An instance of the Complex class to conjugate.

Complex.norm(complex)

Returns the unit complex number with the same argument as complex. If the magnitude of complex is 0, then an instance of Complex is returned with a magnitude of NaN and an argument of 0.

Arguments

complex - An instance of the Complex class to normalize.

Complex.floor(complex)

Rounds down the cartesian components of complex.

Arguments

complex - An instance of the Complex class.

Complex.ceil(complex)

Rounds up the cartesian components of complex.

Arguments

complex - An instance of the Complex class.

Complex.round(complex)

Rounds the cartesian components of complex to the nearest integers.

Arguments

complex - An instance of the Complex class.

Complex.iPart(complex)

Returns the integer parts of the cartesian coordinates in complex. This floors positive components and ceilings negative components.

Arguments

complex - An instance of the Complex class.

Complex.fPart(complex)

Returns the fractional parts of the cartesian coordinates in complex.

Arguments

complex - An instance of the Complex class.

Complex.square(complex)

Returns the square of complex.

Arguments

complex - An instance of the Complex class.

Complex.cube(complex)

Returns the cube of complex.

Arguments

complex - An instance of the Complex class.

Complex.sqrt(complex)

Returns the square root of complex.

Arguments

complex - An instance of the Complex class.

Complex.cbrt(complex)

Returns the cube root of complex.

Arguments

complex - An instance of the Complex class.

Complex.exp(complex)

Returns the exponent function of complex, i.e. e^complex

Arguments

complex - An instance of the Complex class.

Complex.log(complex)

Returns the natural logarithm of complex.

Arguments

complex - An instance of the Complex class.

Complex.gamma(complex)

Returns the gamma function of complex. Note This function is not guaranteed to be accurate enough for the Complex.prototype.equals method to return true when compared to expected results.

Arguments

complex - An instance of the Complex class.

Complex.fact(complex)

Returns the factorial of complex. Note This function is not guaranteed to be accurate enough for the Complex.prototype.equals method to return true when compared to expected results.

Arguments

complex - An instance of the Complex class.

Complex.cos(complex)

Returns the cosine of complex.

Arguments

complex - An instance of the Complex class.

Complex.sin(complex)

Returns the sine of complex.

Arguments

complex - An instance of the Complex class.

Complex.tan(complex)

Returns the tangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.sec(complex)

Returns the secant of complex.

Arguments

complex - An instance of the Complex class.

Complex.csc(complex)

Returns the cosecant of complex.

Arguments

complex - An instance of the Complex class.

Complex.cot(complex)

Returns the cotangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.arccos(complex)

Returns the arccosine of complex.

Arguments

complex - An instance of the Complex class.

Complex.arcsin(complex)

Returns the arcsine of complex.

Arguments

complex - An instance of the Complex class.

Complex.arctan(complex)

Returns the arctangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.arcsec(complex)

Returns the arcsecant of complex.

Arguments

complex - An instance of the Complex class.

Complex.arccsc(complex)

Returns the arccosecant of complex.

Arguments

complex - An instance of the Complex class.

Complex.arccot(complex)

Returns the arccotangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.cosh(complex)

Returns the hyperbolic cosine of complex.

Arguments

complex - An instance of the Complex class.

Complex.sinh(complex)

Returns the hyperbolic sine of complex.

Arguments

complex - An instance of the Complex class.

Complex.tanh(complex)

Returns the hyperbolic tangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.sech(complex)

Returns the hyperbolic secant of complex.

Arguments

complex - An instance of the Complex class.

Complex.csch(complex)

Returns the hyperbolic cosecant of complex.

Arguments

complex - An instance of the Complex class.

Complex.coth(complex)

Returns the hyperbolic cotangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.arccosh(complex)

Returns the hyperbolic arccosine of complex.

Arguments

complex - An instance of the Complex class.

Complex.arcsinh(complex)

Returns the hyperbolic arcsine of complex.

Arguments

complex - An instance of the Complex class.

Complex.arctanh(complex)

Returns the hyperbolic arctangent of complex.

Arguments

complex - An instance of the Complex class.

Complex.arcsech(complex)

Returns the hyperbolic arcsecant of complex.

Arguments

complex - An instance of the Complex class.

Complex.arccsch(complex)

Returns the hyperbolic arccosecant of complex.

Arguments

complex - An instance of the Complex class.

Complex.arccoth(complex)

Returns the hyperbolic arccotangent of complex.

Arguments

complex - An instance of the Complex class.

Misc. Static Methods

Complex.min(complex_1[, complex_2...])

Returns the first complex instance with the smallest absolute value.

Arguments

complex_n - An instance of the Complex class.

Complex.max(complex_1[, complex_2...])

Returns the first complex instance with the largest absolute value.

Arguments

complex_n - An instance of the Complex class.

Complex.isNaN(complex)

Returns a Boolean; if any component of complex evaluates to NaN, this returns true, otherwise false.

Arguments

complex - An instance of the Complex class.

Complex.isFinite(complex)

Returns a Boolean; if the absolute value of complex is finite, this returns true, otherwise false.

Arguments

complex - An instance of the Complex class.

Complex.formatFunction(string)

Returns a sterilized human-readable expression that can be parsed by Complex.parseFunction if string is a valid math expression.

Arguments

string - A human-readable String of a math expression to be sterilized.

Complex.parseFunction(string[, params][, skipFormat])

Returns a JavaScript function bound with pre-compiled constants parsed from the human-readable math expression string. Optionally, an Array of human-readable parameters may be supplied to parse from the expression. Lastly, skipFormat is an optional Boolean that can be specified if string has already been formatted by Complex.formatFunction.

Arguments

string - A human-readable String of a math expression to be compiled.
params - An optional Array[String] of human-readable parameters to parse.
skipFormat - An optional Boolean to determine whether to skip pre-formatting.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Overview

Download

Functions vs. Operators

Coordinate Notation

Parsing Human-Readable Expressions

Documentation

Constructors

Non-Static Methods

Static Methods

Misc. Methods

Constants

Constructors

Complex(real, imag[, abs[, arg]])

Complex.Polar(abs, arg)

Non-Static Methods

Complex.prototype.toString([cartesian])

Complex.prototype.equals(complex)

Complex.prototype.re(), Complex.prototype.real()

Complex.prototype.im(), Complex.prototype.imag()

Complex.prototype.abs(), Complex.prototype.mag()

Complex.prototype.arg(), Complex.prototype.angle()

Complex.prototype.rAdd(real)

Complex.prototype.add(complex), Complex.prototype['+'](complex)

Complex.prototype.rSub(real)

Complex.prototype.sub(complex), Complex.prototype['-'](complex)

Complex.prototype.rMult(real)

Complex.prototype.mult(complex), Complex.prototype['*'](complex)

Complex.prototype.rDiv(real)

Complex.prototype.div(complex), Complex.prototype['/'](complex)

Complex.prototype.rMod(real)

Complex.prototype.mod(complex), Complex.prototype['%'](complex)

Complex.prototype.rPow(real)

Complex.prototype.pow(complex), Complex.prototype['^'](complex)

Static Methods

Complex.neg(complex)

Complex.re(complex)

Complex.im(complex)

Complex.abs(complex)

Complex.arg(complex)

Complex.conj(complex)

Complex.norm(complex)

Complex.floor(complex)

Complex.ceil(complex)

Complex.round(complex)

Complex.iPart(complex)

Complex.fPart(complex)

Complex.square(complex)

Complex.cube(complex)

Complex.sqrt(complex)

Complex.cbrt(complex)

Complex.exp(complex)

Complex.log(complex)

Complex.gamma(complex)

Complex.fact(complex)

Complex.cos(complex)

Complex.sin(complex)

Complex.tan(complex)

Complex.sec(complex)

Complex.csc(complex)

Complex.cot(complex)

Complex.arccos(complex)

Complex.arcsin(complex)

Complex.arctan(complex)

Complex.arcsec(complex)

Complex.arccsc(complex)

Complex.arccot(complex)

Complex.cosh(complex)

Complex.sinh(complex)

Complex.tanh(complex)

Complex.sech(complex)

Complex.csch(complex)

Complex.coth(complex)

Complex.arccosh(complex)

Complex.arcsinh(complex)

Complex.arctanh(complex)

Complex.arcsech(complex)

Complex.arccsch(complex)

Complex.arccoth(complex)

Misc. Static Methods

Complex.min(complex_1[, complex_2...])