system.q

The system library for Quasar: contains functions that are not built-in, but that are very often used.

If the function you are looking for, cannot be found in system.q (or any of the other .q files located in the Library directory), please feel free to implement this function, and send a copy of the code to bart.g.nosp@m.oossens@telin.u.nosp@m.gent.be.  This way, I can make sure that the function is distributed automatically in later versions of Quasar.

Summary
system.qThe system library for Quasar: contains functions that are not built-in, but that are very often used.
type-checking functions
isrealreturns 1 if x is real-valued, 0 otherwise
iscomplexreturns 1 if x is complex-valued, 0 otherwise
isscalarreturns 1 if x is scalar, 0 otherwise
isvectorreturns 1 if x is a vector (max.
ismatrixreturns 1 if x is a matrix (max.
iscubereturns 1 if x is a cube (max.
isfunctionreturns 1 if x is a function, 0 otherwise
isstringreturns 1 if x is a string, 0 otherwise
isobjectreturns 1 if x is an object, 0 otherwise
iskernelreturns 1 if x is a kernel function, 0 otherwise
iscellreturns 1 if x is a cell matrix, 0 otherwise
mathematical functions
nextpow2returns the next integer power of two
prevpow2returns the previous integer power of two
stdcomputes the standard deviation of all elements in a matrix
lerpperforms linear interpolation between a and b (with weight d)
conversion functions
num2strconverts a number to string
str2numconverts the string to a numerical value
general matrix functions
isemptyreturns 1 if the number of elements of x is 0 and 0 otherwise.
ndimsreturns the number of dimensions of x
flipupflips a two dimensional matrix upside-down (vertically)
fliplrflips a two dimensional matrix horizontally
anyreturns 1 if at least one element of x is non-zero, otherwise 0.
allreturns 1 if all elements of x are non-zero, otherwise 0.
diagCreates a diagonal matrix from a one dimensional vector.
diagCreates a diagonal matrix from a one dimension
diagExtracts the diagonal elements of a square real-valued matrix
diagExtracts the diagonal elements of a square complex-valued matrix
traceComputes the trace of a matrix (i.e.
circshiftApplies circular (periodic) shifting of a given vector, according to the relationship y[p] = x[p+d]
circshiftApplies circular (periodic) shifting of a given matrix, according to the relationship y[p] = x[p+d]
circshiftApplies circular (periodic) shifting of a given cube, according to the relationship y[p] = x[p+d]
circshiftApplies circular (periodic) shifting of a given complex-valued vector, according to the relationship y[p] = x[p+d]
circshiftApplies circular (periodic) shifting of a given complex-valued matrix, according to the relationship y[p] = x[p+d]
circshiftApplies circular (periodic) shifting of a given complex-valued cube, according to the relationship y[p] = x[p+d]
fftshift1Moves the DC components of a 1D discrete Fourier transform (DFT) to the center of the data.
ifftshift1The inverse operation of fftshift1
fftshift2Moves the DC components of a 2D discrete Fourier transform (DFT) to the center of the data
ifftshift2The inverse operation of fftshift2
fftshift3Moves the DC components of a 3D discrete Fourier transform (DFT) to the center of the data
ifftshift3The inverse operation of fftshift3
binsearch1dA 1D binary search algorithm: given a sorted vector x0, find the index of the element that is closest to ‘value’.
interp1_functionGet a device function that can be used for one-dimensional interpolation
interp1Performs one-dimensional interpolation
interp2_functionGet a device function that can be used for two-dimensional interpolation
interp2Performs two-dimensional interpolation
invert_functionComputes the inverse of a function
meshgridGenerate matrices with coordinates for a 2D Cartesian grid
meshgridGenerate matrices with coordinates for a 3D Cartesian grid
swapSwaps the values of two variables
dotprodComputes the dot product between two vectors
isnanCheck which elements of the matrix are NaN The isnan function is available as a built-in function inside kernel or device functions.
isinfCheck which elements of the matrix are infinite The isnan function is available as a built-in function inside kernel or device functions.
isfiniteCheck which elements of the matrix are finite The isnan function is available as a built-in function inside kernel or device functions.
sortinplace sort along the rows (currently: ascending sort).
sort2a non-inplace sort along the rows that also returns the indices (ascending sort) Internally uses a parallel bitsort algorithm.
mediancompute the median along the rows...
catHorizontal concatenation function: works for matrix, complex matrices and cell matrices
vertcatVertical concatenation function: works for matrix, complex matrices and cell matrices
findFinds the location of the non-zero elements of x.
sincThe normalized sinc function, defined as sin(pi*x)/(pi*x)
herm_transposeHermitian transpose of a matrix
kronComputes the Kronecker product of two matrices
periodizeComputes x modulo a: but in a sense that the result is in the range [0, a[, even for negative numbers
mirror_extPerforms mirror reflection of the input coordinate

type-checking functions

isreal

returns 1 if x is real-valued, 0 otherwise

iscomplex

returns 1 if x is complex-valued, 0 otherwise

isscalar

returns 1 if x is scalar, 0 otherwise

isvector

returns 1 if x is a vector (max. dimensionality 1), 0 otherwise

ismatrix

returns 1 if x is a matrix (max. dimensionality 2), 0 otherwise

iscube

returns 1 if x is a cube (max. dimensionality 3), 0 otherwise

isfunction

returns 1 if x is a function, 0 otherwise

isstring

returns 1 if x is a string, 0 otherwise

isobject

returns 1 if x is an object, 0 otherwise

iskernel

returns 1 if x is a kernel function, 0 otherwise

iscell

returns 1 if x is a cell matrix, 0 otherwise

mathematical functions

nextpow2

returns the next integer power of two

prevpow2

returns the previous integer power of two

std

computes the standard deviation of all elements in a matrix

lerp

performs linear interpolation between a and b (with weight d)

conversion functions

num2str

converts a number to string

str2num

converts the string to a numerical value

general matrix functions

isempty

returns 1 if the number of elements of x is 0 and 0 otherwise.

ndims

returns the number of dimensions of x

flipup

flips a two dimensional matrix upside-down (vertically)

fliplr

flips a two dimensional matrix horizontally

any

returns 1 if at least one element of x is non-zero, otherwise 0.

all

returns 1 if all elements of x are non-zero, otherwise 0.

diag

Creates a diagonal matrix from a one dimensional vector.  The non-diagonal elements are set to zero.

function y : mat = diag(x : vec)

Parameters

xa vector containing the diagonal elements

diag

Creates a diagonal matrix from a one dimension

function y : cmat = diag(x : cvec)

Parameters

xa vector containing the diagonal elements

diag

Extracts the diagonal elements of a square real-valued matrix

function y : vec = diag(x : mat)

Parameters

xa square matrix to extract the diagonal elements from.

diag

Extracts the diagonal elements of a square complex-valued matrix

function y : cvec = diag(x : cmat)

Parameters

xa square matrix to extract the diagonal elements from.

trace

Computes the trace of a matrix (i.e. the sum of the diagonal elements)

function y = trace(x)

Parameters

xa square input matrix

circshift

Applies circular (periodic) shifting of a given vector, according to the relationship y[p] = x[p+d]

function y : vec = circshift(x : vec, d : ivec1)

Parameters

xan input vector
dan integer displacement

circshift

Applies circular (periodic) shifting of a given matrix, according to the relationship y[p] = x[p+d]

function y : mat = circshift(x : mat, d : ivec2)

Parameters

xan input matrix
dan integer displacement vector of length 2

circshift

Applies circular (periodic) shifting of a given cube, according to the relationship y[p] = x[p+d]

function y : cube = circshift(x : cube, d : ivec3)

Parameters

xan input cube
dan integer displacement vector of length 3

circshift

Applies circular (periodic) shifting of a given complex-valued vector, according to the relationship y[p] = x[p+d]

function y : cvec = circshift(x : cvec, d : ivec1)

Parameters

xan input vector
dan integer displacement

circshift

Applies circular (periodic) shifting of a given complex-valued matrix, according to the relationship y[p] = x[p+d]

function y : cmat = circshift(x : cmat, d : ivec2)

Parameters

xan input matrix
dan integer displacement vector of length 2

circshift

Applies circular (periodic) shifting of a given complex-valued cube, according to the relationship y[p] = x[p+d]

function y : ccube = circshift(x : ccube, d : ivec3)

Parameters

xan input cube
dan integer displacement vector of length 3

fftshift1

Moves the DC components of a 1D discrete Fourier transform (DFT) to the center of the data.  For higher dimensional data - it is presumed that the FFT data is stored in the last dimension

function y : cube = fftshift1(x : cube)
function y : ccube = fftshift1(x : ccube)

Parameters

xthe input data

See also

ifftshift1

ifftshift1

The inverse operation of fftshift1

function y : cube = ifftshift1(x : cube)
function y : ccube = ifftshift1(x : ccube)

Parameters

xthe input data

See also

fftshift1

fftshift2

Moves the DC components of a 2D discrete Fourier transform (DFT) to the center of the data

function y : cube = fftshift2(x : cube)
function y : ccube = fftshift2(x : ccube)

Parameters

xthe input data

See also

ifftshift2

ifftshift2

The inverse operation of fftshift2

function y : cube = ifftshift2(x : cube)
function y : ccube = ifftshift2(x : ccube)

Parameters

xthe input data

See also

fftshift2

fftshift3

Moves the DC components of a 3D discrete Fourier transform (DFT) to the center of the data

function y : cube = fftshift3(x : cube)
function y : ccube = fftshift3(x : ccube)

Parameters

xthe input data

See also

ifftshift3

ifftshift3

The inverse operation of fftshift3

function y : cube = ifftshift3(x : cube)
function y : ccube = ifftshift3(x : ccube)

Parameters

xthe input data

See also

fftshift3

binsearch1d

A 1D binary search algorithm: given a sorted vector x0, find the index of the element that is closest to ‘value’.

function [mid : int] = __device__ binsearch1d(x0 : vec'unchecked, value : scalar)

Parameters

x0a sorted vector

interp1_function

Get a device function that can be used for one-dimensional interpolation

function fn : [__device__ scalar->scalar] = interp1_function(
  x0 : vec'unchecked, y0 : vec'unchecked, interpolation : string = "linear", uniform = 1)

Parameters

x0x-values of the input vector
y0y-values of the input vector interpolation : the interpolation method to use
  • ”nearest” - nearest neighbor interpolation
  • ”linear” - linear interpolation
  • ”cubic” - cubic interpolation uniform : specifies whether the input data is uniformly spaced (uniform=1) or sorted (uniform=0).  In case of sorted input data, a binary search algorithm will be used.

Remarks

The function returns a device function that can subsequently be used in other kernel functions.  Function closures are used to store the data [x0, y0] Note that x0 does not have to be uniformly-spaced.  In case of other spacings, a binary search algorithm is employed for the look-up.

interp1

Performs one-dimensional interpolation

function y = interp1(x0 : vec,y0 : vec,x,interpolation="linear",uniform=1)

Parameters

x0x-values of the input vector
y0y-values of the input vector
xthe x-values to interpolate interpolation : the interpolation method to use
  • ”nearest” - nearest neighbor interpolation
  • ”linear” - linear interpolation
  • ”cubic” - cubic interpolation uniform : specifies whether the input data is uniformly spaced (uniform=1) or sorted (uniform=0).  In case of sorted input data, a binary search algorithm will be used.

interp2_function

Get a device function that can be used for two-dimensional interpolation

function fn : [__device__ vec2->scalar] = interp2_function(

x0 : vec’unchecked, y0 : vec’unchecked, z0 : mat’unchecked, interpolation : string = “linear”)

Parameters

x0x-values of the input vector (along the 2nd dimension)
y0y-values of the input vector (along the 1st dimension) interpolation : the interpolation method to use
  • ”nearest” - nearest neighbor interpolation
  • ”linear” - linear interpolation
  • ”cubic” - cubic interpolation

Remarks

The function returns a device function that can subsequently be used in other kernel functions.  Function closures are used to store the data [x0, y0]

interp2

Performs two-dimensional interpolation

function z : cube = interp2(x0:vec,y0:vec,z0:mat,x:cube,y:cube,interpolation="linear")

Parameters

x0vector of x-values
y0vector of y-values
z0matrix with z-values - the points (x0,y0,z0) define a surface
xthe x-values to interpolate
ythe y-values to interpolate interpolation : the interpolation method to use
  • ”nearest” - nearest neighbor interpolation
  • ”linear” - linear interpolation
  • ”cubic” - cubic interpolation

invert_function

Computes the inverse of a function

function [x0,y] = invert_function(x : vec)

meshgrid

Generate matrices with coordinates for a 2D Cartesian grid

function [x : mat, y : mat] = meshgrid(range_x : vec, range_y : vec)

Note: the matrix indexing is as follows: Y x X

Parameters

range_xvalues for the x-axis of the Cartesian grid
range_yvalues for the y-axis of the Cartesian grid
xoutput matrix with x-coordinates
youtput matrix with y-coordinates

meshgrid

Generate matrices with coordinates for a 3D Cartesian grid

function [x : cube, y : cube, z : cube] = meshgrid(
     range_x : vec, range_y : vec, range_z : vec)

Parameters

range_xvalues for the x-axis of the Cartesian grid
range_yvalues for the y-axis of the Cartesian grid
range_zvalues for the z-axis of the Cartesian grid
xoutput matrix with x-coordinates
youtput matrix with y-coordinates
zoutput matrix with z-coordinates

swap

Swaps the values of two variables

function [y1, y2] = swap(x1, x2)

dotprod

Computes the dot product between two vectors

function z = dotprod(x, y)

Remarks

The dotprod function is available as a built-in function inside kernel or device functions.  The following definition is necessary to ensure that ‘dotprod’ can also be used in regular functions.

isnan

Check which elements of the matrix are NaN The isnan function is available as a built-in function inside kernel or device functions.  The following definition is necessary to ensure that ‘isnan’ can also be used in regular functions.

function y = isnan(x)

isinf

Check which elements of the matrix are infinite The isnan function is available as a built-in function inside kernel or device functions.  The following definition is necessary to ensure that ‘isinf’ can also be used in regular functions.

function y = isinf(x)

isfinite

Check which elements of the matrix are finite The isnan function is available as a built-in function inside kernel or device functions.  The following definition is necessary to ensure that ‘isfinite’ can also be used in regular functions.

function y = isfinite(x)

sort

inplace sort along the rows (currently: ascending sort).  Internally uses a parallel bitsort algorithm.

function [] = sort(x)

Parameters

xthe data values to sort

sort2

a non-inplace sort along the rows that also returns the indices (ascending sort) Internally uses a parallel bitsort algorithm.

function [y, ind] = sort2(x)

Parameters

xthe data values to sort
youtput values of the sorted data
indcontains the resulting indices

median

compute the median along the rows...

function y : vec = median(x : mat)

Parameters

xa matrix with values to compute the median from
ythe output vector

cat

Horizontal concatenation function: works for matrix, complex matrices and cell matrices

function y = cat(a, b)

vertcat

Vertical concatenation function: works for matrix, complex matrices and cell matrices

function y = vertcat(a, b)

find

Finds the location of the non-zero elements of x.  The result is a list of positions [[x0, y0, z0], [x1, y1, z1], ...].

function y : mat = find(x : cube, mode : string = "all", dim : int = 0)

Parameters

xa data cube
ya matrix with coordinates of the positions of size Nx3 where N is the number of elements of x != 1, i.e. sum(x!=1)
modethe search mode
  • ”all”: lists all occurences of elements != 1
  • ”first”: returns the first occurence of an element != 1

sinc

The normalized sinc function, defined as sin(pi*x)/(pi*x)

sinc = __device__ (x : scalar) -> (x == 0.0) ? 1.0 : sin(pi*x)/(pi*x)

herm_transpose

Hermitian transpose of a matrix

function y : scalar = herm_transpose(x : scalar)
function y : cscalar = herm_transpose(x : cscalar)
function y : mat = herm_transpose(x : mat)
function y : cmat = herm_transpose(x : cmat)

See also

transpose

kron

Computes the Kronecker product of two matrices

function y = kron(a, b)

periodize

Computes x modulo a: but in a sense that the result is in the range [0, a[, even for negative numbers

function y : cube = periodize(x : cube, a : scalar)
function y : cube = periodize(x : cube, a : cube)

mirror_ext

Performs mirror reflection of the input coordinate

function y : cube = mirror_ext(x : cube, a : scalar)
function y : cube = mirror_ext(x : cube, a : cube)
The inverse operation of fftshift1
Moves the DC components of a 1D discrete Fourier transform (DFT) to the center of the data.
The inverse operation of fftshift2
Moves the DC components of a 2D discrete Fourier transform (DFT) to the center of the data
The inverse operation of fftshift3
Moves the DC components of a 3D discrete Fourier transform (DFT) to the center of the data
Transposes a matrix.
Close