refactor: Adopt new config options organization

Author: gwhitney

docs/core/configuration.md

@@ -1,92 +1,124 @@
 # Configuration
 
-Math.js contains a number of configuration options.
-These options can be applied on a created mathjs instance and changed afterwards.
+Math.js contains a number of configuration options. These options can be
+applied on a created mathjs instance and changed afterwards.
 
 ```js
 import { create, all } from 'mathjs'
 
 // create a mathjs instance with configuration
 const config = {
-  relTol: 1e-12,
-  absTol: 1e-15,
-  matrix: 'Matrix',
   number: 'number',
-  numberFallback: 'number',
-  precision: 64,
-  predictable: false,
-  randomSeed: null,
-  legacySubset: false
+  compute: {
+    defaultRelTol: 1e-12,
+    defaultAbsTol: 1e-15,
+    numberApproximate: 'number',
+    randomSeed: null,
+    uniformType: false,
+    Matrix: {
+      defaultType: 'Matrix'
+    },
+    BigNumber: {
+      precision: 64,
+    },
+  },
+  parse: {
+    numberFallback: 'number',
+  },
+  compatibility: {
+    subset: false
+  }
 }
 const math = create(all, config)
 
 // read the applied configuration
 console.log(math.config())
 
 // change the configuration
-math.config({
-  number: 'BigNumber'
-})
+math.config({ number: 'BigNumber' })
 ```
 
