LatticeCovering.h File Reference

Author:: Reinhard Prix Header-file defining the API for the lattice-covering functions.

#include <gsl/gsl_matrix.h>
#include <lal/LALStdlib.h>
#include <lal/LALDatatypes.h>
#include <lal/AVFactories.h>
#include <lal/PtoleMetric.h>

Include dependency graph for LatticeCovering.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct tagINT4VectorList

doubly linked list of INT4-vectors (lattice-vectors) More...

struct tagREAL8VectorList

doubly linked list of REAL8-vectors (physical vectors) More...

Defines

#define LATTICECOVERING_ENULL   1

#define LATTICECOVERING_ENONULL   2

#define LATTICECOVERING_EMEM   3

#define LATTICECOVERING_EINPUT   4

#define LATTICECOVERING_ELIST   5

#define LATTICECOVERING_EFUNC   6

#define LATTICECOVERING_MSGENULL   "Arguments contained an unexpected null pointer"

#define LATTICECOVERING_MSGENONULL   "Output pointer is not NULL"

#define LATTICECOVERING_MSGEMEM   "Out of memory"

#define LATTICECOVERING_MSGEINPUT   "Invald input parameter"

#define LATTICECOVERING_MSGELIST   "Error occurred in list-handling ..."

#define LATTICECOVERING_MSGEFUNC   "Sub-routine failed"

Typedefs

typedef tagINT4VectorList INT4VectorList

doubly linked list of INT4-vectors (lattice-vectors)

typedef tagREAL8VectorList REAL8VectorList

doubly linked list of REAL8-vectors (physical vectors)

Enumerations

enum LatticeType { LATTICE_TYPE_ANSTAR = 0, LATTICE_TYPE_CUBIC, LATTICE_TYPE_LAST }

enum-type for denoting several types of lattice More...

Functions

NRCSID (LATTICECOVERINGH,"$Id: LatticeCovering.h,v 1.5 2007/01/31 00:18:41 reinhard Exp $")

void LALLatticeCovering (LALStatus *, REAL8VectorList **covering, REAL8 coveringRadius, const gsl_matrix *metric, const REAL8Vector *startPoint, BOOLEAN(*isInside)(const REAL8Vector *point), LatticeType latticeType)

Central function of this module: produce a lattice-covering of given lattice-type for the given parameter-space with constant metric.

void LALLatticeFill (LALStatus *, REAL8VectorList **fillGrid, const gsl_matrix *generator, const REAL8Vector *startPoint, BOOLEAN(*isInside)(const REAL8Vector *point))

Fill the given parameter-space by a lattice defined by the specified generating matrix.

int XLALFindCoveringGenerator (gsl_matrix **outmatrix, LatticeType type, REAL8 coveringRadius, const gsl_matrix *gij)

Construct the full-rank generating matrix of given type, for covering a space of given (constant) metric and a given covering Radius.

int XLALReduceGenerator2FullRank (gsl_matrix **outmatrix, const gsl_matrix *inmatrix)

"Reduce" a general (non-quadratic) generating matrix M with rank(M) <= cols(M) into a quadratic generator of full rank.

int XLALGetLatticeGenerator (gsl_matrix **outmatrix, UINT4 dimension, LatticeType type)

Return a (not necessarily quadratic) n-dimensional generating matrix for one of several possible lattices (currently possible: cubic or $A_n^*$ ).

REAL8 XLALMetricScalarProduct (const gsl_vector *vector1, const gsl_vector *vector2, const gsl_matrix *metric)

Scalar product of two vectors with respect to the given metric $\vec{v}_1 \cdot \vec{v}_2 = g_{i j}\, v_1^i \,v_2^j$ .

REAL8VectorList * XLALREAL8VectorListAddEntry (REAL8VectorList *head, const REAL8Vector *entry)

Add a new element at the end of the list 'head', _copy_ the given entry there, and return pointer to the new list-entry.

void XLALREAL8VectorListDestroy (REAL8VectorList *head)

'List-destructor' for REAL8VectorList: free a complete list.

REAL8Vector * XLALgsl2LALmetric (const gsl_matrix *gmetric)

Translate a symmetric gsl_matrix into a 'LAL-encoded' REAL8Vector, using the index-convention l = a + b*(b+1) if a <= b, see PMETRIC_INDEX(a,b).

gsl_matrix * XLALmetric2gsl (const REAL8Vector *metric)

Convert a LAL-encoded metric (REAL8Vector) into a symmetric gsl_matrix.

