Calculation (CALC) in ALG Language

Table of contents

Design Inspirations

Let’s have a look at the example below.

\sqrt(\accu(\pow(\abs(A_{1,:,2:5} - B^{-1}), 2))) * c * A @ (D ./ E^T) + \sin(f_{2})

Well, that looks like \(\rm\LaTeX\), right? The familiar \ character starting a command (sorry, that’s called macro in LaTeX), and inverse as ^{-1}, transpose ^T, and subscript with _{}!

Well, let’s write the above example in LaTeX (through some informal Matlab style subscript)

\[\begin{equation} \left\|\mathbf{A}_{1,:,2:5}-\mathbf{B}^{-1}\right\|_2\cdot c\mathbf{A}\cdot\left(\mathbf{D}\oslash\mathbf{E}^\mathsf{T}+\mathrm{ones}(\sin(\mathbf{f}_2))\right), \end{equation}\]

where \(\mathbf{A},\mathbf{B},\mathbf{D},\mathbf{E}\) are matrices, \(c\) is a scalar, \(\mathbf{f}\) is a vector, \(\oslash\) represents the element-wise division, and \(\mathrm{ones}\) represent a matrix with all elements as \(1\).

\left\|\mathbf{A}_{1,:,2:5}-\mathbf{B}^{-1}\right\|_2\cdot c\mathbf{A}\cdot\left(\mathbf{D}\oslash\mathbf{E}^\mathsf{T}+\mathrm{ones}(\sin(\mathbf{f}_2))\right)

As a matter of fact, that can be even more like \(\rm\LaTeX\), with all brackets can be converted to {}, though parameters are separated by , not another {}. For LaTeX fans, you may even use ^\star or ^\ast for conjugate in addition to the normal ^*. Happy TeXing :-)

To make the language simple and efficiently convertible to C++, Python and Matlab/Octave, some syntaxes from Python and Matlab are adopted in addition to The LaTeX look.

Syntax Basics

There are commands starting with backslash (\), operators and superscript, subscripts.

Variable Naming

  • Variable names should not contain reserved characters !@#$%^&*()[]{}\|/-+=~,.<>?:;"'`.
  • Variable name should also not end with underscore (_).
  • Digit can not be the first character of variable name.
  • Variable name should not clash with reserved keywords.

Note that whitespace does not matter and are actually removed before parsing.

Operators

Operator List

Operators Description
+, - (Unary/Binary) plus/minus
* Scalar and scalar multiplication, scalar and matrix multiplication
@ Matrix and matrix multiplication
.*, ./ Element-wise multiplication, division
! Logical NOT
(), {} Command call
<, <=, >, >= Relational operator \(<, \leq, >, \geq\)
==, != Relational \(=\) and \(\neq\)
&& Logical AND
|| Logical OR
= Assign

Matrix and matrix multiplication is different from matrix scalar and scalar scalar multiplication. You should distinguish the use of * and @. (This is like the Python syntax.)

Element-wise multiplication .* is different from matrix multiplication @. (This is like the Matlab syntax.)

Operator Precedence

The following table lists the precedence and associativity of ALG CALC operators. Operators are listed top to bottom, in descending precedence.

Precedence Operators Description Associativity
1 (), {} Command call Left-to-right
2 ^T, ^H, ^t, ^i, ^*, ^{-1} Matrix superscript Left-to-right
3 _{} Matrix subscript Left-to-right
4 !, +, - Logical NOT, unary plus/minus Right-to-left
5 *, @, .*, ./ Matrix (and element-wise) multiplication, division Left-to-right
6 +, - Addition and subtraction Left-to-right
7 <, <=, >, >= Relational operator \(<, \leq, >, \geq\) Left-to-right
8 ==, != Relational \(=\) and \(\neq\) Left-to-right
9 && Logical AND Left-to-right
10 || Logical OR Left-to-right
11 = Assign Right-to-left

The above table is so similar to that of C++. Well, indeed, and it is adapted from C++ Reference.

Commands

Command Usage Basics

Here are the basic rules for command usage:

  • Commands start with character \;
  • Command call has parameter list inside brackets (), and you may optionally use {} if you want the syntax more like \(\rm\LaTeX\);
  • Parameters are separated by comma (,).

The function naming convention mainly follows that of Armadillo which is also similar to MATLAB.

\dictionary

Generate a dictionary matrix for beamspace (virtual) representation.

Math Representation

The complex dictionary matrix is used in compressed sensing (CS). For a uniform linear array (ULA) with size \(M\) and grid size \(M^G\), the dictionary \(\mathbf{V}\in\mathbb{C}^{M\times M^G}\) is defined as

\[\begin{equation}\label{eq:dictionary} \frac1{\sqrt{M}}\exp\left(-2\pi i\cdot d\cdot\mathbf{x}_M\mathbf{u}_{M^G}^\mathsf{H}\right), \end{equation}\]