-The following configuration options are available:
-
-- `relTol`. The minimum relative difference used to test equality between two
-  compared values. This value is used by all relational functions.
-  Default value is `1e-12`.
-
-- `absTol`. The minimum absolute difference used to test equality between two
-  compared values. This value is used by all relational functions.
-  Default value is `1e-15`.
-
-- `matrix`. The default type of matrix output for functions.
-  Available values are: `'Matrix'` (default) or `'Array'`.
-  Where possible, the type of matrix output from functions is determined from
-  the function input: An array as input will return an Array, a Matrix as input
-  will return a Matrix. In case of no matrix as input, the type of output is
-  determined by the option `matrix`. In case of mixed matrix
-  inputs, a matrix will be returned always.
-
-- `number`. The type used to parse strings into a numeric value or create a new
-  numeric value internally.
-
-  For most functions, the type of output is determined from the input: 
-  a number as input will return a number as output, a BigNumber as input 
-  returns a BigNumber as output. But for example the functions 
-  `math.evaluate('2+3')`, `math.parse('2+3')`, `math.range('1:10')`, 
-  and `math.unit('5cm')` use the `number` configuration setting. 
-
-  Note that `math.sqrt(4)` will always return the number `2` regardless of 
-  the `number` configuration, because the numeric type can be determined from 
-  the input value.
-
-  Available values are: `'number'` (default), `'BigNumber'`, `'bigint'`, or `'Fraction'`.
-  [BigNumbers](../datatypes/bignumbers.md) have higher precision than the default numbers of JavaScript, 
-  [bigint](../datatypes/bigints.md) can represent large integer numbers, 
-  and [`Fractions`](../datatypes/fractions.md) store values in terms of a numerator and 
-  denominator.
-
-- `numberFallback`. When `number` is configured for example with value `'bigint'`,
-  and a value cannot be represented as `bigint` like in `math.evaluate('2.3')`, 
-  the value will be parsed in the type configured with `numberFallback`. 
-  Available values: `'number'` (default) or `'BigNumber'`.
-
-- `precision`. The maximum number of significant digits for BigNumbers.
-  This setting only applies to BigNumbers, not to numbers.
-  Default value is `64`.
-
-- `predictable`. Predictable output type of functions. When true, output type
-  depends only on the input types. When false (default), output type can vary
-  depending on input values. For example `math.sqrt(-4)` returns `complex('2i')` when
-  predictable is false, and returns `NaN` when true.
-  Predictable output can be needed when programmatically handling the result of
-  a calculation, but can be inconvenient for users when evaluating dynamic
-  equations.
-
-- `randomSeed`. Set this option to seed pseudo random number generation, making it deterministic. The pseudo random number generator is reset with the seed provided each time this option is set. For example, setting it to `'a'` will cause `math.random()` to return `0.43449421599986604` upon the first call after setting the option every time. Set to `null` to seed the pseudo random number generator with a random seed. Default value is `null`.
-
-- `legacySubset`. When set to `true`, the `subset` function behaves as in earlier versions of math.js: retrieving a subset where the index size contains only one element, returns the value itself. When set to `false` (default), `subset` eliminates dimensions from the result only if the index dimension is a scalar; if the index dimension is a range, matrix, or array, the dimensions are preserved. This option is helpful for maintaining compatibility with legacy code that depends on the previous behavior.
-
+The following configuration options and sub-options are available.
+
+- {string} `number`. When the type of a numeric value is not otherwise
+    specifically determined, either in parsing or in computation, the type
+    given by this option is tried first. For example, when set to `Fraction`,
+    `math.evaluate('0.15 + 02')` will return the exact rational number
+    `math.fraction(7, 20)` and `math.sum([])` will return `math.fraction(0)`.
+    Note there are separate backup options for parsing (`parse.numberFallback`)
+    and computation (`compute.numberApproximate`) when this `number` type is
+    not appropriate, see below. The currently supported values for this
+    option are `number` (the default), `BigNumber` (which can support higher
+    precision than the built-in JavaScript number type), `Fraction`, `bigint`
+    (which can represent arbitrarily large integer numbers, but not
+    fractions or decimals).
+
+- compute:
+  - {number} `defaultAbsTol`. The minimum absolute difference used to test
+    equality between two compared values of floating-point (inexact) types.
+    This value is used by all relational functions. Default value is `1e-15`.
+
+  - {number} `defaultRelTol`. The minimum relative difference used to test
+    equality between two compared values of floating-point (inexact) types.
+    This value is used by all relational functions. Default value is `1e-12`.
+
+  - {string} `numberApproximate`. The type to use for floating-point
+    (approximate real) values as output when the type is not uniquely
+    determined by the input types (e.g., the square root of a bigint or the
+    value of a mathematical constant). Default value is `number`.
+
+  - {string|null} `randomSeed`. Set this option to seed pseudo-random number
+    generation, making it deterministic. The pseudo-random number generator is
+    reset with the seed provided each time this option is set to a new value.
+    For example, setting it to `'a'` will always cause `math.random()` to
+    return `0.43449421599986604` on its next call. Set to `null` to seed the
+    pseudo random number generator with a random seed. Default value is `null`.
+
+  - {boolean} `uniformType`. When this option is true, the output type of any
+    function depends only on the input types. When false, the output type can
+    vary depending on input values within the same type. For example,
+    `math.sqrt(-4)` returns `math.complex('2i')` when this option is false,
+    and returns `NaN` when true. Predictable output can be needed when
+    programmatically handling the result of a calculation, but can be
+    inconvenient for users when evaluating dynamic equations. Default
+    value is `false`.
+
+  - BigNumber:
+    - {number} `precision`. The maximum number of significant digits kept
+      for values of BigNumber type. Note that increasing it will not affect
+      previously computed BigNumbers, but will retain the larger number
+      of digits for future computations. Default value is `64`.
+
+  - Matrix:
+    - {string} `defaultType`. The data type used to represent a matrix output
+      by any function, when that type is not uniquely determined by the input
+      types. Whenever possible, the type of matrix output from functions is
+      determined from the function input: An array as input will return an
+      Array and a Matrix as input will return a Matrix (which is also returned
+      in case of mixed-type matrix inputs). However, some functions, such as
+      `math.identity(n)`, have no matrix parameter. In such cases, the type
+      of the output is determined by this option, including in the case of
+      the `[...]` matrix-creating operator in mathjs expressions. Currently
+      supported types are `Array` and `Matrix`, the default.
+
+- parse:
+  - {string} `numberFallback`. When the top-level `number` option is
+    configured, for example, with value `'bigint'`, and a literal value in
+    an expression, such as `'2.3'`, cannot be represented as that type,
+    the value will instead be parsed into the type specified by
+    `numberFallback`. The currently supported values are `BigNumber`,
+    `Fraction`, and `number`, the default.
+
+- compatibility:
+  - {boolean} `subset`. When set to `true`, the `subset` function behaves
+    as in earlier versions of math.js: retrieving a subset where the index
+    size contains only one element, returns the value itself. When set to
+    `false`, `subset` eliminates dimensions from the result only if the
+    index dimension is a scalar; if the index dimension is a range, matrix,
+    or array, the dimensions are preserved. This option is helpful for
+    maintaining compatibility with legacy code that depends on the
+    previous behavior. It is, however, deprecated and will be removed in some
+    future version of mathjs.
 
 ## Examples
 