Variables

INT4VectorList empty_INT4VectorList

REAL8VectorList empty_REAL8VectorList

Detailed Description

Author:: Reinhard Prix Header-file defining the API for the lattice-covering functions.

Date:: 2005

Id: LatticeCovering.h,v 1.5 2007/01/31 00:18:41 reinhard Exp

Definition in file LatticeCovering.h.

Define Documentation

#define LATTICECOVERING_ENULL 1

Definition at line 68 of file LatticeCovering.h.

#define LATTICECOVERING_ENONULL 2

Definition at line 69 of file LatticeCovering.h.

#define LATTICECOVERING_EMEM 3

Definition at line 70 of file LatticeCovering.h.

#define LATTICECOVERING_EINPUT 4

Definition at line 71 of file LatticeCovering.h.

#define LATTICECOVERING_ELIST 5

Definition at line 72 of file LatticeCovering.h.

#define LATTICECOVERING_EFUNC 6

Definition at line 73 of file LatticeCovering.h.

#define LATTICECOVERING_MSGENULL "Arguments contained an unexpected null pointer"

Definition at line 75 of file LatticeCovering.h.

#define LATTICECOVERING_MSGENONULL "Output pointer is not NULL"

Definition at line 76 of file LatticeCovering.h.

#define LATTICECOVERING_MSGEMEM "Out of memory"

Definition at line 77 of file LatticeCovering.h.

#define LATTICECOVERING_MSGEINPUT "Invald input parameter"

Definition at line 78 of file LatticeCovering.h.

#define LATTICECOVERING_MSGELIST "Error occurred in list-handling ..."

Definition at line 79 of file LatticeCovering.h.

#define LATTICECOVERING_MSGEFUNC "Sub-routine failed"

Definition at line 80 of file LatticeCovering.h.

Typedef Documentation

typedef struct tagINT4VectorList INT4VectorList

doubly linked list of INT4-vectors (lattice-vectors)

typedef struct tagREAL8VectorList REAL8VectorList

doubly linked list of REAL8-vectors (physical vectors)

Enumeration Type Documentation

enum LatticeType

enum-type for denoting several types of lattice

Enumerator:

LATTICE_TYPE_ANSTAR	An*: optimal covering grid.
LATTICE_TYPE_CUBIC	standard cubic grid: Zn
LATTICE_TYPE_LAST

Definition at line 85 of file LatticeCovering.h.

Function Documentation

NRCSID	(	LATTICECOVERINGH	,
		"$Id: LatticeCovering.	h,
		v 1.5 2007/01/31 00:18:41 reinhard Exp $"
	)

void LALLatticeCovering	(	LALStatus *	status,
		REAL8VectorList **	covering,
		REAL8	coveringRadius,
		const gsl_matrix *	metric,
		const REAL8Vector *	startPoint,
		BOOLEAN()(const REAL8Vector point)	isInside,
		LatticeType	latticeType
	)

Central function of this module: produce a lattice-covering of given lattice-type for the given parameter-space with constant metric.

For optimal covering, use latticeType=0, namely the An* lattice, which is the best known covering-lattice up to dimension 23, see [CS99]

Algorithm:

1) use XLALFindCoveringGenerator() to get the generator of the given lattice.

2) use it to LALLatticeFill() the space.

Parameters:

covering	[out] final covering-grid
coveringRadius	[in] covering radius
metric	[in] constant metric
startPoint	[in] start-point in the covering-region
isInside	[in] boundary-condition

Definition at line 103 of file LatticeCovering.c.

void LALLatticeFill	(	LALStatus *	status,
		REAL8VectorList **	fillGrid,
		const gsl_matrix *	generator,
		const REAL8Vector *	startPoint,
		BOOLEAN()(const REAL8Vector point)	isInside
	)

Fill the given parameter-space by a lattice defined by the specified generating matrix.

Note1:: The input generating-matrix (generator) must already be scaled correctly to the required covering radius, also, it needs to be in canonical full-rank square matrix form.

Note2:: As always in this module, the generating matrix contains the lattice-vectors as rows

Parameters:

fillGrid	[out] fillGrid final fill-grid (physical points)
generator	[in] SQUARE generating matrix for lattice
startPoint	[in] physical startpoint for filling
isInside	[in] boundary-condition

Definition at line 167 of file LatticeCovering.c.

int XLALFindCoveringGenerator	(	gsl_matrix **	outmatrix,
		LatticeType	type,
		REAL8	coveringRadius,
		const gsl_matrix *	gij
	)

