Lattice point generators and lattice vector analysis / transformation. More...

#include <math.h>
#include <stdbool.h>
#include <assert.h>
#include <stddef.h>
#include <stdlib.h>
#include "vectors.h"

Include dependency graph for lattices.h:

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

Go to the source code of this file.

Data Structures
struct	PGen
	Generic lattice point generator type. More...

struct	PGenReturnDataBulk
	Metadata generated by the fetch*() methods from PGenClassInfo. More...

struct	PGenReturnData
	Generic PGen return type that might contain point represented in any of the supported coordinate systems. More...

struct	PGenZReturnData
	PGen single-point return data type (1D). More...

struct	PGenPolReturnData
	PGen single-point return data type (2D, polar coordinates). More...

struct	PGenSphReturnData
	PGen single-point return data type (3D, spherical coordinates). More...

struct	PGenCart2ReturnData
	PGen single-point return data type (2D, cartesian coordinates). More...

struct	PGenCart3ReturnData
	PGen single-point return data type (3D, cartesian coordinates). More...

struct	PGenClassInfo
	PGen class metadata. More...

struct	points2d_rordered_t

struct	triangular_lattice_gen_t

struct	honeycomb_lattice_gen_t

Macros
#define	M_SQRT3 1.7320508075688772935274463415058724

#define	M_SQRT3_2 (M_SQRT3/2)

#define	M_1_SQRT3 0.57735026918962576450914878050195746

#define	BASIS_RTOL 1e-13

Typedefs
typedef enum LatticeDimensionality	LatticeDimensionality

typedef cart2_t	point2d

typedef struct PGen	PGen
	Generic lattice point generator type. More...

typedef enum PGenPointFlags	PGenPointFlags

typedef struct PGenReturnDataBulk	PGenReturnDataBulk
	Metadata generated by the fetch*() methods from PGenClassInfo.

typedef struct PGenReturnData	PGenReturnData
	Generic PGen return type that might contain point represented in any of the supported coordinate systems.

typedef struct PGenZReturnData	PGenZReturnData
	PGen single-point return data type (1D).

typedef struct PGenPolReturnData	PGenPolReturnData
	PGen single-point return data type (2D, polar coordinates).

typedef struct PGenSphReturnData	PGenSphReturnData
	PGen single-point return data type (3D, spherical coordinates).

typedef struct PGenCart2ReturnData	PGenCart2ReturnData
	PGen single-point return data type (2D, cartesian coordinates).

typedef struct PGenCart3ReturnData	PGenCart3ReturnData
	PGen single-point return data type (3D, cartesian coordinates).

typedef struct PGenClassInfo	PGenClassInfo
	PGen class metadata. More...

typedef enum PGen_1D_incrementDirection	PGen_1D_incrementDirection

typedef struct triangular_lattice_gen_privstuff_t	triangular_lattice_gen_privstuff_t

Enumerations
enum	LatticeDimensionality { LAT1D = 1 , LAT2D = 2 , LAT3D = 4 , SPACE1D = 8 , SPACE2D = 16 , SPACE3D = 32 , LAT_1D_IN_3D = 33 , LAT_2D_IN_3D = 34 , LAT_3D_IN_3D = 40 , LAT_ZONLY = 64 , LAT_XYONLY = 128 , LAT_1D_IN_3D_ZONLY = 97 , LAT_2D_IN_3D_XYONLY = 162 }

enum	PGenPointFlags { PGEN_NOTDONE = 2 , PGEN_OLD_R = 1 , PGEN_SINGLE_R = 16 , PGEN_AT_Z = 4 , PGEN_AT_XY = 8 , PGEN_METHOD_UNAVAILABLE = 2048 , PGEN_DONE = 0 , PGEN_COORDS_CART1 = QPMS_COORDS_CART1 , PGEN_COORDS_CART2 = QPMS_COORDS_CART2 , PGEN_COORDS_CART3 = QPMS_COORDS_CART3 , PGEN_COORDS_POL = QPMS_COORDS_POL , PGEN_COORDS_SPH = QPMS_COORDS_SPH , PGEN_COORDS_BITRANGE = QPMS_COORDS_BITRANGE }

