simple-squiggle

A restricted subset of Squiggle
Log | Files | Refs | README

cbrt.js (4461B)

      1 import { factory } from '../../utils/factory.js';
      2 import { isBigNumber, isComplex, isFraction } from '../../utils/is.js';
      3 import { deepMap } from '../../utils/collection.js';
      4 import { cbrtNumber } from '../../plain/number/index.js';
      5 var name = 'cbrt';
      6 var dependencies = ['config', 'typed', 'isNegative', 'unaryMinus', 'matrix', 'Complex', 'BigNumber', 'Fraction'];
      7 export var createCbrt = /* #__PURE__ */factory(name, dependencies, _ref => {
      8   var {
      9     config,
     10     typed,
     11     isNegative,
     12     unaryMinus,
     13     matrix,
     14     Complex,
     15     BigNumber,
     16     Fraction
     17   } = _ref;
     18 
     19   /**
     20    * Calculate the cubic root of a value.
     21    *
     22    * For matrices, the function is evaluated element wise.
     23    *
     24    * Syntax:
     25    *
     26    *    math.cbrt(x)
     27    *    math.cbrt(x, allRoots)
     28    *
     29    * Examples:
     30    *
     31    *    math.cbrt(27)                  // returns 3
     32    *    math.cube(3)                   // returns 27
     33    *    math.cbrt(-64)                 // returns -4
     34    *    math.cbrt(math.unit('27 m^3')) // returns Unit 3 m
     35    *    math.cbrt([27, 64, 125])       // returns [3, 4, 5]
     36    *
     37    *    const x = math.complex('8i')
     38    *    math.cbrt(x)                   // returns Complex 1.7320508075689 + i
     39    *    math.cbrt(x, true)             // returns Matrix [
     40    *                                    //    1.7320508075689 + i
     41    *                                    //   -1.7320508075689 + i
     42    *                                    //   -2i
     43    *                                    // ]
     44    *
     45    * See also:
     46    *
     47    *    square, sqrt, cube
     48    *
     49    * @param {number | BigNumber | Complex | Unit | Array | Matrix} x
     50    *            Value for which to calculate the cubic root.
     51    * @param {boolean} [allRoots]  Optional, false by default. Only applicable
     52    *            when `x` is a number or complex number. If true, all complex
     53    *            roots are returned, if false (default) the principal root is
     54    *            returned.
     55    * @return {number | BigNumber | Complex | Unit | Array | Matrix}
     56    *            Returns the cubic root of `x`
     57    */
     58   return typed(name, {
     59     number: cbrtNumber,
     60     // note: signature 'number, boolean' is also supported,
     61     //       created by typed as it knows how to convert number to Complex
     62     Complex: _cbrtComplex,
     63     'Complex, boolean': _cbrtComplex,
     64     BigNumber: function BigNumber(x) {
     65       return x.cbrt();
     66     },
     67     Unit: _cbrtUnit,
     68     'Array | Matrix': function ArrayMatrix(x) {
     69       // deep map collection, skip zeros since cbrt(0) = 0
     70       return deepMap(x, this, true);
     71     }
     72   });
     73   /**
     74    * Calculate the cubic root for a complex number
     75    * @param {Complex} x
     76    * @param {boolean} [allRoots]   If true, the function will return an array
     77    *                               with all three roots. If false or undefined,
     78    *                               the principal root is returned.
     79    * @returns {Complex | Array.<Complex> | Matrix.<Complex>} Returns the cubic root(s) of x
     80    * @private
     81    */
     82 
     83   function _cbrtComplex(x, allRoots) {
     84     // https://www.wikiwand.com/en/Cube_root#/Complex_numbers
     85     var arg3 = x.arg() / 3;
     86     var abs = x.abs(); // principal root:
     87 
     88     var principal = new Complex(cbrtNumber(abs), 0).mul(new Complex(0, arg3).exp());
     89 
     90     if (allRoots) {
     91       var all = [principal, new Complex(cbrtNumber(abs), 0).mul(new Complex(0, arg3 + Math.PI * 2 / 3).exp()), new Complex(cbrtNumber(abs), 0).mul(new Complex(0, arg3 - Math.PI * 2 / 3).exp())];
     92       return config.matrix === 'Array' ? all : matrix(all);
     93     } else {
     94       return principal;
     95     }
     96   }
     97   /**
     98    * Calculate the cubic root for a Unit
     99    * @param {Unit} x
    100    * @return {Unit} Returns the cubic root of x
    101    * @private
    102    */
    103 
    104 
    105   function _cbrtUnit(x) {
    106     if (x.value && isComplex(x.value)) {
    107       var result = x.clone();
    108       result.value = 1.0;
    109       result = result.pow(1.0 / 3); // Compute the units
    110 
    111       result.value = _cbrtComplex(x.value); // Compute the value
    112 
    113       return result;
    114     } else {
    115       var negate = isNegative(x.value);
    116 
    117       if (negate) {
    118         x.value = unaryMinus(x.value);
    119       } // TODO: create a helper function for this
    120 
    121 
    122       var third;
    123 
    124       if (isBigNumber(x.value)) {
    125         third = new BigNumber(1).div(3);
    126       } else if (isFraction(x.value)) {
    127         third = new Fraction(1, 3);
    128       } else {
    129         third = 1 / 3;
    130       }
    131 
    132       var _result = x.pow(third);
    133 
    134       if (negate) {
    135         _result.value = unaryMinus(_result.value);
    136       }
    137 
    138       return _result;
    139     }
    140   }
    141 });