naginterfaces.library.blas.zhousg

naginterfaces.library.blas.zhousg(alpha, x, tol)

zhousg generates a complex elementary reflection.

For full information please refer to the NAG Library document for f06hr

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f06/f06hrf.html

Parameters

alphacomplex

The scalar $\alpha$.

xcomplex, array-like, shape $\left(n\right)$

The $n$-element vector $x$.

tolfloat

The value $\text{tol}$.

Returns

alphacomplex

The scalar $\beta$.

xcomplex, ndarray, shape $\left(n\right)$

The referenced elements are overwritten by details of the complex elementary reflection.

thetacomplex

The scalar $\theta$.

Raises

NagValueError

(errno $4$)

On entry, error in parameter $\text{incx}$.

Constraint: $\text{incx}>0$.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

zhousg generates details of a complex elementary reflection (Householder matrix), $P$, such that

$$\begin{array}{c}P\left(\begin{array}{c}\alpha \\ x\end{array}\right)=\left(\begin{array}{c}\beta \\ 0\end{array}\right)\end{array}$$

where $P$ is unitary, $\alpha$ is a complex scalar, $\beta$ is a real scalar, and $x$ is an $n$-element complex vector.

$P$ is given in the form

$$\begin{array}{c}P=I-\gamma \left(\begin{array}{c}\zeta \\ z\end{array}\right)\left(\begin{array}{cc}\zeta & z^H\end{array}\right)\text{,}\end{array}$$

where $z$ is an $n$-element complex vector, $\gamma$ is a complex scalar such that $Re\left(\gamma \right)=1$, and $\zeta$ is a real scalar. $\gamma$ and $\zeta$ are returned in a single complex value $\theta =(\zeta ,Im\left(\gamma \right))$. Thus $\zeta =Re\left(\theta \right)$ and $\gamma =(1,Im\left(\theta \right))$.

If $x$ is such that

$$max(\left|Re\left(x_i\right)\right|,\left|Im\left(x_i\right)\right|)\le max(\text{tol},ϵmax(\left|Re\left(\alpha \right)\right|,\left|Im\left(\alpha \right)\right|))\text{,}$$

where $ϵ$ is the machine precision and $\text{tol}$ is a user-supplied tolerance, then:

either $\theta$ is set to $0$, in which case $P$ can be taken to be the unit matrix;

or $\theta$ is set so that $Re\left(\theta \right)\le 0$ and $\theta \ne 0$, in which case

$$\begin{array}{c}P=\left(\begin{array}{cc}\theta & 0\\ 0& I\end{array}\right)\text{.}\end{array}$$

Otherwise $1\le Re\left(\theta \right)\le \sqrt{2}$.