Construct the full-rank generating matrix of given type, for covering a space of given (constant) metric and a given covering Radius.

Note1:: the returned generator is a square matrix, with lattice-vectors in the matrix-rows (as always in this module!)

Note2:: the memory for 'outmatrix' is allocated here with gsl_matrix_alloc() and needs to be free by the caller via gsl_matrix_free()

Algorithm:

1) get the (generally non-square) generating matrix for the lattice
2) reduce it to a full-rank square generating matrix by expressing the lattice vectors in the basis of their spanned space
3) translate the basis-vectors to the coordinates cooresponding to the given metric
4) scale the generating matrix to the given covering radius

Parameters:

outmatrix	[out] generating matrix for covering lattice
type	[in] type of lattice
coveringRadius	[in] desired covering radius
gij	[in] (constant) metric of covering space

Definition at line 591 of file LatticeCovering.c.

int XLALReduceGenerator2FullRank	(	gsl_matrix **	outmatrix,
		const gsl_matrix *	inmatrix
	)

"Reduce" a general (non-quadratic) generating matrix M with rank(M) <= cols(M) into a quadratic generator of full rank.

The input matrix can have columns >= rows, the rows reprenting the lattice vectors. This algorithm simply proceeds by constructing an (Euclidean!) orthonormal basis out of the lattice vectors (using GramSchmidt), and then expressing the lattice-vectors in this new basis.

Note:: the memory for 'outmatrix' is allocated in here via gsl_matrix_alloc() and has to be free'ed by the caller via gsl_matrix_free() !

Parameters:

outmatrix	[out] full-rank square generating matrix
inmatrix	[in] generating matrix (cols >= rows)

Definition at line 691 of file LatticeCovering.c.

int XLALGetLatticeGenerator	(	gsl_matrix **	outmatrix,
		UINT4	dimension,
		LatticeType	type
	)

Return a (not necessarily quadratic) n-dimensional generating matrix for one of several possible lattices (currently possible: cubic or $A_n^*$ ).

See [CS99] for the definition and properties of these lattices.

Note1:: Because these lattices are intended for covering, we scale them so that their covering-radius is unity. This allows the user to later-on scale these easily to any desired covering-radius without having to know anything about the lattice... (Remembering that if you scale the generator of a lattice by , then the covering radius R scales as )

Note2:: The memory for 'outmatrix' is allocated in here via gsl_matrix_alloc() and has to be free'ed by the caller via gsl_matrix_free() !

Parameters:

outmatrix	[out] generating matrix
dimension	[in] number of dimensions
type	[in] type of lattice

Definition at line 795 of file LatticeCovering.c.

REAL8 XLALMetricScalarProduct	(	const gsl_vector *	vector1,
		const gsl_vector *	vector2,
		const gsl_matrix *	metric
	)

Scalar product of two vectors with respect to the given metric $\vec{v}_1 \cdot \vec{v}_2 = g_{i j}\, v_1^i \,v_2^j$ .

Definition at line 405 of file LatticeCovering.c.

REAL8VectorList* XLALREAL8VectorListAddEntry	(	REAL8VectorList *	head,
		const REAL8Vector *	entry
	)

Add a new element at the end of the list 'head', _copy_ the given entry there, and return pointer to the new list-entry.

Note:: This function is rather permissive in that it takes the vector-dimension from the new entry 'el', without requiring this to be equal to the dimension of the other list-entries...

Definition at line 939 of file LatticeCovering.c.

void XLALREAL8VectorListDestroy ( REAL8VectorList * head )

'List-destructor' for REAL8VectorList: free a complete list.

Note:: 'head' will be freed too, so make sure not to pass a non-freeable head (like an automatic variabe)

Definition at line 1063 of file LatticeCovering.c.

REAL8Vector* XLALgsl2LALmetric ( const gsl_matrix * gmetric )

Translate a symmetric gsl_matrix into a 'LAL-encoded' REAL8Vector, using the index-convention l = a + b*(b+1) if a <= b, see PMETRIC_INDEX(a,b).

Definition at line 1150 of file LatticeCovering.c.

gsl_matrix* XLALmetric2gsl ( const REAL8Vector * metric )

Convert a LAL-encoded metric (REAL8Vector) into a symmetric gsl_matrix.

Definition at line 1184 of file LatticeCovering.c.

Variable Documentation

INT4VectorList empty_INT4VectorList

Definition at line 62 of file LatticeCovering.c.