enum	PGen_1D_incrementDirection { PGEN_1D_INC_FROM_ORIGIN , PGEN_1D_INC_TOWARDS_ORIGIN }

enum	LatticeType2 { OBLIQUE = 1 , RECTANGULAR = 2 , SQUARE = 4 , RHOMBIC = 5 , EQUILATERAL_TRIANGULAR = 3 , RIGHT_ISOSCELES =SQUARE , PARALLELOGRAMMIC =OBLIQUE , CENTERED_RHOMBIC =RECTANGULAR , RIGHT_TRIANGULAR =RECTANGULAR , CENTERED_RECTANGULAR =RHOMBIC , ISOSCELE_TRIANGULAR =RHOMBIC , RIGHT_ISOSCELE_TRIANGULAR =SQUARE , HEXAGONAL =EQUILATERAL_TRIANGULAR }

enum	LatticeFlags { NOT_ORTHOGONAL = 0 , ORTHOGONAL_01 = 1 , ORTHOGONAL_12 = 2 , ORTHOGONAL_02 = 4 }

enum	TriangularLatticeOrientation { TRIANGULAR_VERTICAL , TRIANGULAR_HORIZONTAL }

Functions
static bool	LatticeDimensionality_checkflags (LatticeDimensionality a, LatticeDimensionality flags_a_has_to_contain)

static point2d	point2d_fromxy (const double x, const double y)

int	qpms_reduce_lattice_basis (double *b, const size_t bsize, const size_t ndim, double delta)
	Lattice basis reduction. More...

static PGenReturnData	PGen_next_nf (struct PGen *g)
	Generate a point with any of the next-methods.

static PGenReturnDataBulk	PGen_fetch_any (struct PGen g, size_t nmemb, anycoord_point_t target)
	Generate multiple points with PGen in any coordinate system.

static PGenReturnData	PGen_next (struct PGen *g)
	Generate a point with any of the next-methods or fetch-methods.

static PGenReturnDataBulk	PGen_fetch_sph (struct PGen g, size_t nmemb, sph_t target)
	Generate multiple points in spherical coordinates.

static PGenReturnDataBulk	PGen_fetch_cart3 (struct PGen g, size_t nmemb, cart3_t target)
	Generate multiple points in 3D cartesian coordinates.

static PGenReturnDataBulk	PGen_fetch_pol (struct PGen g, size_t nmemb, pol_t target)
	Generate multiple points in polar coordinates.

static PGenReturnDataBulk	PGen_fetch_cart2 (struct PGen g, size_t nmemb, cart2_t target)
	Generate multiple points in 2D cartesian coordinates.

static PGenReturnDataBulk	PGen_fetch_z (struct PGen g, size_t nmemb, double target)
	Generate multiple points in 1D cartesian coordinates.

static void	PGen_destroy (PGen *g)
	Deallocate and invalidate a PGen point generator.

static PGenZReturnData	PGen_next_z (PGen *g)
	Generate a point in a 1D real space.

static PGenSphReturnData	PGen_next_sph (PGen *g)
	Generate a point in a 3D real space (spherical coordinates).

static PGenPolReturnData	PGen_next_pol (PGen *g)
	Generate a point in a 2D real space (polar coordinates).

static PGenCart3ReturnData	PGen_next_cart3 (PGen *g)
	Generate a point in a 3D real space (cartesian coordinates).

static PGenCart2ReturnData	PGen_next_cart2 (PGen *g)
	Generate a point in a 2D real space (cartesian coordinates).

static bool	PGenSph_notDone (PGenSphReturnData data)

static bool	PGenCart3_notDone (PGenCart3ReturnData data)

static PGenCart3ReturnData	PGenReturnDataConv_sph_cart3 (PGenSphReturnData sphdata)
	Standard PGen spherical coordinates -> 3d cartesian convertor.

static PGenSphReturnData	PGenReturnDataConv_cart3_sph (PGenCart3ReturnData c)
	Standard PGen 3d cartesian -> spherical coordinates convertor.

PGen	PGen_FromPoints2DArray_new (const point2d *points, size_t len)
	PGen_FromPoint2DArray constructor.

PGen	PGen_1D_new_minMaxR (double period, double offset, double minR, bool inc_minR, double maxR, bool inc_maxR, PGen_1D_incrementDirection incdir)
	PGen_1D point generator constructor. More...

