view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        $B = -$A;           # $B is the negative of $A

- `~`

    Transpose.

        $B = ~$A;           # $B is the transpose of $A

- `abs`

    Absolute value.

        $B = abs $A;        # $B contains absolute values of $A

- `int`

    Truncate to integer.

        $B = int $A;        # $B contains only integers

# IMPROVING THE SOLUTION OF LINEAR SYSTEMS

The methods that do an explicit or implicit matrix left division accept some
additional parameters. If these parameters are specified, the matrix left
division is done repeatedly in an iterative way, which often gives a better
solution.

## Background

The linear system of equations

    $A * $x = $y

can be solved for `$x` with

    $x = $y -> mldiv($A);

Ideally `$A * $x` should equal `$y`, but due to numerical errors, this is not
always the case. The following illustrates how to improve the solution `$x`
computed above:

    $r = $A -> mmuladd($x, -$y);    # compute the residual $A*$x-$y
    $d = $r -> mldiv($A);           # compute the delta for $x
    $x -= $d;                       # improve the solution $x

This procedure is repeated, and at each step, the absolute error

    ||$A*$x - $y|| = ||$r||

and the relative error

    ||$A*$x - $y|| / ||$y|| = ||$r|| / ||$y||

are computed and compared to the tolerances. Once one of the stopping criteria
is satisfied, the algorithm terminates.

## Stopping criteria

The algorithm stops when at least one of the errors are within the specified
tolerances or the maximum number of iterations is reached. If the maximum number
of iterations is reached, but noen of the errors are within the tolerances, a
warning is displayed and the best solution so far is returned.

## Parameters

- MaxIter

    The maximum number of iterations to perform. The value must be a positive
    integer. The default is 20.

- RelTol

    The limit for the relative error. The value must be a non-negative. The default
    value is 1e-19 when perl is compiled with long doubles or quadruple precision,
    and 1e-9 otherwise.

- AbsTol

    The limit for the absolute error. The value must be a non-negative. The default
    value is 0.

- Debug

    If this parameter does not affect when the algorithm terminates, but when set to
    non-zero, some information is displayed at each step.

## Example

If

    $A = [[  8, -8, -5,  6, -1,  3 ],
          [ -7, -1,  5, -9,  5,  6 ],
          [ -7,  8,  9, -2, -4,  3 ],
          [  3, -4,  5,  5,  3,  3 ],
          [  9,  8, -3, -4,  1,  6 ],
          [ -8,  9, -1,  3,  5,  2 ]];

    $y = [[  80, -13 ],
          [  -2, 104 ],
          [ -57, -27 ],
          [  47, -28 ],
          [   5,  77 ],
          [  91, 133 ]];

the result of `$x = $y -> mldiv($A);`, using double precision arithmetic,
is the approximate solution

    $x = [[ -2.999999999999998, -5.000000000000000 ],
          [ -1.000000000000000,  3.000000000000001 ],
          [ -5.999999999999997, -8.999999999999996 ],
          [  8.000000000000000, -2.000000000000003 ],
          [  6.000000000000003,  9.000000000000002 ],
          [  7.999999999999997,  8.999999999999995 ]];

The residual `$res = $A -> mmuladd($x, -$y);` is

    $res = [[  1.24344978758018e-14,  1.77635683940025e-15 ],
            [  8.88178419700125e-15, -5.32907051820075e-15 ],
            [ -1.24344978758018e-14,  1.77635683940025e-15 ],
            [ -7.10542735760100e-15, -4.08562073062058e-14 ],
            [ -1.77635683940025e-14, -3.81916720471054e-14 ],
            [  1.24344978758018e-14,  8.43769498715119e-15 ]];

and the delta `$dx = $res -> mldiv($A);` is

    $dx = [[   -8.592098303124e-16, -2.86724066474914e-15 ],
           [ -7.92220125658508e-16, -2.99693950082398e-15 ],
           [ -2.22533360993874e-16,  3.03465504177947e-16 ],