where \(\mathbf{x}_M=[0,1,2,\cdots,M-1]^\mathsf{T}\), \(\mathbf{u}_{M^G}=[-1,-1+\frac2{M^G},-1+\frac4{M^G},\cdots,1-\frac2{M^G}]^\mathsf{T}\) and \(d\) is the antenna spacing which is assumed to be \(1/2\) in the current version.

For a uniform planar array (UPA) with size \(M=M_xM_y\), the dictionary is defined as

\[\begin{equation} \mathbf{V}_M=\mathbf{V}_{M_x}\otimes\mathbf{V}_{M_y}, \end{equation}\]

where \(\otimes\) denotes the Kronecker product, and \(\mathbf{V}_{M_x}\) and \(\mathbf{V}_{M_y}\) can both be calculated with \(\eqref{eq:dictionary}\).

ALG Implementation

The return value is the generated dictionary matrix which has type c2c (const complex matrix).

Position Meaning Descriptions
1 Mx ULA size or UPA \(x\) dimension size.
2 My \(1\) for ULA and \(y\) dimension size for UPA.
3 GMx ULA grid size or UPA \(x\) dimension grid size.
4 GMy \(1\) for ULA and \(y\) dimension grid size for UPA.

Example 

# UPA Antenna size: 16x6, Grid size: 16x16
D = \dictionary(16, 8, 16, 16)
# This creates a new instance of dictionary matrix
D::mc = NEW \dictionary(16, 8, 16, 16)
# Use macro to create a dictionary at the transmitter side
D::mc = NEW `DICTIONARY.T`

For simplicity, you may use macros to simplicity the \dictionary command. The `DICTIONARY.T` and `DICTIONARY.R` macros can be used to represent the dictionary at the transmitter side and receiver side without specifying the parameters as long as they are specified in the nodes section of .sim configuration.

Subscripts

Subscripts take the subview of vector/matrix/tensor. The syntax is _{<sub>} (a leading underscore _ as in LaTeX), where the brackets cannot be omitted even if <sub> contains only one character.

The subscript syntax imposes a requirement for variables: variables cannot be ended with character underscore (_).

Due to internal underscore is allowed for variable names, the subscript is only recognized when brackets {} exist.

Foo Subscripts

Well, some subscripts just do nothing, so they are removed. They are _{}, _{:}, _{:,:}, _{:,:,:}.

Valid Subscripts

The contents inside _{} of valid subscripts are similar to MATLAB syntax except for indices start from 0.

  • For a vector x, use x_{n} to access the n-th element, and x_{begin:end} to access a range of elements.
  • For a matrix A, use A_{i,j} to access an individual element, A_{i,:} to access an entire row, A_{:,j} to access an entire column, A_{i:j,l:m} to access a range of rows and columns, and A_{:,:,k} to access a slice of the matrix.
  • For a tensor Z, use Z_{i,j,k} to access an individual element, Z_{:,:,k} to access a slice of the tensor, and Z_{:,:,indices} to access multiple slices where indices is of type u1. Accessing indices vector of type u1 for a tensor is only supported for the last dimension.

Here are some examples.

# x is a vector (dim = 1)
# A is a matrix (dim = 2)
# Z is a tensor (dim = 3)
x_{2} # [scalar] the 2-nd element of vector
x_{1:4} # [vector] elements 1,2,3,4 of vectors
x_{index} # [scalar] (index of type u0) the index-element of vector
x_{indices} # [vector] (indices of type u1) elements of indices in vector
A_{3,2} # [scalar] the element at position (3,2)
A_{2,index} # [scalar] (index of type u0)
A_{2,:} # [rowvec] the 2-nd row
A_{:,3} # [vector] the 3-nd column
A_{1,3:5} # [vector] elements (1,3),(1,4),(1,5)
A_{2:4,indices} # [matrix] (indices of type u1)
A_{15} # [scalar] the 15-th element in the flattened matrix as vector
A^T_{1,2} # [scalar] element (1,2) of A^T, i.e. element (2,1) of A
A_{1:3,:}^H # [scalar] the conjugate transpose of sub matrix (Mind the sequence!)
Z_{0,0,0} # [scalar] element (0,0,0) of tensor
Z_{:,:,2} # [matrix] the 2-nd slice of tensor
Z_{:,:,indices} # [tensor] (indices of type u1) slices of tensor

Using indices vector of type u1 for a tensor is only supported for the last dimension (i.e. the slice).

Superscripts

Supper scripts are led by caret (^) as in LaTeX.

Transpose and Conjugate Transpose

Real Matrices

The transpose for a real matrix is ^t or ^{t}.

Complex Matrices

The transpose for a complex matrix is ^T or ^{T}, and the conjugate transpose for a complex matrix is ^H or ^{H}.

There can be compiling error if ^T and ^t are misused!

Conjugate

The conjugate of a complex number/vector/matrix/tensor is ^*, ^{*}, ^\star, ^{\star}, ^\ast or ^{\ast}. (Wow, so LaTeX!!!)

You should not calculate the conjugate for a real number/vector/matrix/tensor.

Inverse

The inverse of a square matrix is ^{-1}, ^i or ^I.

For a non-square matrix, you may use \pinv (pseudo-inverse) command.