README.md (7501B)
1 # Complex.js - ℂ in JavaScript 2 3 [](https://npmjs.org/package/complex.js) 4 5 [](https://travis-ci.org/infusion/Complex.js) 6 [](http://opensource.org/licenses/MIT) 7 8 Complex.js is a well tested JavaScript library to work with [complex number arithmetic](https://www.xarg.org/book/analysis/complex-numbers/) in JavaScript. It implements every elementary complex number manipulation function and the API is intentionally similar to [Fraction.js](https://github.com/infusion/Fraction.js). Furthermore, it's the basis of [Polynomial.js](https://github.com/infusion/Polynomial.js) and [Math.js](https://github.com/josdejong/mathjs). 9 10 11 Examples 12 === 13 14 ```js 15 let Complex = require('complex.js'); 16 17 let c = new Complex("99.3+8i"); 18 c.mul({re: 3, im: 9}).div(4.9).sub(3, 2); 19 ``` 20 21 A classical use case for complex numbers is solving quadratic equations `ax² + bx + c = 0` for all `a, b, c ∈ ℝ`: 22 23 ```js 24 25 function quadraticRoot(a, b, c) { 26 let sqrt = Complex(b * b - 4 * a * c).sqrt() 27 let x1 = Complex(-b).add(sqrt).div(2 * a) 28 let x2 = Complex(-b).sub(sqrt).div(2 * a) 29 return {x1, x2} 30 } 31 32 // quadraticRoot(1, 4, 5) -> -2 ± i 33 ``` 34 35 Parser 36 === 37 38 Any function (see below) as well as the constructor of the *Complex* class parses its input like this. 39 40 You can pass either Objects, Doubles or Strings. 41 42 Objects 43 --- 44 ```javascript 45 new Complex({re: real, im: imaginary}); 46 new Complex({arg: angle, abs: radius}); 47 new Complex({phi: angle, r: radius}); 48 new Complex([real, imaginary]); // Vector/Array syntax 49 ``` 50 If there are other attributes on the passed object, they're not getting preserved and have to be merged manually. 51 52 Doubles 53 --- 54 ```javascript 55 new Complex(55.4); 56 ``` 57 58 Strings 59 --- 60 ```javascript 61 new Complex("123.45"); 62 new Complex("15+3i"); 63 new Complex("i"); 64 ``` 65 66 Two arguments 67 --- 68 ```javascript 69 new Complex(3, 2); // 3+2i 70 ``` 71 72 Attributes 73 === 74 75 Every complex number object exposes its real and imaginary part as attribute `re` and `im`: 76 77 ```javascript 78 let c = new Complex(3, 2); 79 80 console.log("Real part:", c.re); // 3 81 console.log("Imaginary part:", c.im); // 2 82 ``` 83 84 Functions 85 === 86 87 Complex sign() 88 --- 89 Returns the complex sign, defined as the complex number normalized by it's absolute value 90 91 Complex add(n) 92 --- 93 Adds another complex number 94 95 Complex sub(n) 96 --- 97 Subtracts another complex number 98 99 Complex mul(n) 100 --- 101 Multiplies the number with another complex number 102 103 Complex div(n) 104 --- 105 Divides the number by another complex number 106 107 Complex pow(exp) 108 --- 109 Returns the number raised to the complex exponent (Note: `Complex.ZERO.pow(0) = Complex.ONE` by convention) 110 111 Complex sqrt() 112 --- 113 Returns the complex square root of the number 114 115 Complex exp(n) 116 --- 117 Returns `e^n` with complex exponent `n`. 118 119 Complex log() 120 --- 121 Returns the natural logarithm (base `E`) of the actual complex number 122 123 _Note:_ The logarithm to a different base can be calculated with `z.log().div(Math.log(base))`. 124 125 double abs() 126 --- 127 Calculates the magnitude of the complex number 128 129 double arg() 130 --- 131 Calculates the angle of the complex number 132 133 Complex inverse() 134 --- 135 Calculates the multiplicative inverse of the complex number (1 / z) 136 137 Complex conjugate() 138 --- 139 Calculates the conjugate of the complex number (multiplies the imaginary part with -1) 140 141 Complex neg() 142 --- 143 Negates the number (multiplies both the real and imaginary part with -1) in order to get the additive inverse 144 145 Complex floor([places=0]) 146 --- 147 Floors the complex number parts towards zero 148 149 Complex ceil([places=0]) 150 --- 151 Ceils the complex number parts off zero 152 153 Complex round([places=0]) 154 --- 155 Rounds the complex number parts 156 157 boolean equals(n) 158 --- 159 Checks if both numbers are exactly the same, if both numbers are infinite they 160 are considered **not** equal. 161 162 boolean isNaN() 163 --- 164 Checks if the given number is not a number 165 166 boolean isFinite() 167 --- 168 Checks if the given number is finite 169 170 Complex clone() 171 --- 172 Returns a new Complex instance with the same real and imaginary properties 173 174 Array toVector() 175 --- 176 Returns a Vector of the actual complex number with two components 177 178 String toString() 179 --- 180 Returns a string representation of the actual number. As of v1.9.0 the output is a bit more human readable 181 182 ```javascript 183 new Complex(1, 2).toString(); // 1 + 2i 184 new Complex(0, 1).toString(); // i 185 new Complex(9, 0).toString(); // 9 186 new Complex(1, 1).toString(); // 1 + i 187 ``` 188 189 double valueOf() 190 --- 191 Returns the real part of the number if imaginary part is zero. Otherwise `null` 192 193 194 Trigonometric functions 195 === 196 The following trigonometric functions are defined on Complex.js: 197 198 | Trig | Arcus | Hyperbolic | Area-Hyperbolic | 199 |------|-------|------------|------------------| 200 | sin() | asin() | sinh() | asinh() | 201 | cos() | acos() | cosh() | acosh() | 202 | tan() | atan() | tanh() | atanh() | 203 | cot() | acot() | coth() | acoth() | 204 | sec() | asec() | sech() | asech() | 205 | csc() | acsc() | csch() | acsch() | 206 207 208 Geometric Equivalence 209 === 210 211 Complex numbers can also be seen as a vector in the 2D space. Here is a simple overview of basic operations and how to implement them with complex.js: 212 213 New vector 214 --- 215 ```js 216 let v1 = new Complex(1, 0); 217 let v2 = new Complex(1, 1); 218 ``` 219 220 Scale vector 221 --- 222 ```js 223 scale(v1, factor):= v1.mul(factor) 224 ``` 225 226 Vector norm 227 --- 228 ```js 229 norm(v):= v.abs() 230 ``` 231 232 Translate vector 233 --- 234 ```js 235 translate(v1, v2):= v1.add(v2) 236 ``` 237 238 Rotate vector around center 239 --- 240 ```js 241 rotate(v, angle):= v.mul({abs: 1, arg: angle}) 242 ``` 243 244 Rotate vector around a point 245 --- 246 ```js 247 rotate(v, p, angle):= v.sub(p).mul({abs: 1, arg: angle}).add(p) 248 ``` 249 250 Distance to another vector 251 --- 252 ```js 253 distance(v1, v2):= v1.sub(v2).abs() 254 ``` 255 256 Constants 257 === 258 259 Complex.ZERO 260 --- 261 A complex zero value (south pole on the Riemann Sphere) 262 263 Complex.ONE 264 --- 265 A complex one instance 266 267 Complex.INFINITY 268 --- 269 A complex infinity value (north pole on the Riemann Sphere) 270 271 Complex.NAN 272 --- 273 A complex NaN value (not on the Riemann Sphere) 274 275 Complex.I 276 --- 277 An imaginary number i instance 278 279 Complex.PI 280 --- 281 A complex PI instance 282 283 Complex.E 284 --- 285 A complex euler number instance 286 287 Complex.EPSILON 288 --- 289 A small epsilon value used for `equals()` comparison in order to circumvent double imprecision. 290 291 292 Installation 293 === 294 Installing complex.js is as easy as cloning this repo or use one of the following commands: 295 296 ```bash 297 bower install complex.js 298 ``` 299 or 300 301 ```bash 302 npm install complex.js 303 ``` 304 305 Using Complex.js with the browser 306 === 307 ```html 308 <script src="complex.js"></script> 309 <script> 310 console.log(Complex("4+3i")); 311 </script> 312 ``` 313 314 Using Complex.js with require.js 315 === 316 ```html 317 <script src="require.js"></script> 318 <script> 319 requirejs(['complex.js'], 320 function(Complex) { 321 console.log(Complex("4+3i")); 322 }); 323 </script> 324 ``` 325 326 Coding Style 327 === 328 As every library I publish, complex.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library. 329 330 331 Testing 332 === 333 If you plan to enhance the library, make sure you add test cases and all the previous tests are passing. You can test the library with 334 335 ```bash 336 npm test 337 ``` 338 339 340 Copyright and licensing 341 === 342 Copyright (c) 2015-2022, [Robert Eisele](https://www.xarg.org/) 343 Dual licensed under the MIT or GPL Version 2 licenses.