dsp.LowerTriangularSolver

Solve lower-triangular matrix equation

Description

The LowerTriangularSolver object solves LX = B for X when L is a square, lower-triangular matrix with the same number of rows as B.

To solve LX = B for X:

1. Create the dsp.LowerTriangularSolver object and set its properties.

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

To learn more about how System objects work, see What Are System Objects? (MATLAB).

Creation

Syntax

lowtriang = dsp.LowerTriangularSolver

lowtriang = dsp.LowerTriangularSolver(Name,Value)

Description

lowtriang = dsp.LowerTriangularSolver returns a linear system solver, lowtriang, used to solve the linear system LX = B, where L is a lower (or unit-lower) triangular matrix.

lowtriang = dsp.LowerTriangularSolver(Name,Value) returns a linear system solver, lowtriang, with each specified property set to the specified value.

Properties

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.

For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).

OverwriteDiagonal — Replace diagonal elements of input with ones

false (default) | true

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

RealDiagonalElements — Indicate that diagonal of complex input is real

false (default) | true

When you set this property to true, the linear system solver optimizes computation speed if the input L 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

RoundingMethod — Rounding method for fixed-point operations

Floor (default) | Ceiling | Convergent | Nearest | Round | Simplest | Zero

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

OverflowAction — Overflow action for fixed-point operations

Wrap (default) | Saturate

Specify the overflow action as Wrap or Saturate.

ProductDataType — Data type of product

Full precision (default) | Same as input | Custom

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

CustomProductDataType — Product word and fraction lengths

numerictype([],32,30) (default) | numerictype

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.

AccumulatorDataType — Data type of accumulator

Full precision (default) | Same as first input | Same as product | Custom

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

CustomAccumulatorDataType — Accumulator word and fraction lengths

numerictype([],32,30) (default) | numerictype

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.

OutputDataType — Data type of output

Same as first input (default) | Custom

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

CustomOutputDataType — Output word and fraction lengths

numerictype([],16,15) (default) | numerictype

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

For versions earlier than R2016b, use the step function to run the System object™ algorithm. The arguments to step are the object you created, followed by the arguments shown in this section.

For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

Syntax

X = lowtriang(L,B)

Description

X = lowtriang(L,B) computes the solution, X, of the matrix equation LX = B, where L is a square, lower-triangular matrix with the same number of rows as the matrix B.

Input Arguments

L — Lower-triangular matrix

matrix

Lower-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

B — Input B

vector | matrix

Input B in the equation LX = 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

X — Solution of the equation

vector | matrix

Solution of the LX = B equation, returned as an M-by-N output matrix. The object uses only the elements in the lower triangle of input L and ignores the upper elements. When you set OverwriteDiagonal to true, the object replaces the elements on the diagonal of the input, L, 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)

Common to All System Objects

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

Solve a Lower Triangular Matrix

Note: This example runs only in R2016b or later. If you are using an earlier release, replace each call to the function with the equivalent step syntax. For example, myObject(x) becomes step(myObject,x).

lowtriang = dsp.LowerTriangularSolver;
u = tril(rand(4, 4));
b = rand(4, 1);

Check that result is the solution to the linear equations.

x1 = u\b

x1 = 4×1

    0.5177
    4.5810
   -3.4853
    9.6147

x = lowtriang(u, b)

x = 4×1

    0.5177
    4.5810
   -3.4853
    9.6147

Algorithms

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

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).