REAL8VectorList empty_REAL8VectorList

Definition at line 63 of file LatticeCovering.c.

Generated on Sun Sep 7 03:07:56 2008 for LAL by

1.5.2


Data Structures
struct	tagINT4VectorList
	doubly linked list of INT4-vectors (lattice-vectors) More...
struct	tagREAL8VectorList
	doubly linked list of REAL8-vectors (physical vectors) More...
Defines
#define	LATTICECOVERING_ENULL 1
#define	LATTICECOVERING_ENONULL 2
#define	LATTICECOVERING_EMEM 3
#define	LATTICECOVERING_EINPUT 4
#define	LATTICECOVERING_ELIST 5
#define	LATTICECOVERING_EFUNC 6
#define	LATTICECOVERING_MSGENULL "Arguments contained an unexpected null pointer"
#define	LATTICECOVERING_MSGENONULL "Output pointer is not NULL"
#define	LATTICECOVERING_MSGEMEM "Out of memory"
#define	LATTICECOVERING_MSGEINPUT "Invald input parameter"
#define	LATTICECOVERING_MSGELIST "Error occurred in list-handling ..."
#define	LATTICECOVERING_MSGEFUNC "Sub-routine failed"
Typedefs
typedef tagINT4VectorList	INT4VectorList
	doubly linked list of INT4-vectors (lattice-vectors)
typedef tagREAL8VectorList	REAL8VectorList
	doubly linked list of REAL8-vectors (physical vectors)
Enumerations
enum	LatticeType { LATTICE_TYPE_ANSTAR = 0, LATTICE_TYPE_CUBIC, LATTICE_TYPE_LAST }
	enum-type for denoting several types of lattice More...
Functions
	NRCSID (LATTICECOVERINGH,"$Id: LatticeCovering.h,v 1.5 2007/01/31 00:18:41 reinhard Exp $")
void	LALLatticeCovering (LALStatus , REAL8VectorList covering, REAL8 coveringRadius, const gsl_matrix metric, const REAL8Vector startPoint, BOOLEAN(isInside)(const REAL8Vector *point), LatticeType latticeType)
	Central function of this module: produce a lattice-covering of given lattice-type for the given parameter-space with constant metric.
void	LALLatticeFill (LALStatus , REAL8VectorList fillGrid, const gsl_matrix generator, const REAL8Vector startPoint, BOOLEAN(isInside)(const REAL8Vector *point))
	Fill the given parameter-space by a lattice defined by the specified generating matrix.
int	XLALFindCoveringGenerator (gsl_matrix *outmatrix, LatticeType type, REAL8 coveringRadius, const gsl_matrix gij)
	Construct the full-rank generating matrix of given type, for covering a space of given (constant) metric and a given covering Radius.
int	XLALReduceGenerator2FullRank (gsl_matrix *outmatrix, const gsl_matrix inmatrix)
	"Reduce" a general (non-quadratic) generating matrix M with rank(M) <= cols(M) into a quadratic generator of full rank.
int	XLALGetLatticeGenerator (gsl_matrix **outmatrix, UINT4 dimension, LatticeType type)
	Return a (not necessarily quadratic) n-dimensional generating matrix for one of several possible lattices (currently possible: cubic or ).
REAL8	XLALMetricScalarProduct (const gsl_vector vector1, const gsl_vector vector2, const gsl_matrix *metric)
	Scalar product of two vectors with respect to the given metric $\vec{v}_1 \cdot \vec{v}_2 = g_{i j}\, v_1^i \,v_2^j$ .
REAL8VectorList *	XLALREAL8VectorListAddEntry (REAL8VectorList head, const REAL8Vector entry)
	Add a new element at the end of the list 'head', _copy_ the given entry there, and return pointer to the new list-entry.
void	XLALREAL8VectorListDestroy (REAL8VectorList *head)
	'List-destructor' for REAL8VectorList: free a complete list.
REAL8Vector *	XLALgsl2LALmetric (const gsl_matrix *gmetric)
	Translate a symmetric gsl_matrix into a 'LAL-encoded' REAL8Vector, using the index-convention l = a + b*(b+1) if a <= b, see PMETRIC_INDEX(a,b).
gsl_matrix *	XLALmetric2gsl (const REAL8Vector *metric)
	Convert a LAL-encoded metric (REAL8Vector) into a symmetric gsl_matrix.
Variables
INT4VectorList	empty_INT4VectorList
REAL8VectorList	empty_REAL8VectorList