# assert_cond2reltol

Suggests a relative error, computed from the condition number.

## Calling Sequence

                rtol = assert_cond2reltol ( condition )
                rtol = assert_cond2reltol ( condition , offset )

## Parameters

condition :

  a matrix of doubles, the condition number. The condition number must be strictly positive.

offset :

  a matrix of doubles, a shift for the number of required decimal digits (default offset=0). For example, offset=1 increases the accuracy requirement (decreases the relative tolerance by a factor 10^-1), offset=-1 decreases the accuracy requirement (increases the relative tolerance by a factor 10^1).

rtol :

  a matrix of doubles, the relative tolerance. The relative tolerance is strictly positive, lower than 1.

## Description

Depending on the condition number, returns the corresponding relative tolerance.

Any optional parameter equal to the empty matrix [] is set to its default value.

We emphasize that this relative tolerance is only a suggestion. Indeed, there may be correct reasons of using a lower or a higher relative tolerance.

- Consider the case where an excellent algorithm is able to make accurate computations, even for an ill-conditionned problem. In this case, we may require more accuracy (positive offset).

- Consider the case where there is a trade-off between performance and accuracy, where performance wins. In this case, we may require less accuracy (negative offset).

Any scalar input argument is expanded to a matrix of doubles of the same size as the other input arguments.

We compute the number of required digits d, then the relative tolerance is 10^-d.

## Examples

    assert_cond2reltol ( 0 ) // 1.110D-16
    assert_cond2reltol ( 1 ) // 1.110D-16
    assert_cond2reltol ( 1.e1 ) // 1.110D-15
    assert_cond2reltol ( 1.e2 ) // 1.110D-14
    assert_cond2reltol ( 1.e3 ) // 1.110D-13
    assert_cond2reltol ( 1.e16 ) // 1
    assert_cond2reltol ( 1.e17 ) // 1
    assert_cond2reltol ( 1.e18 ) // 1

    // Matrix input.
    condition = [0,1,10,100,1000,1.D13,1.D14,1.D15,1.D16,1.D17,1.D18];
    expected = [1.110D-16    1.110D-16    1.110D-15    1.110D-14    1.110D-13    0.0011102    0.0111022    0.1110223    1.    1.    1.];
    assert_cond2reltol ( condition )

    // Using offset
    // Negative offset : require less accuracy
    assert_cond2reltol ( 1.e2 , [0 -1] ) // [1.1D-14 1.1D-13]
    // Positive offset : requires more accuracy
    // See that the impact of offset is constrained.
    assert_cond2reltol ( 1.e2 , [0 1 2 3] ) // [1.1D-14 1.1D-15 1.1D-16 1.1D-16]
    // Negative offset
    // See that the impact of offset is constrained.
    assert_cond2reltol ( 1.e14 , [0 -1 -2 -3] ) // [1.1D-02    1.1D-01    1 1]

    // Plot the relative tolerance depending on the condition
    condition = logspace(0,18,1000);
    r = assert_cond2reltol ( condition );
    plot(condition,r)
    h=gcf();
    h.children.log_flags="lln";
    h.children.children.children.thickness=4;
    xt = h.children.x_ticks;
    xt.locations = 10^(0:2:18)';
    xt.labels = ["10^0";"10^2";"10^4";"10^6";"10^8";"10^10";"10^12";"10^14";"10^16";"10^18"];
    h.children.x_ticks=xt;
    yt = h.children.y_ticks;
    yt.locations = 10^-(0:2:18)';
    yt.labels = ["10^0";"10^-2";"10^-4";"10^-6";"10^-8";"10^-10";"10^-12";"10^-14";"10^-16";"10^-18"];
    h.children.y_ticks=yt;
    xtitle("Relative tolerance","Condition","Relative tolerance");
    r = assert_cond2reltol ( condition , +3 );
    plot(condition,r,"r")
    r = assert_cond2reltol ( condition , -3 );
    plot(condition,r,"g")
    legend(["Offset=0","Offset=+3","Offset=-3"]);

## History

5.4.0
Function introduced