@@ -98,25 +130,27 @@ This section shows a number of configuration examples.
 import { create, all } from 'mathjs'
 
 const config = {
-  matrix: 'Array' // Choose 'Matrix' (default) or 'Array'
+  compute: {
+    Matrix: { defaultType: 'Array' } // Choose 'Matrix' (default) or 'Array'
+  }
 }
 const math = create(all, config)
 
 // range will output an Array
 math.range(0, 4) // Array [0, 1, 2, 3]
 
 // change the configuration from Arrays to Matrices
-math.config({
-  matrix: 'Matrix' // Choose 'Matrix' (default) or 'Array'
-})
+math.config({ compute: { Matrix: { defaultType: 'Matrix' } } })
 
 // range will output a Matrix
 math.range(0, 4) // Matrix [0, 1, 2, 3]
 
 // create an instance of math.js with BigNumber configuration
 const bigmath = create(all, {
-  number: 'BigNumber', // Choose 'number' (default), 'BigNumber', or 'Fraction'
-  precision: 32        // 64 by default, only applicable for BigNumbers
+  number: 'BigNumber'
+  compute: {
+    BigNumber: { precision: 32 } // Would be 64 by default
+  }
 })
 
 // parser will parse numbers as BigNumber now:
@@ -141,16 +175,20 @@ bigmath.evaluate('1 / 3') // BigNumber, 0.33333333333333333333333333333333
 
     // change the configuration of math from Matrices to Arrays
     math.config({
-      matrix: 'Array'         // Choose 'Matrix' (default) or 'Array'
+      compute: {
+        Matrix: { defaultType: 'Array' }
+      }
     })
 
     // range will output an Array
     math.range(0, 4)          // Array [0, 1, 2, 3]
 
     // create a new instance of math.js with bignumber configuration