PGen	PGen_xyWeb_new (cart2_t b1, cart2_t b2, double rtol, cart2_t offset, double minR, bool inc_minR, double maxR, bool inc_maxR)

size_t	PGen_xyWeb_sizecap (cart2_t b1, cart2_t b2, double rtol, cart2_t offset, double minR, bool inc_minR, double maxR, bool inc_maxR)
	Returns a number larger or equal than the number of all the points generated by a PGen_xyWeb.

PGen	PGen_LatticeRadialHeap2D_new (cart2_t b1, cart2_t b2, cart2_t offset, double minR, bool inc_minR, double maxR, bool inc_maxR)

PGen	PGen_LatticeRadialHeap3D_new (const cart3_t b1, const cart3_t b2, const cart3_t b3, const cart3_t offset, double minR, bool inc_minR, double maxR, bool inc_maxR)

PGen	PGen_shifted_new (PGen orig, cart3_t shift)

void	l2d_reduceBasis (cart2_t in1, cart2_t in2, cart2_t out1, cart2_t out2)

void	l3d_reduceBasis (const cart3_t in[3], cart3_t out[3])

void	l2d_shortestBase3 (cart2_t i1, cart2_t i2, cart2_t o1, cart2_t o2, cart2_t *o3)

int	l2d_shortestBase46 (cart2_t i1, cart2_t i2, cart2_t o1, cart2_t o2, cart2_t o3, cart2_t o4, cart2_t o5, cart2_t o6, double rtol)

int	l2d_shortestBase46_arr (cart2_t i1, cart2_t i2, cart2_t *oarr, double rtol)

bool	l2d_is_obtuse_r (cart2_t i1, cart2_t i2, double rtol)

bool	l2d_is_obtuse (cart2_t i1, cart2_t i2)

LatticeType2	l2d_classifyLattice (cart2_t b1, cart2_t b2, double rtol)

LatticeFlags	l2d_detectRightAngles (cart2_t b1, cart2_t b2, double rtol)

LatticeFlags	l3d_detectRightAngles (const cart3_t basis[3], double rtol)

int	l2d_cellCornersWS (cart2_t i1, cart2_t i2, cart2_t o1, cart2_t o2, cart2_t o3, cart2_t o4, cart2_t o5, cart2_t o6, double rtol)

int	l2d_cellCornersWS_arr (cart2_t i1, cart2_t i2, cart2_t *oarr, double rtol)

int	l2d_reciprocalBasis1 (cart2_t b1, cart2_t b2, cart2_t rb1, cart2_t rb2)

int	l2d_reciprocalBasis2pi (cart2_t b1, cart2_t b2, cart2_t rb1, cart2_t rb2)

double	l3d_reciprocalBasis1 (const cart3_t direct_basis[3], cart3_t reciprocal_basis[3])

double	l3d_reciprocalBasis2pi (const cart3_t direct_basis[3], cart3_t reciprocal_basis[3])

double	l2d_unitcell_area (cart2_t b1, cart2_t b2)

double	l2d_hexWebInCircleRadius (cart2_t b1, cart2_t b2)

points2d_rordered_t *	points2d_rordered_frompoints (const point2d *orig_base, size_t nmemb, double rtol, double atol)

points2d_rordered_t *	points2d_rordered_shift (const points2d_rordered_t *orig, point2d shift, double rtol, double atol)

points2d_rordered_t *	points2d_rordered_scale (const points2d_rordered_t *orig, double factor)

void	points2d_rordered_free (points2d_rordered_t *)

static point2d	points2d_rordered_get_point (const points2d_rordered_t *ps, int r_order, int i)

static double	points2d_rordered_get_r (const points2d_rordered_t *ps, int r_order)

ptrdiff_t	points2d_rordered_locate_r (const points2d_rordered_t *, double r)

points2d_rordered_t	points2d_rordered_annulus (const points2d_rordered_t *orig, double minr, bool minr_inc, double maxr, bool maxr_inc)

size_t	qpms_emptylattice2_modes_maxfreq (double **target_freqs, cart2_t b1_rec, cart2_t b2_rec, double rtol, cart2_t k, double wave_speed, double maxfreq)
	Gives the frequencies of empty lattice modes at a given wave vector k up to maxfreq and one more. More...

