# Determine Fixed-Point Types for Complex Least-Squares Matrix Solve AX=B

This example shows how to use the `fixed.complexQRMatrixSolveFixedpointTypes` function to analytically determine fixed-point types for the solution of the complex least-squares matrix equation $AX=B$, where $A$ is an $m$-by-$n$ matrix with $m\ge n$, $B$ is $m$-by-$p$, and $X$ is $n$-by-$p$.

Fixed-point types for the solution of the matrix equation $AX=B$ are well-bounded if the number of rows, $m$, of $A$ are much greater than the number of columns, $n$ (i.e. $m\gg n$), and $A$ is full rank. If $A$ is not inherently full rank, then it can be made so by adding random noise. Random noise naturally occurs in physical systems, such as thermal noise in radar or communications systems. If $m=n$, then the dynamic range of the system can be unbounded, for example in the scalar equation $x=a/b$ and $a,b\in \left[-1,1\right]$, then $x$ can be arbitrarily large if $b$ is close to $0$.

### Define System Parameters

Define the matrix attributes and system parameters for this example.

`m` is the number of rows in matrices `A` and `B`. In a problem such as beamforming or direction finding, `m` corresponds to the number of samples that are integrated over.

`m = 300;`

`n` is the number of columns in matrix `A` and rows in matrix `X`. In a least-squares problem, `m` is greater than `n`, and usually `m` is much larger than `n`. In a problem such as beamforming or direction finding, `n` corresponds to the number of sensors.

`n = 10;`

`p` is the number of columns in matrices `B` and `X`. It corresponds to simultaneously solving a system with `p` right-hand sides.

`p = 1;`

In this example, set the rank of matrix `A` to be less than the number of columns. In a problem such as beamforming or direction finding, $\text{rank}\left(A\right)$ corresponds to the number of signals impinging on the sensor array.

`rankA = 3;`

`precisionBits` defines the number of bits of precision required for the matrix solve. Set this value according to system requirements.

`precisionBits = 24;`

In this example, complex-valued matrices `A` and `B` are constructed such that the magnitude of the real and imaginary parts of their elements is less than or equal to one, so the maximum possible absolute value of any element is $|1+1i|=\sqrt{2}$. Your own system requirements will define what those values are. If you don't know what they are, and `A` and `B` are fixed-point inputs to the system, then you can use the `upperbound` function to determine the upper bounds of the fixed-point types of `A` and `B`.

`max_abs_A` is an upper bound on the maximum magnitude element of A.

`max_abs_A = sqrt(2); `

`max_abs_B` is an upper bound on the maximum magnitude element of B.

`max_abs_B = sqrt(2);`

Thermal noise standard deviation is the square root of thermal noise power, which is a system parameter. A well-designed system has the quantization level lower than the thermal noise. Here, set `thermalNoiseStandardDeviation` to the equivalent of $-50$dB noise power.

`thermalNoiseStandardDeviation = sqrt(10^(-50/10))`
```thermalNoiseStandardDeviation = 0.0032 ```

The quantization noise standard deviation is a function of the required number of bits of precision. Use `fixed.complexQuantizationNoiseStandardDeviation` to compute this. See that it is less than `thermalNoiseStandardDeviation`.

`quantizationNoiseStandardDeviation = fixed.complexQuantizationNoiseStandardDeviation(precisionBits)`
```quantizationNoiseStandardDeviation = 2.4333e-08 ```

### Compute Fixed-Point Types

In this example, assume that the designed system matrix $A$ does not have full rank (there are fewer signals of interest than number of columns of matrix $A$), and the measured system matrix $A$ has additive thermal noise that is larger than the quantization noise. The additive noise makes the measured matrix $A$ have full rank.

Set .

`noiseStandardDeviation = thermalNoiseStandardDeviation;`

Use `fixed.complexQRMatrixSolveFixedpointTypes` to compute fixed-point types.

```T = fixed.complexQRMatrixSolveFixedpointTypes(m,n,max_abs_A,max_abs_B,... precisionBits,noiseStandardDeviation)```
```T = struct with fields: A: [0x0 embedded.fi] B: [0x0 embedded.fi] X: [0x0 embedded.fi] ```

`T.A` is the type computed for transforming $\mathit{A}$ to $R={Q}^{\prime }A$ in-place so that it does not overflow.

`T.A`
```ans = [] DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 24 ```

`T.B` is the type computed for transforming $\mathit{B}$ to $C={Q}^{\prime }B$ in-place so that it does not overflow.

`T.B`
```ans = [] DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 32 FractionLength: 24 ```

`T.X` is the type computed for the solution $\mathit{X}=\mathit{A}\\mathit{B}\text{\hspace{0.17em}}$so that there is a low probability that it overflows.

`T.X`
```ans = [] DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 37 FractionLength: 24 ```

### Use the Specified Types to Solve the Matrix Equation AX=B

Create random matrices `A` and `B` such that `B` is in the range of `A`, and `rankA=rank(A)`. Add random measurement noise to `A` which will make it become full rank, but it will also affect the solution so that `B` is only close to the range of `A`.

```rng('default'); [A,B] = fixed.example.complexRandomLeastSquaresMatrices(m,n,p,rankA); A = A + fixed.example.complexNormalRandomArray(0,noiseStandardDeviation,m,n);```

Cast the inputs to the types determined by `fixed.complexQRMatrixSolveFixedpointTypes`. Quantizing to fixed-point is equivalent to adding random noise.

```A = cast(A,'like',T.A); B = cast(B,'like',T.B);```

Accelerate the `fixed.qrMatrixSolve` function by using `fiaccel` to generate a MATLAB executable (MEX) function.

`fiaccel fixed.qrMatrixSolve -args {A,B,T.X} -o qrComplexMatrixSolve_mex`

Specify the output type `T.X` and compute fixed-point $X=A\B$ using the QR method.

`X = qrComplexMatrixSolve_mex(A,B,T.X);`

Compute the relative error to verify the accuracy of the output.

`relative_error = norm(double(A*X - B))/norm(double(B))`
```relative_error = 0.0056 ```

Suppress `mlint` warnings in this file.

```%#ok<*NASGU> %#ok<*ASGLU>```