Documentation

# dsp.UpperTriangularSolver

Solve upper-triangular matrix equation

## Description

The `UpperTriangularSolver` object solves UX = B for X when U is a square, upper-triangular matrix with the same number of rows as B.

To solve UX = B:

1. Create the `dsp.UpperTriangularSolver` object and set its properties.

2. Call the object with arguments, as if it were a function.

## Creation

### Syntax

``uptriang = dsp.UpperTriangularSolver``
``uptriang = dsp.UpperTriangularSolver(Name,Value)``

### Description

example

````uptriang = dsp.UpperTriangularSolver` returns a linear system solver, `uptriang`, used to solve UX = B where U is an upper (or unit-upper) triangular matrix.```
````uptriang = dsp.UpperTriangularSolver(Name,Value)` returns a linear system solver, `uptriang`, with each specified property set to the specified value. Enclose each property name in single quotes. Unspecified properties have default values.```

## Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the `release` function unlocks them.

If a property is tunable, you can change its value at any time.

When you set this property to `true`, the linear system solver replaces the elements on the diagonal of the input, U, with ones. This property is useful when matrix U is the result of another operation, such as an LDL decomposition, that uses the diagonal elements to represent the D matrix.

When you set this property to `true`, the linear system solver optimizes computation speed if the input U is complex, but its diagonal elements are real. Set this property to either `true` or `false`.

#### Dependencies

This property applies only when you set the `OverwriteDiagonal` property to `false`.

### Fixed-Point Properties

Specify the rounding method as `Ceiling`, `Convergent`, `Floor`, `Nearest`, `Round`, `Simplest`, or `Zero`.

Specify the overflow action as `Wrap` or `Saturate`.

Specify the product data type as `Full precision`, ```Same as input```, or `Custom`.

Specify the product fixed-point type as a scaled `numerictype` object with a `Signedness` of `Auto`.

#### Dependencies

This property applies only when you set the `ProductDataType` property to `Custom`.

Specify the accumulator data type as `Full precision`, `Same as first input`, `Same as product`, or `Custom`.

Specify the accumulator fixed-point type as a scaled `numerictype` object with a `Signedness` of `Auto`.

#### Dependencies

This property applies only when you set the `AccumulatorDataType` property to `Custom`.

Specify the output data type as `Same as first input` or `Custom`.

Specify the output fixed-point type as a scaled `numerictype` object with a `Signedness` of `Auto`.

#### Dependencies

This property applies only when you set the OutputDataType property to `Custom`.

## Usage

### Syntax

``X = uptriang(U,B)``

### Description

example

````X = uptriang(U,B)` computes the solution, `X`, of the matrix equation UX = B, where `U` is a square, upper-triangular matrix with the same number of rows as the matrix `B`.```

### Input Arguments

expand all

Upper-triangular square matrix of size M-by-M.

If the matrix is of fixed-point data type, it must be signed fixed point.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `fi`

Input B in the equation UX = B, where `B` is an M-by-N matrix.

If the matrix is of fixed-point data type, it must be signed fixed point.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `fi`

### Output Arguments

expand all

Solution of the UX = B equation, returned as an M-by-N output matrix. The object uses only the elements in the upper triangle of input U and ignores the lower elements. When you set `OverwriteDiagonal` to `true`, the object replaces the elements on the diagonal of the input, U, with ones.

If the matrix is of fixed-point data type, it must be signed fixed point.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `fi`

## Object Functions

To use an object function, specify the System object™ as the first input argument. For example, to release system resources of a System object named `obj`, use this syntax:

`release(obj)`

expand all

 `step` Run System object algorithm `release` Release resources and allow changes to System object property values and input characteristics `reset` Reset internal states of System object

## Examples

expand all

Note: If you are using R2016a or an earlier release, replace each call to the object with the equivalent step syntax. For example, `obj(x)` becomes `step(obj,x)`.

```uptriang = dsp.UpperTriangularSolver; u = triu(rand(4, 4)); b = rand(4, 1);```

Check that result is the solution to the linear equations.

`x1 = u\b`
```x1 = 4×1 -179.1887 265.6759 -29.3098 6.7624 ```
`x = uptriang(u, b)`
```x = 4×1 -179.1887 265.6759 -29.3098 6.7624 ```

## Algorithms

This object implements the algorithm, inputs, and outputs described on the Backward Substitution block reference page. The object properties correspond to the block parameters.