void	qpms_emptylattice2_modes_nearest (double target[2], cart2_t b1_rec, cart2_t b2_rec, double rtol, cart2_t k, double wave_speed, double omega)
	Gives the frequencies of two empty lattice modes nearest to omega at a given wave vector k. More...

static TriangularLatticeOrientation	reverseTriangularLatticeOrientation (TriangularLatticeOrientation o)

triangular_lattice_gen_t *	triangular_lattice_gen_init (double a, TriangularLatticeOrientation ori, bool include_origin, int halfoffset)

const points2d_rordered_t *	triangular_lattice_gen_getpoints (const triangular_lattice_gen_t *g)

int	triangular_lattice_gen_extend_to_r (triangular_lattice_gen_t *g, double r)

int	triangular_lattice_gen_extend_to_steps (triangular_lattice_gen_t *g, int maxsteps)

void	triangular_lattice_gen_free (triangular_lattice_gen_t *g)

honeycomb_lattice_gen_t *	honeycomb_lattice_gen_init_h (double h, TriangularLatticeOrientation ori)

honeycomb_lattice_gen_t *	honeycomb_lattice_gen_init_a (double a, TriangularLatticeOrientation ori)

int	honeycomb_lattice_gen_extend_to_steps (honeycomb_lattice_gen_t *g, int maxsteps)

int	honeycomb_lattice_gen_extend_to_r (honeycomb_lattice_gen_t *g, double r)

void	honeycomb_lattice_gen_free (honeycomb_lattice_gen_t *g)

Variables
static const PGenZReturnData	PGenZDoneVal = {PGEN_DONE, 0}

static const PGenPolReturnData	PGenPolDoneVal = {PGEN_DONE, {0,0}}

static const PGenSphReturnData	PGenSphDoneVal = {PGEN_DONE, {0,0,0}}

static const PGenCart2ReturnData	PGenCart2DoneVal = {PGEN_DONE, {0,0}}

static const PGenCart3ReturnData	PGenCart3DoneVal = {PGEN_DONE, {0,0,0}}

const PGenClassInfo	PGen_FromPoint2DArray
	2D point generator that simply iterates over an existing array of Point2d.

const PGenClassInfo	PGen_1D
	1D equidistant point generator.

const PGenClassInfo	PGen_xyWeb

const PGenClassInfo	PGen_LatticeRadialHeap2D

const PGenClassInfo	PGen_LatticeRadialHeap3D

const PGenClassInfo	PGen_shifted
	A metagenerator generating points from another generator shifted by a constant.

Detailed Description

Lattice point generators and lattice vector analysis / transformation.

Typedef Documentation

◆ PGen

typedef struct PGen PGen

Generic lattice point generator type.

A bit of OOP-in-C brainfuck here.

