Source: complex.mjs

  1. // @ts-check
  3. /**
  4.  * @typedef {{real: number, imag: number}} Cobj
  5.  * An object representing a complex number with real and imaginary parts.
  6.  */
  8. /**
  9.  * @typedef {Int8Array | Uint8Array | Uint8ClampedArray | Int16Array |
  10.  * Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array |
  11.  * BigInt64Array | BigUint64Array} TypedArray
  12.  * A union type representing all possible TypedArrays.
  13.  */
  15. /**
  16.  * @template {Typed<TypedArray>} T
  17.  * @typedef {T} Typed A generic type representing a TypedArray.
  18.  */
  20. /**
  21.  * @template T
  22.  * @typedef {function(new:T, ...any)} Newable
  23.  * A constructor type that can be instantiated with the `new` keyword.
  24.  */
  26. /**
  27.  * @typedef {function(new:Complex, number, number)} TC
  28.  * A constructor for typeof Complex.
  29.  * @param {number} [re=0] The real part of the complex number.
  30.  * @param {number} [im=0] The imaginary part of the complex number.
  31.  */
  33. /**
  34.  * @template {Ctor<TC>} C
  35.  * @typedef {C} Ctor A generic type representing a `Complex` constructor.
  36.  */
  38. /**
  39.  * @template {TC} C
  40.  * @typedef {InstanceType<C>} Cinst
  41.  * A generic type representing an instance of a constructor `Complex`.
  42.  */
  44. /**
  45.  * @template {Ctor<TC>} C
  46.  * @typedef {Ctor<C> | {} | void} Cvoid
  47.  * A union type representing either a constructor `Complex`, an object, or void.
  48.  * Used to hint that a static method can also be invoked "bare".
  49.  */
  51. /**
  52.  * Type of callback Complex.compare().
  53.  * @callback Compare
  54.  * @param {Complex} a The first complex number to compare.
  55.  * @param {Cobj} b The second complex number to compare.
  56.  * @return {number} -1 if a < b, 0 if a == b, or +1 if a > b.
  57.  */
  59. /**
  60.  * An immutable complex number class with real and imaginary parts.
  61.  * @name Complex
  62.  * @class Complex
  63.  */
  64. export default class Complex {
  65.     /**
  66.      * The cached hashcode for this complex number.
  67.      * @type {number | null}
  68.      */
  69.     #hashCode = null;
  71.     /**
  72.      * The cached string representation for this complex number.
  73.      * @type {string | null}
  74.      */
  75.     #$ = null;
  77.     /**
  78.      * Create a new instance of the Complex class.
  79.      * @constructor
  80.      * @param {number} [re=0] The real part of the complex number.
  81.      * @param {number} [im=0] The imaginary part of the complex number.
  82.      */
  83.     constructor(re = 0, im = 0) {
  84.         /**
  85.          * The real part of the complex number.
  86.          * @readonly
  87.          * @const
  88.          * @member {number}
  89.          */
  90.         this.real = +re || 0;
  92.         /**
  93.          * The imaginary part of the complex number.
  94.          * @readonly
  95.          * @const
  96.          * @member {number}
  97.          */
  98.         this.imag = +im || 0;
  100.         /**
  101.          * The constructor function for this instance.
  102.          * @type {Newable<this> & typeof Complex}
  103.          */
  104.         this.constructor;
  106.         /**
  107.          * The prototype object of this instance.
  108.          * @type {this}
  109.          */
  110.         this.__proto__;
  112.         /*
  113.          * Define the real & imag properties of this Complex object as readonly.
  114.          * And thus making class Complex itself immutable:
  115.          */
  116.         Object.defineProperties(this, Complex._IMMUTABLE);
  117.     }
  119.     /**
  120.      * A property descriptor object that defines a property as read-only
  121.      * by setting its attribute writable to false.
  122.      * @protected
  123.      * @static
  124.      * @readonly
  125.      * @const {PropertyDescriptor}
  126.      */
  127.     static _READONLY = Object.freeze({ writable: false });
  129.     /**
  130.      * Map of property descriptors that define the real & imag properties of a
  131.      * Complex object as read-only; so instances of class Complex are immutable.
  132.      * @protected
  133.      * @static
  134.      * @readonly
  135.      * @const {PropertyDescriptorMap}
  136.      */
  137.     static _IMMUTABLE = Object.freeze({
  138.         real: this._READONLY, imag: this._READONLY
  139.     });
  141.     /**
  142.      * Property's name to check if an object is a TypedArray.
  143.      * @protected
  144.      * @static
  145.      * @readonly
  146.      * @const {'BYTES_PER_ELEMENT'}
  147.      */
  148.     static _TYPED = 'BYTES_PER_ELEMENT';
  150.     /**
  151.      * Static property's name to check if some constructor is of type Complex.
  152.      * @protected
  153.      * @static
  154.      * @readonly
  155.      * @const {'fromRI'}
  156.      */
  157.     static _METHOD = 'fromRI';
  159.     /**
  160.      * A Float64Array buffer used to store the binary representation of the
  161.      * real or imaginary part of a complex number for hashcode computation.
  162.      * @protected
  163.      * @static
  164.      * @readonly
  165.      * @type {Float64Array}
  166.      */
  167.     static _hashFBuf = new Float64Array(1);
  169.     /**
  170.      * A Uint8Array buffer view that shares the same memory block as _hashFBuf,
  171.      * used to access the individual bytes of the real or imaginary part of a
  172.      * complex number for hashcode computation.
  173.      * @protected
  174.      * @static
  175.      * @readonly
  176.      * @type {Uint8Array}
  177.      */
  178.     static _hashIBuf = new Uint8Array(this._hashFBuf.buffer);
  180.     /**
  181.      * A complex number representing zero.
  182.      * @static
  183.      * @readonly
  184.      * @const {Complex}
  185.      */
  186.     static ZERO = new this().resetCaches();
  188.     /**
  189.      * A complex number representing 1 + 0i.
  190.      * @static
  191.      * @readonly
  192.      * @const {Complex}
  193.      */
  194.     static _1_0i = new this(1, 0).resetCaches();
  196.     /**
  197.      * A complex number representing -1 + 0i.
  198.      * @static
  199.      * @readonly
  200.      * @const {Complex}
  201.      */
  202.     static _1_0i_neg = new this(-1, 0).resetCaches();
  204.     /**
  205.      * A complex number representing 0 + 1i.
  206.      * @static
  207.      * @readonly
  208.      * @const {Complex}
  209.      */
  210.     static _0_1i = new this(0, 1).resetCaches();
  212.     /**
  213.      * A complex number representing 0 - 1i.
  214.      * @static
  215.      * @readonly
  216.      * @const {Complex}
  217.      */
  218.     static _0_1i_neg = new this(0, -1).resetCaches();
  220.     /**
  221.      * Pi. Ratio of the circumference of a circle to its diameter.
  222.      * @static
  223.      * @readonly
  224.      * @const {3.141592653589793}
  225.      */
  226.     static PI = /** @type {3.141592653589793} */ (Math.PI);
  228.     /**
  229.      * Tau. Ratio of the circumference of a circle to its radius (2pi).
  230.      * @static
  231.      * @readonly
  232.      * @const {6.283185307179586}
  233.      */
  234.     static TAU = /** @type {6.283185307179586} */ (2 * this.PI);
  236.     /**
  237.      * The conversion factor from radians to degrees (180 / Math.PI).
  238.      * @static
  239.      * @readonly
  240.      * @const {57.29577951308232}
  241.      */
  242.     static RAD_TO_DEG = /** @type {57.29577951308232} */ (180 / this.PI);
  244.     /**
  245.      * The conversion factor from degrees to radians (Math.PI / 180).
  246.      * @static
  247.      * @readonly
  248.      * @const {.017453292519943295}
  249.      */
  250.     static DEG_TO_RAD = /** @type {.017453292519943295} */ (this.PI / 180);
  252.     /**
  253.      * The default maximum difference allowed when testing complex numbers.
  254.      * @type {number}
  255.      * @default
  256.      */
  257.     static #epsilon = 1E-8;
  259.     /**
  260.      * Get the default maximum difference allowed when testing complex numbers.
  261.      * @static
  262.      * @return {number} The maximum difference allowed.
  263.      */
  264.     static get epsilon() {
  265.         return Complex.#epsilon;
  266.     }
  268.     /**
  269.      * Set the default maximum difference allowed when testing complex numbers.
  270.      * @static
  271.      * @param {number} norm The max diff allowed. Must be > 0 and < 1.
  272.      * @throws {RangeError} If epsilon to be set is <= 0 or >=1.
  273.      */
  274.     static set epsilon(norm) {
  275.         if (norm <= 0 || norm >= 1)
  276.             throw RangeError('Range must be between 0 & 1 (exclusive)!');
  278.         Complex.#epsilon = +norm;
  279.     }
  281.     /**
  282.      * Convert an angle in radians to degrees.
  283.      * @static
  284.      * @param {number} rad The angle in radians.
  285.      * @return {number} The angle in degrees.
  286.      */
  287.     static toDeg(rad) {
  288.         return rad * Complex.RAD_TO_DEG;
  289.     }
  291.     /**
  292.      * Convert an angle in degrees to radians.
  293.      * @static
  294.      * @param {number} deg The angle in degrees.
  295.      * @return {number} The angle in radians.
  296.      */
  297.     static toRad(deg) {
  298.         return deg * Complex.DEG_TO_RAD;
  299.     }
  301.     /**
  302.      * Callback for comparing 2 complex numbers by their real & imaginary parts.
  303.      * @static
  304.      * @param {Complex} a The first complex number to compare.
  305.      * @param {Cobj} b The second complex number to compare.
  306.      * @return {number} -1 if a < b, 0 if a == b, or +1 if a > b.
  307.      */
  308.     static compare(a, b) {
  309.         return a.compareTo(b);
  310.     }
  312.     /**
  313.      * Returns a new array with the elements sorted by their real value.
  314.      * Numbers w/ same real value are then sorted by their imaginary value.
  315.      * The original array or iterable is unchanged.
  316.      * @static
  317.      * @template {Cinst<TC>} I Instance of Complex type.
  318.      * @param {Iterable<I>} z The original array or iterable.
  319.      * @param {Compare} [sort=Complex.compare] The sorting callback.
  320.      * @return {I[]} A new sorted array.
  321.      */
  322.     static sort(z, sort = Complex.compare) {
  323.         return [...z].sort(sort);
  324.     }
  326.     /**
  327.      * @template {Typed<TypedArray>} T Specific type of the passed TypedArray.
  328.      * @overload
  329.      * @param {T} arr The TypedArray to clone.
  330.      * @return {T} A new TypedArray of same datatype containing
  331.      * the elements of the input TypedArray.
  332.      *
  333.     */
  334.     /**
  335.      * @template A The type of elements in the Array or Iterable object.
  336.      * @overload
  337.      * @param {Iterable<A>} arr The Array or Iterable object to clone.
  338.      * @return {A[]} A new Array containing the elements of the input Array
  339.      * or Iterable object.
  340.      */
  341.     /**
  342.      * @static
  343.      * @param {T | Iterable<A>} arr Array, TypedArray or Iterable to clone.
  344.      * @description Clones an Array, a TypedArray or an Iterable object
  345.      * as an Array or TypedArray of same datatype.
  346.      */
  347.     static arrClone(arr) {
  348.         return Complex._TYPED in arr ? arr.slice() : [...arr];
  349.     }
  351.     /**
  352.      * Check if a function is a Complex datatype constructor.
  353.      * @static
  354.      * @template {Ctor<TC>} C Extends typeof Complex.
  355.      * @param {Cvoid<C>} c The constructor function to check.
  356.      * @return {c is Newable<Cinst<C>>}
  357.      * True if param c is or inherits from Complex class.
  358.      */
  359.     static isComplex(c) {
  360.         return !!c && Complex._METHOD in c;
  361.     }
  363.     /**
  364.      * Get input constructor c if typeof Complex; or fallback to Complex.
  365.      * @protected
  366.      * @static
  367.      * @template {Ctor<TC>} C Extends typeof Complex.
  368.      * @template {Newable<Cinst<C>>} N Constructor for typeof Complex.
  369.      * @param {Cvoid<C>} c The constructor function to verify.
  370.      * @return {N} Param c if type Complex; otherwise a Complex constructor.
  371.      */
  372.     static _ctor(c) {
  373.         return /** @type {N} */ (Complex.isComplex(c) ? c : this || Complex);
  374.     }
  376.     /**
  377.      * Create a new instance of a given Complex constructor function.
  378.      * @protected
  379.      * @static
  380.      * @template {Ctor<TC>} C Extends typeof Complex.
  381.      * @param {Cvoid<C>} c An existing Complex constructor.
  382.      * @param {*} args Real & imaginary number parts.
  383.      * @return {Cinst<C>} A new instance of a complex number.
  384.      */
  385.     static _new(c, ...args) {
  386.         return new (this._ctor(c))(...args);
  387.     }
  389.     /**
  390.      * Return a complex number given values for the real & imaginary parts.
  391.      * @static
  392.      * @template {Ctor<TC>} C Extends typeof Complex.
  393.      * @this {Cvoid<C>} Constructor for a Complex object or its subclass.
  394.      * @param {number} [re=0] The real part.
  395.      * @param {number} [im=0] The imaginary part.
  396.      * @param {*} _args Extended parameters.
  397.      * @return {Cinst<C>} The complex number of given real & imaginary parts.
  398.      */
  399.     static fromRI(re, im, ..._args) {
  400.         return Complex._new(this, re, im, ..._args);
  401.     }
  403.     /**
  404.      * Return a new complex number using given object's props real & imag.
  405.      * @static
  406.      * @template {Ctor<TC>} C Extends typeof Complex.
  407.      * @this {Cvoid<C>} Constructor for a Complex object or its subclass.
  408.      * @param {Cobj} z The Complex object to copy from.
  409.      * @param {*} _args Extended parameters.
  410.      * @return {Cinst<C>} Duplicate of the given Complex object.
  411.      */
  412.     static fromZ({ real, imag }, ..._args) {
  413.         return Complex._new(this, real, imag, ..._args);
  414.     }
  416.     /**
  417.      * Return a complex number given polar coordinates.
  418.      * @static
  419.      * @template {Ctor<TC>} C Extends typeof Complex.
  420.      * @this {Cvoid<C>} Constructor for a Complex object or its subclass.
  421.      * @param {number} mod The length of the complex number.
  422.      * @param {number} rad The angle subtended by the number.
  423.      * @param {*} _args Extended parameters.
  424.      * @return {Cinst<C>} Complex of given length & orientation.
  425.      */
  426.     static fromPolar(mod, rad, ..._args) {
  427.         const re = mod * Math.cos(rad), im = mod * Math.sin(rad);
  428.         return Complex._new(this, re, im, ..._args);
  429.     }
  431.     /**
  432.      * Return a complex number of a given size but random orientation.
  433.      * @static
  434.      * @template {Ctor<TC>} C Extends typeof Complex.
  435.      * @this {Cvoid<C>} Constructor for a Complex object or its subclass.
  436.      * @param {number} [mod=1] The length of the complex number.
  437.      * @param {*} _args Extended parameters.
  438.      * @return {Cinst<C>} Complex of given length & random orientation.
  439.      */
  440.     static fromRandom(mod = 1, ..._args) {
  441.         const
  442.           ang = Complex.TAU * Math.random(),
  443.           re = mod * Math.cos(ang),
  444.           im = mod * Math.sin(ang);
  446.         return Complex._new(this, re, im, ..._args);
  447.     }
  449.     /**
  450.      * Given an array of complex numbers return a new array containing a clone
  451.      * of those that represent real numbers. The original array is unchanged.
  452.      * @static
  453.      * @template {Ctor<TC>} C Extends typeof Complex.
  454.      * @this {Cvoid<C>} Constructor for a Complex object or its subclass.
  455.      * @param {Iterable<Complex>} z The original array or iterable.
  456.      * @param {number} [epsilon=Complex.epsilon] Max diffference allowed.
  457.      * @param {*} _args Extended parameters.
  458.      * @return {Array<Cinst<C>>} Array of Complex representing real numbers.
  459.      */
  460.     static filterRealRoots(z, epsilon = Complex.#epsilon, ..._args) {
  461.         const ctor = Complex._ctor(this), r = [];
  463.         for (const c of z)
  464.             c.isReal(epsilon) && r.push(new ctor(c.real, 0, ..._args));
  466.         return r;
  467.     }
  469.     /**
  470.      * If the original array contains more than 1 element the new array is
  471.      * returned with duplicates removed leaving just unique vales.
  472.      * In all cases a clone is returned and the original array is unchanged.
  473.      * @static
  474.      * @template {Cinst<TC>} I Instance of Complex type.
  475.      * @param {Iterable<I>} z The original array or iterable.
  476.      * @param {number} [epsilon=Complex.epsilon] Max diffference allowed.
  477.      * @return {I[]} A new array with duplicates removed.
  478.      */
  479.     static removeDuplicates(z, epsilon = Complex.#epsilon) {
  480.         const zs = [...z], len = zs.length;
  481.         if (len < 2) return zs; // Can't have duplicates, so exit now!
  483.         const nz = [ zs.sort(Complex.compare)[0] ];
  484.         var i = 0, idx = 0;
  486.         while (++i < len) {
  487.             const c = zs[i];
  488.             if (!c.equals(nz[idx], epsilon)) nz.push(c), ++idx;
  489.         }
  491.         return nz;
  492.     }
  494.     /**
  495.      * Compute the absolute value (modulus or magnitude) of this complex number.
  496.      * @return {number} The absolute length value of this complex number.
  497.      */
  498.     abs() {
  499.         return Math.sqrt(this.real * this.real + this.imag * this.imag);
  500.         // return Math.hypot(this.real, this.imag); // Likely slower!
  501.     }
  503.     /**
  504.      * Compute the squared absolute value of this complex number.
  505.      * @return {number} The squared absolute value of this complex number.
  506.      */
  507.     abs_squared() {
  508.         return this.real * this.real + this.imag * this.imag;
  509.     }
  511.     /**
  512.      * Add another complex number or a real number to this complex number.
  513.      * @param {Cobj | number} n The complex or real number to add.
  514.      * @return {this} A new complex number representing the sum.
  515.      */
  516.     add(n) {
  517.         const { constructor, real, imag } = this;
  519.         return typeof n == 'object' ?
  520.             new constructor(+n.real + real, +n.imag + imag) :
  521.             new constructor(+n + real, imag);
  522.     }
  524.     /**
  525.      * Calculate the inverse cosine of this complex number.
  526.      * @return {this} A new complex number representing the result.
  527.      */
  528.     acos() {
  529.         const z = this.squared().sub(1).sqrt().add(this).log().
  530.                        mult(Complex._0_1i_neg);
  532.         return z.real < 0 && z.negate() || z;
  533.     }
  535.     /**
  536.      * Calculate the inverse hyperbolic cosine of this complex number.
  537.      * @return {this} A new complex number representing the result.
  538.      */
  539.     acosh() {
  540.         const z = this.squared().sub(Complex._1_0i).sqrt().add(this).log();
  541.         return z.real < 0 && z.negate() || z;
  542.     }
  544.     /**
  545.      * Calculate the argument (phase) of this complex number in radians.
  546.      * @return {number} The argument of this complex number in radians.
  547.      */
  548.     arg() {
  549.         return Math.atan2(this.imag, this.real);
  550.     }
  552.     /**
  553.      * Calculate the inverse sine of this complex number.
  554.      * @return {this} A new complex number representing the result.
  555.      */
  556.     asin() {
  557.         const t2 = this.squared().sub(Complex._1_0i).negate().sqrt();
  558.         return this.mult(Complex._0_1i).add(t2).log().mult(Complex._0_1i_neg);
  559.     }
  561.     /**
  562.      * Calculate the inverse hyperbolic sine of this complex number.
  563.      * @return {this} A new complex number representing the result.
  564.      */
  565.     asinh() {
  566.         return this.squared().add(Complex._1_0i).sqrt().add(this).log();
  567.     }
  569.     /**
  570.      * Calculate the inverse tangent of this complex number.
  571.      * @return {this} A new complex number representing the result.
  572.      */
  573.     atan() {
  574.         const _01 = this.constructor.fromZ(Complex._0_1i);
  575.         return _01.half().mult( _01.add(this).div( _01.sub(this) ).log() );
  576.     }
  578.     /**
  579.      * Calculate the inverse hyperbolic tangent of this complex number.
  580.      * @return {this} A new complex number representing the result.
  581.      */
  582.     atanh() {
  583.         const _10 = this.constructor.fromZ(Complex._1_0i);
  584.         return _10.add(this).div( _10.sub(this) ).log().half();
  585.     }
  587.     /**
  588.      * Calculate the cube root of this complex number.
  589.      * @return {this} A new complex number representing the result.
  590.      */
  591.     cbrt() {
  592.         const { cbrt, atan2, cos, sin } = Math, mag = cbrt( this.abs() );
  593.         var theta = atan2(this.imag, this.real);
  594.         if (theta < 0) theta += Complex.TAU;
  595.         return new this.constructor(cos(theta /= 3) * mag, sin(theta) * mag);
  596.     }
  598.     /**
  599.      * Creates a copy of the same type as this complex instance.
  600.      * Although it's unnecessary given a Complex object is already immutable.
  601.      * @return {this} A new complex object with the same real and imaginary
  602.      * values as this instance.
  603.      */
  604.     clone() {
  605.         return new this.constructor(...this).resetCaches();
  606.     }
  608.     /**
  609.      * Calculate the conjugate of this complex number.
  610.      * @return {this} A new complex number representing the conjugate.
  611.      */
  612.     conj() {
  613.         return new this.constructor(this.real, -this.imag);
  614.     }
  616.     /**
  617.      * This method compares this complex number with another.
  618.      * The main purpose of this is to define an appropriate sort order.
  619.      * Returns:
  620.      *  Zero if the numbers are the same when using the equals method.
  621.      *  Negative if considered less than z.
  622.      *  Positive if considered larger than z.
  623.      * @param {Cobj} z the complex number to compare with.
  624.      * @return {number} -1, 0 or +1
  625.      */
  626.     compareTo(z) {
  627.         return this.equals(z) ? 0 : this.real - z.real || this.imag - z.imag;
  628.     }
  630.     /**
  631.      * Calculate the cosine of this complex number.
  632.      * @return {this} A new complex number representing the result.
  633.      */
  634.     cos() {
  635.         const t = this.mult(Complex._0_1i);
  636.         return t.exp().add( t.negate().exp() ).half();
  637.     }
  639.     /**
  640.      * Calculate the cosecant of this complex number.
  641.      * @return {this} A new complex number representing the result.
  642.      */
  643.     cosec() {
  644.         return this.sin().pow(-1);
  645.     }
  647.     /**
  648.      * Calculate the hyperbolic cosecant of this complex number.
  649.      * @return {this} A new complex number representing the result.
  650.      */
  651.     cosech() {
  652.         return this.sinh().pow(-1);
  653.     }
  655.     /**
  656.      * Calculate the hyperbolic cosine of this complex number.
  657.      * @return {this} A new complex number representing the result.
  658.      */
  659.     cosh() {
  660.         return this.exp().add( this.negate().exp() ).half();
  661.     }
  663.     /**
  664.      * Returns the cotangent of this complex number.
  665.      * @return {this} The cotangent of this complex number.
  666.      */
  667.     cot() {
  668.         return this.cos().div( this.sin() );
  669.     }
  671.     /**
  672.      * Returns the hyperbolic cotangent of this complex number.
  673.      * @return {this} The hyperbolic cotangent of this complex number.
  674.      */
  675.     coth() {
  676.         return this.cosh().div( this.sinh() );
  677.     }
  679.     /**
  680.      * Returns the cube of this complex number.
  681.      * @return {this} The cube of this complex number.
  682.      */
  683.     cubed() {
  684.         const
  685.           { constructor, real, imag } = this,
  687.           re = real**3 - 3 * real * imag * imag,
  688.           im = 3 * real * real * imag**4;
  690.         return new constructor(re, im);
  691.     }
  693.     /**
  694.      * Divides this complex number by another complex number or a scalar.
  695.      * @param {(Cobj | number)} n The divisor.
  696.      * @return {this} The quotient of the division.
  697.      */
  698.     div(n) {
  699.         const { constructor, real, imag } = this;
  701.         if (typeof n == 'object') {
  702.             const
  703.               { real: r, imag: i } = n,
  704.               m = r*r + i*i;
  706.             var
  707.               re = (r * real + i * imag) / m,
  708.               im = (r * imag - i * real) / m;
  709.         }
  711.         else var re = real / n, im = imag / n;
  713.         return new constructor(re, im);
  714.     }
  716.     /**
  717.      * Checks if this complex number is equal to another complex number within
  718.      * a given tolerance.
  719.      * @param {Cobj} z The other complex number to compare with.
  720.      * @param {number} [epsilon=Complex.epsilon] The tolerance for equality.
  721.      * @return {boolean} True if the two numbers are equal within the given
  722.      * tolerance, false otherwise.
  723.      */
  724.     equals({ real, imag }, epsilon = Complex.#epsilon) {
  725.         return Math.abs(this.real - real) < epsilon &&
  726.                Math.abs(this.imag - imag) < epsilon;
  727.     }
  729.     /**
  730.      * Returns the exponential of this complex number.
  731.      * @return {this} The exponential of this complex number.
  732.      */
  733.     exp() {
  734.         const
  735.           a = Math.exp(this.real),
  736.           b = Math.cos(this.imag),
  737.           c = Math.sin(this.imag);
  739.         return this.constructor.fromZ(Complex._0_1i).mult(c).add(b).mult(a);
  740.     }
  742.     /**
  743.      * Generates a hashcode for this complex number.
  744.      * @param {number} [hash=17] Optional initial seed for the hashcode.
  745.      * @return {number} The hashcode for this complex number.
  746.      */
  747.     hashCode(hash = 0) {
  748.         if (!hash && this.#hashCode != null) return this.#hashCode;
  750.         hash = ~~hash || 17;
  752.         for (const z of this) { // Iterate over [real & imag] values.
  753.             Complex._hashFBuf[0] = z;
  754.             for (const int8 of Complex._hashIBuf) hash = hash * 31 + int8 | 0;
  755.         }
  757.         return this.#hashCode = hash;
  758.     }
  760.     /**
  761.      * Checks if this complex number is real within a given tolerance.
  762.      * @param {number} [epsilon=Complex.epsilon] The tolerance for checking
  763.      * if the imaginary part is zero.
  764.      * @return {boolean} True if the imaginary part is zero within the given
  765.      * tolerance, false otherwise.
  766.      */
  767.     isReal(epsilon = Complex.#epsilon) {
  768.         return Math.abs(this.imag) <= epsilon;
  769.     }
  771.     /**
  772.      * Checks if this complex number is zero within a given tolerance.
  773.      * @param {number} [epsilon=Complex.epsilon] The tolerance for checking
  774.      * if both the real and imaginary parts are zero.
  775.      * @return {boolean} True if both the real and imaginary parts are zero
  776.      * within the given tolerance, false otherwise.
  777.      */
  778.     isZero(epsilon = Complex.#epsilon) {
  779.         return Math.abs(this.real) < epsilon && Math.abs(this.imag) < epsilon;
  780.     }
  782.     /**
  783.      * Returns the natural logarithm of this complex number.
  784.      * @return {this} The natural logarithm of this complex number.
  785.      */
  786.     log() {
  787.         const re = Math.log( this.abs() );
  788.         const im = this.real < 0 && !this.imag ? Complex.PI : this.arg();
  789.         return new this.constructor(re, im);
  790.     }
  792.     /**
  793.      * Multiplies this complex number by another complex number or a scalar.
  794.      * @param {(Cobj | number)} n The multiplicand.
  795.      * @return {this} The product of the multiplication.
  796.      */
  797.     mult(n) {
  798.         const { constructor, real, imag } = this;
  800.         if (typeof n == 'object') return new constructor(
  801.             n.real * real - n.imag * imag,
  802.             n.imag * real + n.real * imag
  803.         );
  805.         return new constructor(n * real, n * imag);
  806.     }
  808.     /**
  809.      * Returns the half (divided by 2) of this complex number.
  810.      * @return {this} Half of this complex number.
  811.      */
  812.     half() {
  813.         return this.mult(.5);
  814.     }
  816.     /**
  817.      * Returns the negation of this complex number.
  818.      * @return {this} The negation of this complex number.
  819.      */
  820.     negate() {
  821.         return this.mult(-1);
  822.     }
  824.     /**
  825.      * Returns the normalization of this complex number.
  826.      * @return {this} The normalization of this complex number.
  827.      */
  828.     norm() {
  829.         return this.div( this.abs() );
  830.     }
  832.     /**
  833.      * Returns the power of this complex number raised to another complex
  834.      * number or a scalar.
  835.      * @param {(Cobj | number)} n The exponent.
  836.      * @return {this} Power of this complex number raised to given exponent.
  837.      */
  838.     pow(n) {
  839.         return this.log().mult(n).exp();
  840.     }
  842.     /**
  843.      * Returns the nth roots of this complex number (min 1).
  844.      * @param {number} [n=1] The degree of the roots.
  845.      * @return {this[]} An array containing the nth roots of this
  846.      * complex number.
  847.      */
  848.     roots(n = 1) {
  849.         const
  850.           { constructor, real, imag } = this,
  852.           delta = Complex.TAU / (n = ~~Math.abs(n) || 1),
  853.           arg = Math.atan2(imag, real) / n,
  854.           mod = Math.pow(this.modSq(), 1 / n);
  856.         return Array.from(
  857.             { length: n },
  858.             (_, r) => constructor.fromPolar(mod, r * delta + arg)
  859.         );
  860.     }
  862.     /**
  863.      * Returns the sine of this complex number.
  864.      * @return {this} The sine of this complex number.
  865.      */
  866.     sin() {
  867.         const t1 = this.mult(Complex._0_1i).exp().mult(Complex._0_1i_neg);
  868.         const t2 = this.mult(Complex._0_1i_neg).exp().mult(Complex._0_1i_neg);
  869.         return t1.sub(t2).half();
  870.     }
  872.     /**
  873.      * Returns the hyperbolic sine of this complex number.
  874.      * @return {this} The hyperbolic sine of this complex number.
  875.      */
  876.     sinh() {
  877.         return this.exp().sub( this.negate().exp() ).half();
  878.     }
  880.     /**
  881.      * Returns the square of this complex number.
  882.      * @return {this} The square of this complex number.
  883.      */
  884.     squared() {
  885.         const
  886.           { constructor, real, imag } = this,
  888.           re = (real + imag) * (real - imag), // Same as: real*real - imag*imag
  889.           im = 2 * real * imag;
  891.         return new constructor(re, im);
  892.     }
  894.     /**
  895.      * Returns the square root of this complex number.
  896.      * @return {this} The square root of this complex number.
  897.      */
  898.     sqrt() {
  899.         const
  900.           { constructor, real, imag } = this,
  902.           abs = this.abs(),
  903.           re = Math.sqrt(.5 * (abs + real)),
  904.           im = Math.sqrt(.5 * (abs - real));
  906.         return new constructor(re, imag >= 0 ? im : -im);
  907.     }
  909.     /**
  910.      * Subtracts another complex or a real number from this complex number.
  911.      * @param {(Cobj | number)} n The subtrahend.
  912.      * @return {this} The difference between the two numbers.
  913.      */
  914.     sub(n) {
  915.         const { constructor, real, imag } = this;
  917.         return typeof n == 'object' ?
  918.             new constructor(real - n.real, imag - n.imag) :
  919.             new constructor(real - n, imag);
  920.     }
  922.     /**
  923.      * Returns the tangent of this complex number.
  924.      * @return {this} The tangent of this complex number.
  925.      */
  926.     tan() {
  927.         return this.sin().div( this.cos() );
  928.     }
  930.     /**
  931.      * Returns the hyperbolic tangent of this complex number.
  932.      * @return {this} The hyperbolic tangent of this complex number.
  933.      */
  934.     tanh() {
  935.         return this.sinh().div( this.cosh() );
  936.     }
  938.     /**
  939.      * Prints this complex number to the console.
  940.      * @param {number} [precision=16] Number of significant digits to display.
  941.      * @return {this} This complex number.
  942.      * @chainable
  943.      */
  944.     print(precision) {
  945.         console.log( this.$(precision) );
  946.         return this;
  947.     }
  949.     /**
  950.      * Returns a string representation of this complex number.
  951.      * @param {number} [precision=16] Number of significant digits to display.
  952.      * @param {string} [$=''] Extra info to append to the string representation.
  953.      * @return {string} A string representation of this complex number.
  954.      */
  955.     $(precision = 0, $ = '') {
  956.         if (!precision && !$ && this.#$ != null) return this.#$;
  958.         const
  959.           sgn = this.imag < 0 && '-' || '+',
  960.           rep = this.real.toPrecision(precision ||= 16),
  961.           imp = Math.abs(this.imag).toPrecision(precision);
  963.         return this.#$ = `( ${rep} | ${sgn}${imp}j )${$}`;
  964.     }
  966.     /**
  967.      * Returns a string representation of this complex number.
  968.      * @return {string} A string representation of this complex number.
  969.      */
  970.     toString() {
  971.         return this.$();
  972.     }
  974.     /**
  975.      * Resets to default values both #hashCode & #$ internal caches.
  976.      * @return {this} This complex number.
  977.      * @chainable
  978.      */
  979.     resetCaches() {
  980.         this.hashCode(17);
  981.         this.$(16, '');
  982.         return this;
  983.     }
  985.     /**
  986.      * Returns the name of the constructor of this complex number.
  987.      * @return {string} The name of the constructor of this complex number.
  988.      */
  989.     get [Symbol.toStringTag]() {
  990.         return this.constructor.name;
  991.     }
  993.     /**
  994.      * Converts this complex number to a primitive value.
  995.      * @param {'default' | 'number' | 'string'} hint Type hint for conversion.
  996.      * @return {number | string} The primitive value of this complex number.
  997.      */
  998.     [Symbol.toPrimitive](hint) {
  999.         return hint == 'number' ? this.real : this.toString();
  1000.     }
  1002.     /**
  1003.      * Gets an iterator for the real and imaginary parts of this complex number.
  1004.      * @generator
  1005.      * @yield {number}
  1006.      * @return {IterableIterator<number>}
  1007.      * An iterator for the real and imaginary parts of this complex number.
  1008.      */
  1009.     *[Symbol.iterator]() {
  1010.         yield this.real;
  1011.         yield this.imag;
  1012.     }
  1013. }
  1015. /**
  1016.  * Compute the absolute value (modulus or magnitude) of this complex number.
  1017.  * @method mod
  1018.  * @memberof Complex
  1019.  * @instance
  1020.  * @return {number} The absolute length value of this complex number.
  1021.  * @description Alias of Complex::abs().
  1022.  */
  1023. Complex.prototype.mod = Complex.prototype.abs;
  1025. /**
  1026.  * Compute the squared absolute value of this complex number.
  1027.  * @method modSq
  1028.  * @memberof Complex
  1029.  * @instance
  1030.  * @return {number} The squared absolute value of this complex number.
  1031.  * @description Alias of Complex::abs_squared().
  1032.  */
  1033. Complex.prototype.modSq = Complex.prototype.abs_squared;
  1035. /**
  1036.  * Multiplies this complex number by another complex number or a scalar.
  1037.  * @method mul
  1038.  * @memberof Complex
  1039.  * @instance
  1040.  * @param {(Cobj | number)} n The multiplicand.
  1041.  * @return {this} The product of the multiplication.
  1042.  * @description Alias of Complex::mult().
  1043.  */
  1044. Complex.prototype.mul = Complex.prototype.mult;
  1046. // Freeze the Complex class to prevent further modifications to
  1047. // its static properties & methods:
  1048. Object.freeze(Complex);