-    const bigmath = math.create({
-      number: 'BigNumber',    // Choose 'number' (default), 'BigNumber', or 'Fraction'
-      precision: 32           // 64 by default, only applicable for BigNumbers
+    const bigmath = create(all, {
+      number: 'BigNumber'
+      compute: {
+        BigNumber: { precision: 32 } // Would be 64 by default
+      }
     })
 
     // parser will parse numbers as BigNumber now:

docs/core/extension.md

@@ -219,7 +219,8 @@ where:
     -   `recreateOnConfigChange: boolean`. If true, the imported factory will be
         created again when there is a change in the configuration. This is for
         example used for the constants like `pi`, which is different depending
-        on the configsetting `number` which can be numbers or BigNumbers.
+        on the config option `compute.numberApproximate` which can be `number`
+        or `BigNumber`.
     -   `formerly: string`. If present, the created function will also be
         accessible on the instance under the name given by the value of
         `formerly` as a (deprecated) synonym for the specified `name`. This

docs/datatypes/bigints.md

@@ -13,21 +13,32 @@ math.bigint('42')
 ```
 
 Most functions can determine the type of output from the type of input:
-a `number` as input will return a `number` as output, a `bigint` as input returns
-a `bigint` as output. Functions which cannot determine the type of output
-from the input (for example `math.evaluate`) use the default number type `number`,
-which can be configured when instantiating math.js. To configure the use of
-`bigint` instead of [numbers](numbers.md) by default, configure math.js like:
+a `number` as input will return a `number` as output, a `bigint` as input
+returns a `bigint` as output, etc. However, when parsing a numeric literal
+like `'23'` or when computing the sum of an empty list of numbers, there is
+not any already-typed input to go by. The numeric type mathjs will try in such
+situations can be configured when instantiating math.js. To use `bigint`
+instead of [numbers](numbers.md),
 
 ```js
-math.config({
-  number: 'bigint'
-})
+import { create, all } from 'mathjs'
+const math = create(all)
+
+math.config({ number: 'bigint' })
 
 // use math
 math.evaluate('70000000000000000123')  // bigint 70000000000000000123n
 ```
 
+You may notice, however, in this setup the parser might encounter a non-integer
+literal like `2.5`, that can't be represented by a bigint. In such cases where
+the type specified by the top-level `number` configuration option is not
+appropriate, backup types can also be configured: the parser will use the
+`parse.numberFallback` option, that can be `number`, `BigNumber`, or
+`Fraction`; and computations (and similar items, like the values of physical
+constants) will use the `compute.numberApproximate` option, that can be
+`number` or `BigNumber`.
+
 ## Support
 
 All basic arithmetic functions in math.js support `bigint`. Since `bigint` can only hold integer values, it is not applicable to for example trigonometric functions. When using a `bigint` in a function that does not support it, like `sqrt`, it will convert the `bigint` into a regular `number` and then execute the function:

docs/datatypes/bignumbers.md

@@ -15,33 +15,44 @@ math.bignumber('2.3e+500') // BigNumber, 2.3e+500
 Most functions can determine the type of output from the type of input:
 a number as input will return a number as output, a BigNumber as input returns
 a BigNumber as output. Functions which cannot determine the type of output
-from the input (for example `math.evaluate`) use the default number type `number`,
+from the input (for example, parsing an expression using `math.evaluate`, or
+summing an empty list of numbers) use the default number type `number`,
 which can be configured when instantiating math.js. To configure the use of
 BigNumbers instead of [numbers](numbers.md) by default, configure math.js like:
 
 ```js
+import { create, all } from 'mathjs'
+const math = create(all)
+
 math.config({
-  number: 'BigNumber',      // Default type of number:
-                            // 'number' (default), 'BigNumber', or 'Fraction'
-  precision: 64,            // Number of significant digits for BigNumbers
-  relTol: 1e-60,
-  absTol: 1e-63
+  number: 'BigNumber' ,        // Default type of number: 'number' (default),
+                               // 'BigNumber', 'Fraction', or 'bigint'
+  compute: {
+    BigNumber: {
+      precision: 64            // Number of significant digits for BigNumbers
+    },
+    defaultRelTol: 1e-60,      // consider numbers equal if they differ by
+                               // less than this fraction of the size of the
+                               // larger,
+    defaultAbsTol: 1e-63       // or if their absolute difference is less than
+  }                            // this.
 })
 
 // use math
 math.evaluate('0.1 + 0.2')  // BigNumber, 0.3
 ```
 
 The default precision for BigNumber is 64 digits, and can be configured with
-the option `precision`. 
-
-Note that we also change the configuration of `relTol` and `absTol` 
-to be close to the precision limit of our BigNumbers. `relTol` and `absTol` are used for 
-example in relational and rounding functions (`equal`, `larger`, `smaller`, 
-`round`, `floor`, etc) to determine when a value is nearly equal, 
-see [Equality](numbers.md#equality). If we would leave `relTol` and `absTol`  unchanged, 
-having the default value of `1e-12` and `1e-15` respectively, we could get inaccurate and misleading 
-results since we're now working with a higher precision.
+the option `compute.BigNumber.precision`.
+
+Note that we also change the configuration of `compute.defaultRelTol` and
+`compute.defaultAbsTol` to be close to the precision limit of our BigNumbers.
+These options are used for example in relational and rounding functions
+(`equal`, `larger`, `smaller`, `round`, `floor`, etc) to determine when
+one value is nearly equal another, see [Equality](numbers.md#equality).
+If we would leave `defaultRelTol` and `defaultAbsTol` unchanged, having the
+default values of `1e-12` and `1e-15` respectively, we could get inaccurate
+and misleading results since we're now working with a higher precision.
 
 
 ## Support