関数sqrt3 マニュアル

(The documentation of function sqrt3)

Last Update: 2021/11/30

◆機能・用途(Purpose)

実数の3乗根を計算する。
Calculate the cubic root of a real number.

◆形式(Format)

#include <doublemath.h>
inline double sqrt3(const double d)

◆引数(Arguments)

d	3乗根を求めたい実数。 A real number for which the cubic root is needed.

◆戻り値(Return value)

\(d\)の3つの3乗根のうち実数のもの。
The cubic root of \(d\); there are three cubic roots, and the one which is a real number is returned.

◆使用例(Example)

a=sqrt3(8.0); //2.0
b=sqrt3(0.0); //0.0
c=sqrt3(-0.125); //-0.5

◆補足(Additional notes)

3乗根を計算するには関数powが利用できる。しかしながらpowは第1引数が非負であることを前提とした関数であり、負の数の3乗根を計算する場合には「絶対値の3乗根の\(-1\)倍」を計算しなければならない。このように実数の符号に応じて場合分けをしなければ面倒であるので符号に関わらず1行で書けるように関数にしたのがsqrt3である。この関数を用いることで、本来なら

if(d>=0){
a=pow(d,1.0/3.0);
}else{
cube_root=-pow(-d,1.0/3.0);
}

と書かなければならなかったものを

a=sqrt3(d);

と書けるようになり、プログラムが簡潔になる。
To compute the cubic root of a real number, function pow is available. However, this function assumes a non-negative value for the 1st argument. To calculate the cubic root of a negative value, “the cubic root of the absolute value of the real number multiplied with \(-1\)” must be computed. The purpose of function sqrt3 is to avoid this branching operation. Using this function, the cubic root can be calculated by only one line regardless of the sign of the real number. Namely, a code

if(d>=0){
&nsbp;a=pow(d,1.0/3.0);
}else{
&nsbp;cube_root=-pow(-d,1.0/3.0);
}

can be rewritten in a simpler form as

a=sqrt3(d);

by the use of this function. In this way, the code becomes brief.

また、中身が0であるか否かの判定をdoublecmp関数を用いて行うことにより、 0に非常に近い数の3乗根を取った場合の不安定を回避する狙いもある。 0は何乗しても0であるが、0から非常にわずかにずれた数は 3乗根を取ると0から離れる方向に変化するため、数値計算のわずかな誤差によって本来ゼロであるべき数が非常に小さなノンゼロの数(例えば\(10^{-18}\))になった場合に、その1/3乗を取ると誤差が増幅されてしまう(上の例では\(10^{-6}\)となる)。しかし、doublecmp関数を用いればこの問題は回避できる。関数sqrt3では内部でdoublecmp関数を用いてゼロに非常に近い数の3乗根をゼロとするようにしている。この仕様により、デフォルトのZERO_THRESHOLDを用いる場合には sqrt(1.0e-18)=0.0となる。
Another purpose of this function is to avoid a numerical instability in case of a value very close to 0. Note that a value which is very close to but not exactly same as 0 will leave from zero by taking the cubic root. For example, consider a situation where a value which should theoretically be 0 becomes a very small non-zero value (e.g., \(10^{-18}\)) due to numerical errors. Taking a cubic root, this error is amplified to \(10^{-6}\). This problem can be avoided by the use of function doublecmp. The function sqrt3 internally calls doublecmp to force the cubic root of a very small non-zero value to zero. Awing to this algorithm, sqrt(1.0e-18)=0.0 as long as the default value of ZERO_THRESHOLD is used.