Module VectorPolar.c

Detailed Description

Convert complex vector components from rectangular coordinates to polar coordinates.

Author

T. D. Creighton, A. M. Sintes

Let u be an object of type COMPLEX8Vector, and let a and b be objects of type REAL4Vector.

The LALCVectorAbs( &status, &a, &u ) function computes the magnitude of a complex vector u:
a.data[i] = sqrt(u.data[i].re^2 + v.data[i].im^2 ).

The LALCVectorAngle( &status, &a, &u ) function computes the phase angle of a complex vector u in the interval \([-\pi, \pi]\) radians:
a.data[i] = atan2( u.data[i].im, v.data[i].re).

The LALUnwrapREAL4Angle( &status, &a, &b ) function corrects the radian phase angles of a real vector b by adding multiples of \(\pm\pi\) when the absolute jumps between consecutive angle elements are greater than \(\pi\) radians. This function detects branch cut crossings, but it can be fooled by sparse, rapidly changing phase values.

The double-precision functions are similar.

Algorithm

The algorithm for LALUnwrapREAL4Angle() and LALUnwrapREAL8Angle() (Inspired from the MATLAP function unwrap):

a = in->data;
b = out->data;
n = out->length;
 
cumsum = 0.0;
phaseI = *a;
*b = phaseI;
--n;
 
while (n-- > 0)
{
  ++a;
  ++b;
  phaseII = *a;
  diffph = phaseII - phaseI;
  phaseI = phaseII;
 
  cumsum += LAL_TWOPI*( (diffph < - LAL_PI) - (diffph > LAL_PI) );
 
  *b= phaseII + cumsum;
}

Notes

For the LALUnwrapREAL4Angle() and LALUnwrapREAL8Angle() functions, a, and b should not point to the same memory location (a != b).

Prototypes
int	XLALCOMPLEX8VectorAbs (REAL4Vector *out, const COMPLEX8Vector *in)
	computes the magnitudes of a vector of complex numbers More...
int	XLALCOMPLEX16VectorAbs (REAL8Vector *out, const COMPLEX16Vector *in)
	computes the magnitudes of a vector of complex numbers More...
int	XLALCOMPLEX8VectorArg (REAL4Vector *out, const COMPLEX8Vector *in)
	computes the arguments of a vector of complex numbers More...
int	XLALCOMPLEX16VectorArg (REAL8Vector *out, const COMPLEX16Vector *in)
	computes the arguments of a vector of complex numbers More...
int	XLALREAL4VectorUnwrapAngle (REAL4Vector *out, const REAL4Vector *in)
	corrects the radian phase angles of a real vector by adding multiples of pi when the absolute jumps between consecutive angle elements are greater pi radians More...
int	XLALREAL8VectorUnwrapAngle (REAL8Vector *out, const REAL8Vector *in)
	corrects the radian phase angles of a real vector by adding multiples of pi when the absolute jumps between consecutive angle elements are greater pi radians More...
void	LALCVectorAbs (LALStatus *status, REAL4Vector *out, const COMPLEX8Vector *in)
	UNDOCUMENTED. More...
void	LALZVectorAbs (LALStatus *status, REAL8Vector *out, const COMPLEX16Vector *in)
	UNDOCUMENTED. More...
void	LALCVectorAngle (LALStatus *status, REAL4Vector *out, const COMPLEX8Vector *in)
	UNDOCUMENTED. More...
void	LALZVectorAngle (LALStatus *status, REAL8Vector *out, const COMPLEX16Vector *in)
	UNDOCUMENTED. More...
void	LALUnwrapREAL4Angle (LALStatus *status, REAL4Vector *out, const REAL4Vector *in)
	UNDOCUMENTED. More...
void	LALUnwrapREAL8Angle (LALStatus *status, REAL8Vector *out, const REAL8Vector *in)
	UNDOCUMENTED. More...

Function Documentation

XLALCOMPLEX8VectorAbs()

int XLALCOMPLEX8VectorAbs	(	REAL4Vector *	out,
		const COMPLEX8Vector *	in
	)

computes the magnitudes of a vector of complex numbers

Definition at line 92 of file VectorPolar.c.

XLALCOMPLEX16VectorAbs()

int XLALCOMPLEX16VectorAbs	(	REAL8Vector *	out,
		const COMPLEX16Vector *	in
	)

computes the magnitudes of a vector of complex numbers

Definition at line 107 of file VectorPolar.c.

XLALCOMPLEX8VectorArg()

int XLALCOMPLEX8VectorArg	(	REAL4Vector *	out,
		const COMPLEX8Vector *	in
	)

computes the arguments of a vector of complex numbers

Definition at line 123 of file VectorPolar.c.

XLALCOMPLEX16VectorArg()

int XLALCOMPLEX16VectorArg	(	REAL8Vector *	out,
		const COMPLEX16Vector *	in
	)

computes the arguments of a vector of complex numbers

Definition at line 138 of file VectorPolar.c.

XLALREAL4VectorUnwrapAngle()

int XLALREAL4VectorUnwrapAngle	(	REAL4Vector *	out,
		const REAL4Vector *	in
	)

corrects the radian phase angles of a real vector by adding multiples of pi when the absolute jumps between consecutive angle elements are greater pi radians

Definition at line 158 of file VectorPolar.c.

XLALREAL8VectorUnwrapAngle()

int XLALREAL8VectorUnwrapAngle	(	REAL8Vector *	out,
		const REAL8Vector *	in
	)

corrects the radian phase angles of a real vector by adding multiples of pi when the absolute jumps between consecutive angle elements are greater pi radians

Definition at line 186 of file VectorPolar.c.

LALCVectorAbs()

void LALCVectorAbs	(	LALStatus *	status,
		REAL4Vector *	out,
		const COMPLEX8Vector *	in
	)

UNDOCUMENTED.

Definition at line 212 of file VectorPolar.c.

LALZVectorAbs()

void LALZVectorAbs	(	LALStatus *	status,
		REAL8Vector *	out,
		const COMPLEX16Vector *	in
	)

UNDOCUMENTED.

Definition at line 243 of file VectorPolar.c.

LALCVectorAngle()

void LALCVectorAngle	(	LALStatus *	status,
		REAL4Vector *	out,
		const COMPLEX8Vector *	in
	)

UNDOCUMENTED.

Definition at line 274 of file VectorPolar.c.

LALZVectorAngle()

void LALZVectorAngle	(	LALStatus *	status,
		REAL8Vector *	out,
		const COMPLEX16Vector *	in
	)

UNDOCUMENTED.

Definition at line 305 of file VectorPolar.c.

LALUnwrapREAL4Angle()

void LALUnwrapREAL4Angle	(	LALStatus *	status,
		REAL4Vector *	out,
		const REAL4Vector *	in
	)

UNDOCUMENTED.

Definition at line 335 of file VectorPolar.c.

LALUnwrapREAL8Angle()

void LALUnwrapREAL8Angle	(	LALStatus *	status,
		REAL8Vector *	out,
		const REAL8Vector *	in
	)

UNDOCUMENTED.

Definition at line 368 of file VectorPolar.c.