The basic principle of operation is following: Instead of a list (array) of points, an initialized PGen object is passed to a function that does something over a set of points. Each time PGen-type object is "called" (more specifically, one of the "methods" specified in the PGenClassInfo structure in c, it returns PGenReturnData which contains a point in given coordinates (depending on the generator class) and some metadata.

After the last generated point, the generator frees all internal memory and returns PGenSphReturnData with PGEN_NOTDONE flag unset (the rest shall be considered invalid data). The caller can also decide not to use the rest and end getting the points even when the PGEN_NOTDONE was set in the last returned data. In such case, the caller shall call PGen_destroy() manually.

Methods

The standard wrapper "methods" to generate a single point in a given coordinate system are

Memory management policy

The basic PGen structure shall be allocated on stack (it's only two pointers), everything internal goes on heap.

◆ PGenClassInfo

typedef struct PGenClassInfo PGenClassInfo

PGen class metadata.

This structure determines the behaviour of the PGen instance pointing to it.

For generating a single point, use the next() method. For generating up to N points in a single call, use the fetch() method.

It is strongly recommended that at least the native-coordinate fetch method and the native-coordinate next method are implemented.

Usually, each generator uses internally one "native" coordinate system (in lattice generators, this will typically be nD cartesian coordinates) in which the next() method gives its result.

One does not have to explicitly implement every single method.

TODO doc about the default transformations etc.

Enumeration Type Documentation

◆ PGenPointFlags

enum PGenPointFlags

Enumerator
PGEN_NOTDONE	The most important flag: when this is not set, the interation ended – other data returned should be considered nonsense and at this point, the generator should have de-allocated all internal memory.
PGEN_OLD_R	Set if the r-coordinate is not different than in the previous generated point (so radial parts of the calculation have to be redone). Optional.
PGEN_SINGLE_R	Set if the r-coordinate has not changed between the first and the last point generated in the current call. Only for the bulk generator methods. Optional.
PGEN_AT_Z	Set if the point(s) lie(s) at the z-axis (theta is either 0 or M_PI).
PGEN_AT_XY	Set if the point(s) lie(s) in the xy-plane (theta is M_PI2).
PGEN_METHOD_UNAVAILABLE	Set if no suitable method exists (no point generated).
PGEN_DONE	Convenience identifier, not an actual flag.

Function Documentation

◆ PGen_1D_new_minMaxR()

PGen PGen_1D_new_minMaxR	(	double	period,
		double	offset,
		double	minR,
		bool	inc_minR,
		double	maxR,
		bool	inc_maxR,
		PGen_1D_incrementDirection	incdir
	)

PGen_1D point generator constructor.

Parameters

period	Distance between points.
offset	Lattice offset from zero.
minR	Lower bound of \|z\| of the generated points.
inc_minR	Include also \|z\| == minR (if applicable).
maxR	Upper bound of \|z\| of the generated points.
inc_maxR	Include also \|z\| == maxR if applicable.
incdir	Order of generated points.

◆ qpms_emptylattice2_modes_maxfreq()

size_t qpms_emptylattice2_modes_maxfreq	(	double **	target_freqs,
		cart2_t	b1_rec,
		cart2_t	b2_rec,
		double	rtol,
		cart2_t	k,
		double	wave_speed,
		double	maxfreq
	)

Gives the frequencies of empty lattice modes at a given wave vector k up to maxfreq and one more.

The frequencies are saved to a newly allocated array *target_freqs (to be deallocated using free() by the caller).

Returns: Number of found mode frequencies lower or equal than maxfreq plus one.

Parameters

b1_rec	First reciprocal lattice base vector
b2_rec	Second reciprocal lattice base vector
rtol	Relative tolerance to detect right angles
k	The wave vector
wave_speed	Wave speed in a given medium (i.e. vacuum speed / refractive index).
maxfreq	The maximum frequency.

◆ qpms_emptylattice2_modes_nearest()

void qpms_emptylattice2_modes_nearest	(	double	target[2],
		cart2_t	b1_rec,
		cart2_t	b2_rec,
		double	rtol,
		cart2_t	k,
		double	wave_speed,
		double	omega
	)

Gives the frequencies of two empty lattice modes nearest to omega at a given wave vector k.

Parameters

target	Target array with lower ([0]) and upper ([1]) frequency.
b1_rec	First reciprocal lattice base vector
b2_rec	Second reciprocal lattice base vector
rtol	Relative tolerance to detect right angles
k	The wave vector
wave_speed	Wave speed in a given medium (i.e. vacuum speed / refractive index).
omega	The frequency around which the frequencies are searched.

◆ qpms_reduce_lattice_basis()

int qpms_reduce_lattice_basis	(	double *	b,
		const size_t	bsize,
		const size_t	ndim,
		double	delta
	)

Lattice basis reduction.

This is currenty a bit naïve implementation of Lenstra-Lenstra-Lovász algorithm.

The reduction happens in-place, i.e. the basis vectors in b are replaced with the reduced basis.

Parameters

b	Array of dimension [bsize][ndim].
bsize	Number of the basis vectors (dimensionality of the lattice).
ndim	Dimension of the space into which the lattice is embedded.
delta	Lovász condition parameter \( \delta \). Polynomial time complexity guaranteed for \(\delta \in (1/4,1)\).

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ PGen

Methods

Memory management policy

◆ PGenClassInfo

Enumeration Type Documentation

◆ PGenPointFlags

Function Documentation

◆ PGen_1D_new_minMaxR()

◆ qpms_emptylattice2_modes_maxfreq()

◆ qpms_emptylattice2_modes_nearest()

◆ qpms_reduce_lattice_basis()