Mathworks FIXED-POINT TOOLBOX 3 Reference

Download

Fixed-Point Toolb

Reference

ox™ 3

How to Contact The MathWorks

www.mathworks. comp.soft-sys.matlab Newsgroup www.mathworks.com/contact_TS.html T echnical Support

suggest@mathworks.com Product enhancement suggestions

bugs@mathwo doc@mathworks.com Documentation error reports service@mathworks.com Order status, license renewals, passcodes

info@mathwo

com

rks.com

Web

Bug reports

Sales, prici

ng, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

Fixed-Point Toolbox™ Reference

The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathW orks, Inc.

FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern theuse,modification,reproduction,release,performance,display,anddisclosureoftheProgramand Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government’s needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Docu mentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See

www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand

names may be trademarks or registered trademarks of their respective holders.

Patents

The MathWorks products are protected by one or more U.S. patents. Please see

www.mathworks.com/patents for more information.

Revision History

June 2004 First printing New for Version 1.0 (Release 14) October 2004 Online only Version 1.1 (Release 14SP1) March 2005 Online only Version 1.2 (Release 14SP2) September 2005 Online only Version 1.3 (Release 14SP3) October 2005 Second printing Version 1.3 March 2006 Online only Version 1.4 (R2006a) September 2006 Online only Version 1.5 (R2006b) March 2007 Online only Version 2.0 (R2007a) September 2007 Online only Revised for Version 2.1 (R2007b) March 2008 Online only Revised for Version 2.2 (R2008a) October 2008 Online only Revised for Version 2.3 (R2008b) March 2009 Online only Revised for Version 2.4 (R2009a) September 2009 Online only Revised for Version 3.0 (R2009b) March 2010 Online only Revised for Version 3.1 (R2010a)

Property Reference

fi Object Properties ................................ 1-2

bin

............................................. 1-2

data dec double fimath hex int NumericType oct

............................................ 1-2

............................................. 1-2

........................................... 1-2

............................................. 1-3

.............................................. 1-3

..................................... 1-3

.............................................. 1-3

Contents

fimath Object Properties

CastBeforeSum MaxProductWordLength MaxSumWordLength OverflowMode ProductBias ProductFixedExponent ProductFractionLength ProductMode ProductSlope ProductSlopeAdjustmentFactor ProductWordLength RoundMode SumBias SumFixedExponent SumFractionLength SumMode SumSlope SumSlopeAdjustmentFactor SumWordLength

fipref Object Properties

DataTypeOverride FimathDisplay

......................................... 1-8

................................... 1-4

.............................. 1-4

.................................... 1-4

...................................... 1-5

..................................... 1-5

..................................... 1-7

............................... 1-7

...................................... 1-8

................................ 1-8

............................... 1-9

........................................ 1-9

........................................ 1-11

.................................. 1-11

................................. 1-12

.................................... 1-12

........................... 1-4

............................. 1-5

...................... 1-7

......................... 1-11

............................ 1-12

LoggingMode ..................................... 1-12

NumericTypeDisplay NumberDisplay

.............................. 1-13

................................... 1-13

numerictype Object Properties

Bias DataType DataTypeMode FixedExponent FractionLength Scaling Signed Signedness Slope SlopeAdjustmentFactor WordLength

quantizer Object Properties

DataMode Format OverflowMode RoundMode

............................................ 1-15

........................................ 1-15

................................... 1-15

................................... 1-16

................................... 1-17

.......................................... 1-17

....................................... 1-18

............................................ 1-18

...................................... 1-19

....................................... 1-20

.......................................... 1-20

.................................... 1-21

...................................... 1-22

..................... 1-15

............................ 1-18

........................ 1-20

Function Reference

vi Contents

Bitwise Operations ................................ 2-2

Constructors and Properties

Data Manipulation

Data Type Operations

Data Type Tools

Data Quantizing

................................. 2-4

.............................. 2-7

................................... 2-8

........................ 2-3

Element-Wise Logical Operators .................... 2-8

Math Operations

Matrix Manipulation

Plots

Radix Conversion

Relational Operators

Statistics

Subscripted Assignment and Reference

fi Object Operations

fimath Object Operations

fipref Object Operations

.............................................. 2-13

.......................................... 2-17

.................................. 2-9

............................... 2-11

.................................. 2-16

............................... 2-17

............................... 2-19

........................... 2-31

........................... 2-32

.............. 2-18

numerictype Object Operations

quantizer Object Operations

........................ 2-34

..................... 2-33

vii

Functions — Alphabetical List

Glossary

Index

viii Contents

Property Reference

• “fi Object Properties” on page 1-2

• “fimath Object Properties” on page 1-4

• “fipref Object Properties” on page 1-12

• “numerictype Object Properties” on page 1-15

• “quantizer Object Properties” on page 1-20

1 Property Reference

fi Object Properties

The properties associated with fi objects are described in the following sections in alphabetical order.

Note The fimath properties and numerictype properties are also properties of the “numerictype Object Properties” o n page 1-15 for more information.

bin

Stored integer value of a fi object in binary.

data

Numerical real-world value of a fi object.

fi object. Re fer to “fimath Object Properties” on page 1-4 and

1-2

dec

Stored integer value of a fi object in decimal.

double

Real-world value of a fi obje ct stored as a MATLAB

double.

fimath

fimath properties associated with a fi object. fimath properties determine

the rules for performing fixed-point arithmetic operations on objects can get their fimath properties from a local fimath object or the global fimath. The factory-default configuration of the global fimath has the following settings:

RoundMode: nearest

OverflowMode: saturate

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

fi objects. fi

fi Object Properties

MaxSumWordLength: 128

To learn more about fimath objects and the global fimath, refer to “Working with fimath Objects”. For more information about each of the properties, refer to “fimath Object Properties” on page 1-4.

fimath object

hex

Stored integer value of a fi object in hexadecimal.

int

Stored integ er value of a fi object, store d in a built-in MATLAB integer data type. You can also use and

uint64 to get the stored integ er value of a fi object in these formats.

int8, int16, int32, int64, uint8, uint16, uint32,

NumericType

The numerictype object contains all the data type and scaling attributes of a fixed-point object. The structure, except that it only lets you set valid values for defined fields. For a table of the possible settings of each field of the structure, see “Valid Values for numerictype Structure Properties” in the Fixed-Point Toolbox™ User’s Guide.

numerictype object behaves like any MATLAB

Note You cannot change the numerictype properties of a fi object after

fi object creation.

oct

Stored integer value of a fi object in octal.

1-3

1 Property Reference

fimath Object Properties

The properties associated with fimath objects are described in the following sections in alphabetical order.

CastBeforeSum

Whether both operands are cast to the sum data type before addition. Possible values of this property are

1 (cast before sum) and 0 (do not cast before sum).

The MATLAB factory default value of this property is

This property is hidden when the

SumMode is set to FullPrecision.

1 (true).

MaxProductWordLength

Maximum allowable word length for the product data type.

The MATLAB factory default value of this property is

128.

MaxSumWordLength

Maximum allowable word length for the sum data type.

The MATLAB factory default value of this property is

128.

OverflowMode

Overflow-handling mode. The value of the OverflowMode property can be one of the following strings:

•

saturate — Saturate to maximum or minimum value of the fixed-point

range on overflow.

•

wrap — Wrap on overflow. This mode is also known as two’s complement

overflow.

1-4

The MATLAB factory default value of this property is

saturate.

ProductBias

Bias of the produ The product data of two

fi object

fimath Object Properties

ct data type. This value can be any floating-point number.

type defines the data type of the result of a multiplication

The MATLAB fac

ProductFixe

Fixed expone negative int of a multipl

ProductSlope ProductSlopeAdjustmentFactor

tory default value of this property is

dExponent

nt of the product data type. This value can be any positive or

eger. The product data type defines the da t a type of the result

ication of two

=×2

fi objects.

ProductFixedExp

oonent

Changing one of these properties changes the others.

The

ProductFixedExponent is the negative of the ProductFractionLength.

Changing one property changes the other.

The MATLAB factory default value of this property is

-30.

ProductFractionLength

Fraction length, in bits, of the product data type. This value can be any positive or negative integer. The product data type defines the data type of the result of a multiplication of two

The

ProductFractionLength is the negative of the ProductFixedExponent.

Changing one property changes the other.

fi objects.

The MATLAB factory default value of this property is

30.

ProductMode

Defines how the product data type is determined. In the fo llowing descriptions, let A and B be real operands, with [word length, fraction length] pairs [W length and F

]and[WbFb], respectively. Wpis the product data type w ord

aFa

is the product data type fraction le ngth.

1-5

1 Property Reference

• FullPrecision — The full precision of the result is kept. An

error is generated if the calculated word lengt h is greater than

MaxProductWordLength.

WWW

pab

FFF

pab

• KeepLSB — Keep least significant bits. You specify the product data type

word length, while the fraction length is s et to maintain the least significant bits of the product. In this mode, full precision is kept, but overflow is possible. This behavior models the C language integer operations.

specified in the propertyProductWordLength

FFF

pab

• KeepMSB — Keep most significant bits. You specify the product data

type word length, while the fraction length is set to maintain the most significant bits of the product. In this mode, overflow is prevented, but precision may be lost.

1-6

specified in the property

=−

intege

ProductWordLength

rr length

where

integer length =+−−()()WW FF

ab ab

• SpecifyPrecision — You specify both the word length and fraction length

of the product data type.

==specified in the property

specified

in the propertyProductFractionLength

ProductWordLength

For [Slope Bias] math, you specify both the slope and bias of the product data type.

==specified in the property

specified in t

ProductSlope

hhe propertyProductBias

fimath Object Properties

[Slope Bias] math is only defined for products when ProductMode is set to

SpecifyPrecision.

The M A TLAB factory default value of this property is

FullPrecision.

ProductSlope

Slope of the product data type. This value can be any floating-point number. The product data type d efines the data type of the result of a multiplication of two

fi objects.

ProductSlope ProductSlopeAdjustmentFactor

=×2

ProductFixedExp

oonent

Changing one of these properties changes the others.

The MATLAB factory default value of this property is

9.3132e-010.

ProductSlopeAdjustmentFactor

Slope adjustment factor of the product data type. This value can be any floating-point number greater than or equal to 1 and less than 2. The product data type defines the data type of the result of a multiplication of two objects.

ProductSlope ProductSlopeAdjustmentFactor

=×2

ProductFixedExp

Changing one of these properties changes the others.

oonent

The MATLAB factory default value of this property is

ProductWordLength

Word length, in bits, of the product data type. This value must be a positive integer. The product data type defines the data type of the result of a multiplication of two

The MATLAB factory default value of this property is

fi objects.

32.

1-7

1 Property Reference

RoundMode

The rounding mod following strin

gs:

e. The value of the

RoundMode property can be one of the

•

ceil — Round tow

•

convergent —R

stored intege Fixed-Point T

•

fix —Roundto

•

floor —Roun

•

nearest —Ro

•

round —Roun

negative n

The MATLAB

See “Roun informat

umbers, and toward positive infinity for positive numbers.

ding Methods” in the Fixed-Point Toolbox User’s Guide for more

ion.

SumBias

The bia The sum object

The MA

s of the sum data type. This value can be any floating-point number.

data type defines the data typeoftheresultofasumoftwo

TLAB factory default value of this property is

ard positive infinity.

ound toward nearest. Ties round to the nearest even

r. This is the least biased rounding method provided by

oolbox software.

ward zero.

d toward n egative infinity.

und toward nearest. Ties round toward positive infinity.

d toward nearest. Ties round toward negativ e infinity for

factory d efault value of this property is

nearest.

1-8

SumF

The f nega sum o

SumSlope SumSlopeAdjustmentFactor

of these properties changes the others.

ixedExponent

ixed exponent of the sum data type. This value can be any positive or

tive integer. The sum data type defines the data type of the result of a

ftwo

fi objects

= × 2

SumFixedExponent

. C hanging one

fimath Object Properties

The SumFixedExponent is the negative of the SumFractionLength. Changing one property changes the other.

The MATLAB factory default value of this property is

-30.

SumFractionLength

The fraction length, in bi ts, of the sum data type. This value can be any positive or negative integer. The sum data type defines the data type of the result of a sum of two

The

SumFractionLength isthenegativeoftheSumFixedExponent. Changing

one property changes the other.

The MATLAB factory default value of this property is

fi objects.

30 .

SumMode

Defines how the sum data type is determined. In the following descriptions, let A and B be real operands, with [word length, fraction length] pairs [W

Fa]and[WbFb], respectively. Wsis the sum data type word length and Fsis

the sum data type fraction length.

Note In the case where there are two operands, as in A + B, NumberOfSummands is

sum(A) where A is a matrix, the NumberOfSummands is size(A,1).In sum(A) where A is a vector, the NumberOfSummands is length(A).

2,andceil(log2(NumberOfSummands)) = 1.In

• FullPrecision — The full precision of the res ul t is kept. An error is

generated if the calculated word length is greater than

=+integer length

where

integer length =−−

max , ceil logW F W F NumberOfSummands

()

aabb

(()

MaxSumWordLength.

()

1-9

1 Property Reference

FFF

= max( , )

sab

• KeepLSB — Keep least sign if ica n t bits. You specify the sum data type w ord

length, while the fraction length is set to maintain the least significant bits of the sum. In this mode, full precision is kept, but overflow is possible. This behavior models the C language integer operations.

==specified in the property SumWordLength

FFF

max( , )

sab

• KeepMSB — Keep most significant bits. You specify the sum data type word

length, while the fraction length is set to maintain the most significant bits of the sum and no more fractional bits than necessary. In this mode, overflow is prevented, but precision may be lost.

specified in the property

=−

integer le

SumWordLength

nngth

where

1-10

integer length =−−

max , ceil logW F W F NumberOfSummands

()

aabb

()

(()

• SpecifyPrecision — You specify both the word length and fraction length

of the sum data type.

==specified in the property

specified in

SumWordLength

tthe propertySumFractionLength

For [Slope Bias] m ath, you specify both the slope and bias of the sum data type.

==specified in the property

specified in the

SumSlope

SuumBias property

[Slope Bias] math is only defined for sums when SumMode is set to

SpecifyPrecision.

The M A TLAB factory default value of this property is

FullPrecision.

SumSlope

The slope of the s The sum data type objects.

fimath Object Properties

um data type. This value can be any floating-point number.

defines the data type of theresultofasumoftwo

SumSlope SumSlopeAdjustmentFactor

of these properties changes the others.

The MATLAB factory default value of this property is

= × 2

SumFixedExponent

9.3132e-010.

. C hanging one

SumSlopeAdjustmentFactor

The slope adjustment factor of the sum data type. This value can be any floating-point number greater than or equal to 1 and less than 2. The sum data type defines the data type of the result of a sum of two

SumSlope SumSlopeAdjustmentFactor

of these properties changes the others.

The MATLAB factory default value of this property is

= × 2

SumFixedExponent

fi obje cts.

. C hanging one

SumWordLength

The word length, in bits, of the sum data type. This value must be a positive integer. The sum data type defines the data type of the result of a sum of two

fi objects.

The MATLAB factory default value of this property is

32.

1-11

1 Property Reference

fipref Object Properties

The properties associated with fipref objects are described in the following sections in alphabetical order.

DataTypeOverride

Data type override options for fi objects

•

ForceOff —Nodatatypeoverride

ScaledDoubles — Override with scaled doubles

•

TrueDoubles — Override with doubles

•

TrueSingles — Override with singles

•

Data type override only occurs when the

The default value of this property is

fi constructor function is called.

ForceOff.

FimathDisplay

Display options for the fimath attributes of a fi object

•

full —Displaysallofthefimath attributes of a fixed-point object

none —Noneofthefimath attributes are displayed

•

The default value of this property is

full.

LoggingMode

Logging options for operations p erforme d on fi objects

•

off —Nologging

on — Information is logged for future operations

•

Overflows a nd underflows for assignment, plus, m inus, and multiplication operations are logged as warnings when

LoggingMode is set to on.

1-12

fipref Object Properties

When LoggingMode is on, you can also use the following functions to return logged information about assignment and creation operations to the MATLAB command line:

•

maxlog — Returns the maximum real-world value

minlog — Returns the minimum value

•

noverflows — Returns the number of overflows

•

nunderflows — Retur ns the number of underflows

•

LoggingMode must be set to on before you p erform any operation in order to

log information about it. To clear the log, use the function

resetlog.

The default value of this property of

off.

NumericTypeDisplay

Display options for the numerictype attributes of a fi object

•

full — Displays all the numerictype attributes of a fixed-point object

none —Noneofthenumerictype attributes are displayed.

•

short — Displays an abbreviated notation of the fixed-point data type and

•

scaling of a fixed-point object in the format

xWL,FL where

- x is s for signed and u for unsigned.

- WL is the word leng th.

- FL is the fraction length.

The default value of this property is

NumberDisplay

Display options for the value of a fi object

•

bin — Displays the stored integer value in binary format

dec —Displaysthestoredintegervalue in unsigned decimal format

•

full.

1-13

1 Property Reference

• RealWorldValue — Displays the stored integer value in the format

specified by the MATLAB

hex — Displays the stored integer value in hexadecimal format

•

int — Displays the stored integer value in signed decimal fo rmat

•

none — No value is displayed.

•

format function

The default value of this property is of a

fi object is displayed in the format specified by the MATLAB format

function: +, bank, compact, hex, long, long e, long g, loose, rat, short,

short e,orshort g. fi objects in rat format are displayed according to

fixed- point exponent

()

stored integer

RealWorldValue. In this mode, the value

1-14

numerictype Object Properties

This section describes the properties associated with numerictype objects.

Bias

The bias is part of the numerical representation used to interpret a fixed-point number. Along with the slope, the bias forms the scaling of the number. Fixed-point numbers can be represented as

real world value slope stored integer bias- =× +()

where the slope can be expressed as

numerictype Object Properties

slope fractional slope

=×2

fixed exponent

DataType

The poss

•

The de

Data

Dat pro

•

• do

ible value of the

boolean

double

Fixed —

Scaled

singl

—Built-inMATLABboolean data type

— Built-in MATLAB double data type

Fixed-point or in tege r data type

Double

— Built-in MATLAB single data type

fault value of this property is

— Scaled double data type

TypeMode

a type and scaling associated with the object. The possible values of this

perty are:

lean

boo

uble

—Built-inboolean

—Built-indouble

DataType property are:

Fixed.

1-15

1 Property Reference

• Fixed-point: binary point scaling — Fixed-point data type and

scaling defined by the word length and fraction length

•

Fixed-point: slope and bias scaling — Fixed-point data type and

scaling defined by the slope and bias

•

Fixed-point: unspecified scaling — Fixed-point data type with

unspecified scaling

•

Scaled double: binary point scaling — Double data type with

fixed-point word length and fraction length information retained

•

Scaled double: slope and bias scaling —Doubledatatypewith

fixed-point slope and bias information retained

•

Scaled double: unspecified scaling —Doubledatatypewith

unspecified fixed-point scaling

•

single —Built-insingle

ThedefaultvalueofthispropertyisFixed-point: binary point scaling.

1-16

FixedExponent

Fixed-point exponent associated with the object. The exponent is part of the numerical representation used to express a fixed-point number. Fixed-point numbers can be represented as

real world value slope stored integer bias- =× +()

where the slope can be expressed as

slope fractional slope

=×2

The exponent of a fixed-point number is equal to the negative of the fraction length:

fixed exponent fraction length=−

fixed exponent

FractionLength

Fraction length length can be any

of the stored integer value of the object, in bits. The fraction

integer value.

numerictype Object Properties

This property a the value of th

Scaling

Scaling mode

•

BinaryPoin

•

SlopeBias —

•

Unspecifi

creation, best-prec

The defau

to allow for the automatic assignment of a binary point

ision scaling.

lt value of this property is

Signed

Whether

•

1 —sign

•

0 — unsi

•

true —

theobjectissigned.Thepossiblevaluesofthispropertyare:

gned

signed

utomatically defaults to the best precision possible based on

e word length and the real-world value of the

fi object.

oftheobject. Thepossiblevaluesofthispropertyare:

— Scaling for the fi object is defined by the fraction length.

Scaling for the

fi object is defined by the slope and bias.

— A temporary setting that is only allowed at fi object

BinaryPoint.

•

false

The d

Note

pro cha pro pro

— unsigned

efault value of this property is

Although the

Signed property is still supported, the Signedness

perty always appears in the

nge or set the signedness of your

true.

numerictype object display. If you choose to

numerictype objects using the Signed

perty, MATLAB updates the corresponding value of the perty.

Signedness

1-17

1 Property Reference

Signedness

Whether the obje possible values

•

Signed —signed

ct is signed, unsigned, or has an unspecified sign. The

of this property are:

Unsigned — uns

•

Auto —unspeci

The default v

All

numeric

fi object

of creation, t

type

creation. If this property is set to

he property automatically defaults to

igned

fied sign

alue of this property is

object pro pe rties of a fi object must be specified at the time

Signed.

Auto atthetimeoffi object

Signed.

Slope

Slope ass represen the slope can be re

where the slope can be expressed as

ociated with the object. The slope is part of the numerical

tation used to express a fixed-point number. Along with the bias,

forms the scaling of a fixed-point number. Fixed-point numbers

presented as

real world value slope stored integer bias- =× +()

slope fractional slope

=×2

fixed exponent

1-18

SlopeAdjustmentFactor

Slope adjustment associated with the object. The slope adjustment is equivalent to the fractional slope of a fixed-point number. The fra ctional slope is part of the numerical representation used to express a fixed-point number. Fixed-point numbers can be represented as

real world value slope stored integer bias- =× +()

ere the slope can be expressed as

numerictype Object Properties

slope fractional slope

=×2

fixed exponent

WordLength

Word length of the stored intege r value of the object, in bits. The word length can be any positive integer value.

The default value of this property is

16.

1-19

1 Property Reference

quantizer Object Properties

The properties associated with quantizer objects are described in the following sections in alphabetical order.

DataMode

Type of arithmetic used in quantization. This property can have the following values:

•

fixed — S igned fixed-point calculations

float — User-specified floating-point calcul ati on s

•

double — Double-precision floating-point calculations

•

single — Single-pre c isi o n floating-point calculations

•

ufixed — Unsigned fixed-point calculations

•

Thedefaultvalueofthispropertyis

When you set the property value become s read only.

DataMode property value to double or single,theFormat

fixed.

Format

Data format of a quantizer object. The interpretation of this property value depends on the value of the

For example, whether you specify the floating-point arithmetic affects the interpretation of the data format property. For some

The following table shows you how to interpret the values for the property value when you specify it, or ho w it is specified in read-only cases.

DataMode property values, the data format property is read only.

DataMode property.

DataMode property with fixed- or

Format

1-20

DataMode Property Value Interpreting the Format Property Values

fixed or ufixed

You specify the Format property value as a vector. The number of bits for the vector, and the number of bits for the

quantizer object word length is the first entry of this

quantizer object fraction

length is the second entry.

The word length can range from 2 to the limits of memory on your PC. T he fraction length can range from 0 to one less than the word length.

float

You specify the Format property value as a vector. The number of bits you want for the

quantizer object word length is the first entry

of this vector, and the number of bits you want for the object exponent length is the second entry.

The word length can range from 2 to the limits of memory on your PC. The exponent length can range from 0 to 11.

double

The Format property value is specified automatically (is read only) when you set the

DataMode property to double.Thevalueis[6411],

specifying the word length and exponent length, respectively.

single

The Format property value is specified automatically (is read only) when you set the

DataMode property to single.Thevalueis[328],

specifying the word length and exponent length, respectively.

quantizer Object Properties

quantizer

OverflowMode

Overflow-handling mode. The value of the OverflowMode property can be one of the following strings:

•

saturate — Overflows saturate.

Whenthevaluesofdatatobequantizedlieoutsidetherangeofthelargest and smallest representable numbers (as specified by the data format properties), these values a re quantized to the v alue of either the largest or smallest representable value, depending on which is closest.

•

wrap — Overflows wrap to the range of representable values.

Whenthevaluesofdatatobequantizedlieoutsidetherangeofthelargest and smallest representable numbers (as specified by the data format

1-21

1 Property Reference

properties), these values are wrapped back into that range using modular arithmetic relative to the smallest representable number.

The default value of this property is

saturate.

Note Floating-point numbers that extend beyond the dynamic range overflow to ±

inf.

The OverflowMode property value is set to saturate and becomes a read-only property w h en you set the value of the or

single.

DataMode property to float, double,

RoundMode

Rounding mode. The value of the RoundMode property can be one of the following strings:

•

ceil — Round up to the next allowable quantized value.

convergent — Round to the nearest allowable quantized value. Numbers

•

that are exactly halfway between the two nearest allowable quantized values are rounded up onl y if the least significant bit (af t er rounding) would be set to 0.

•

fix — Round negative numbers up and positive numbers down to the next

allowable quantized value.

1-22

•

floor — Round down to the next allowable quantized value.

nearest — Round to the nearest allowable quantized value. Numbers

•

that are halfway between the two nearest allowable quantized values are rounded up.

Thedefaultvalueofthispropertyis

floor.

Function Reference

Bitwise Operations (p. 2-2) Operate on and manipulate bits

Constructors and Properties (p. 2-3) Create and manipulate objects and

properties

Data Manipulation (p. 2 -4) Manipulate and get information

about objects

Data Type Operations (p. 2-7) Convert objects or values to different

data types

Data Type Tools (p. 2-8) Analyze dynamic range of variables

to determine data types

Data Quantizing (p. 2-8) Quantize data

Element-Wise Logical Operators (p. 2-8)

Math Operations (p. 2-9) Operate on o bjects

Matrix Manipulation (p. 2-11) Manipulate and get information

Plots (p. 2-13) Create plots

Radix Conversion (p. 2-16)

Relational Operators (p. 2-17) Compare real-world values of objects

Statistics (p. 2-17) Get statistical information about

Subscripted Assignm e n t and Reference (p. 2-18)

Get information about array elements

about arrays

Binary point representations and conversions

objects

Getandsetarrayelements

2 Function Reference

fi Object Operations (p. 2-19) All functions that operate directly on

fi objects

fimath Object Operations (p. 2-31) All functions that operate directly on

fimath objects

fipref Object Operations (p. 2-32) All functions that operate directly on

fipref objects

numerictype Object Operations (p. 2-33)

quantizer Object Operations (p. 2-34) All functions that operate directly on

Bitwise Operations

bitand

bitandreduce

bitcmp

bitconcat

bitget

bitor

bitorreduce

bitreplicate

bitrol

bitror

bitset

bitshift

bitsliceget

All functions that operate directly on

numerictype objects

quantizer objects

Bitwise AND of two fi objects

Bitwise AND of consecutive range of bits

Bitwise complement of fi object

Concatenate bits of fi objects

Bitatcertainposition

Bitwise OR of two fi objects

Bitwise OR of consecutive range of bits

Replicate and concatenate bits of fi object

Bitwiserotateleft

Bitwiserotateright

Set bit at certain position

Shift bits specified number of places

Consecutive slice of bits

2-2

Constructors and Properties

bitsll

bitsra

bitsrl

bitxor

bitxorreduce

getlsb

getmsb

Constructors and Properties

assignmentquantizer

copyobj

fimath

fipref

get

globalfimath

numerictype

quantizer

removedefaultfimathpref

removeglobalfimathpref

reset

resetdefaultfimath

Bit shift left logical

Bit shift right arithmetic

Bitshiftrightlogical

Bitwise exclusive OR of two fi objects

Bitwise exclusive OR of consecutive range of b its

Least significant bit

Most significant bit

Assignment quantizer object of fi object

Make independent c o py of quantizer object

Construct fixed-point numeric object

Construct fimath object

Construct fipref object

Property values of object

Configure global fimath and return handle object

Construct numerictype object

Construct quantizer object

Remove global fimath preference

Reset objects to initial conditions

Set global fimath to MATLAB factory default

2-3

2 Function Reference

resetglobalfimath

savedefaultfimathpref

savefipref

saveglobalfimathpref

set

setdefaultfimath

sfi

tostring

ufi

unitquantizer

Set global fimath to MATLAB factory default

Save global fimath for next MATLAB session

Save fi preferences for next MATLAB session

Save global fimath for next MATLAB session

Set or display property values for

quantizer objects

Set MATLAB global fimath

Construct signed fixed-point numeric object

Convert numerictype or quantizer object to string

Construct unsigned fixed-point numeric object

Constructor for unitquantizer object

Data Manipulation

2-4

denormalmax

denormalmin

eps

exponentbias

exponentlength

Largest denormalized quantized number for

quantizer object

Smallest denormalized quantized number for

quantizer object

Quantized relative accuracy for fi or quantizer objects

Exponent bias for quantizer object

Exponent length of quantizer object

Data Manipulation

exponentmax

exponentmin

fractionlength

intmax

intmin

isboolean

isdouble

isequal

isfi

isfimath

isfimathlocal

isfipref

isfixed

isfloat

isnumerictype

Maximum exponent for quantizer object

Minimum exponent for quantizer object

Fraction length of quantizer object

Largest positiv e stored intege r value representable by

numerictype of fi

object

Smallest stored integer value representable by

numerictype of fi

object

Determine whether input is Boolean

Determine whether input is double-precision data type

Determine whether real-world values of two

fi objects are equal, or

determine whether properties of two

fimath, numerictype,orquantizer

objects are equal

Determine whether variable is fi object

Determine whether variable is

fimath object

Determine whether fi object has local fimath

Determine whether input is fipref object

Determine whether input is fixed-point data type

Determine whether input is floating-point data type

Determine whether input is

numerictype object

2-5

2 Function Reference

ispropequal

isquantizer

isscaleddouble

isscaledtype

issigned

issingle

isslopebiasscaled

lowerbound

lsb

range

realmax

realmin

sort

upperbound

wordlength

Determine whether properties of two

fi objects are equal

Determine whether input is

quantizer object

Determine whether input is scaled double data type

Determine whether input is fixed-point or scaled double data type

Determine whether fi object is signed

Determine whether input is single-precision data type

Determine whether numerictype object has nontrivial slope and bias

Lower bound of range of fi object

Scaling of least significant bit of fi object, or value of least significant bit of

quantizer object

Numerical range of fi or quantizer object

Largest positiv e fixed-point value or quantized number

Smallest positive normalized fixed-point value or quan tized number

Sort elements of real-v alued fi object in ascending or descending order

Upper bound of range of fi object

Word length of quantizer object

2-6

Data Type Operations

double

int

int16

int32

int64

int8

logical

reinterpretcast

rescale

single

stripscaling

uint16

uint32

uint64

uint8

Double-precision floating-point real-world value of

fi object

Smallest built-in integer fitting stored integ er value of

fi obje ct

Stored integer value of fi object as built-in

int16

Stored integer value of fi object as built-in

int32

Stored integer value of fi object as built-in

int64

Stored integer value of fi object as built-in

int8

Convert numeric values to logical

Convert fixed-point data types without changing underlying data

Change scaling of fi object

Single-precision floating-point real-world value of

fi object

Stored integer of fi object

Stored integer value of fi object as built-in

uint16

Stored integer value of fi object as built-in

uint32

Stored integer value of fi object as built-in

uint64

Stored integer value of fi object as built-in

uint8

2-7

2 Function Reference

Data Type Tools

NumericTypeScope

Data Quantizi

quantize

randquant

round

unitquan

unitqua

ntizer

tize

Element-Wise Logical Operators

Determine numeric type for data

Apply quantizer object to data

Generate uniformly distributed, quantized random number using

quantizer object

Round fi ob integer or

quantizer

Quantize of +1

Constru object

ject toward nearest

round input data using

object

except numbers within

ctor for

unitquantizer

eps

2-8

all

and

any

Determine whether all a rray elements are nonzero

Find logical AND of array or scalar inputs

ermine whether any array

Det

ments are nonzero

ele

nd logical NOT of array or scalar

put

Math Operations

xor

Math Operations

abs

add

ceil

complex

conj

conv

convergent

cordiccexp

cordiccos

cordicsin

cordicsincos

divide

filter

fix

floor

Find logical OR of array or scalar inputs

Logical exclusive-OR

Absolute value of fi object

Add two objects using fimath object

Round toward positive infinity

Construct complex fi object from real and imaginary parts

Complex conjugate of fi object

Convolution and polynomial multiplication of

fi obje cts

Round toward nearest integer with ties rounding to nearest even integer

CORDIC-based approximation of complex exponential

CORDIC-based approximation of cosine

CORDIC-based approximation of sine

CORDIC-based approximation of sine and co sine

Divide two objects

One-dimensional digital filter of fi objects

Round toward zero

Round toward negative infinity

2-9

2 Function Reference

imag

innerprodintbits

minus

mpower

mpy

mrdivide

mtimes

nearest

plus

pow2

power

rdivide

real

round

sign

sqrt

sub

sum

times

uminus

uplus

Imaginary part of complex number

Number of integer bits needed for fixed-point inner produ ct

Matrix difference between fi objects

Fixed-point matrix power (^)

Multiply two objects using fimath object

Forward slash (/) or right-matrix division

Matrix product of fi objects

Round toward nearest integer with ties rounding toward positive infinity

Matrix sum of fi objects

Efficient fixed-point multiplication

by 2

Fixed-point array power (.^)

Right-array division (./)

Real part of complex number

Round fi object toward nearest integer or round input data using

quantizer object

Perform sig num function on array

Square root of fi obje ct

Subtract two objects using fimath object

Sum of array elements

Element-by-element multiplication of

fi objects

Negate elem ents of fi object array

Unary plus

2-10

Matrix Manipulation

buffer

ctranspose

diag

disp

end

flipdim

fliplr

flipud

hankel

horzcat

ipermute

iscolumn

empty

isfinite

isinf

isnan

isnumeric

isobject

Buffer signal vector into matrix of data frames

Complex conjugate transpose of fi object

Diagonal matrices or diagonals of matrix

Display object

Last index of array

Flip array along specified dimension

Flip matrix left to right

Flip mat

rix up to down

Hankel matrix

Horizontally concatenate multiple

fi objects

Inverse permute dimensions of multidimensional array

ermine whether

Det

umn vector

col

fi object is

Determine whether array is empty

Determine whether array elements are finite

Determine whether array elements are infinite

Determine whether array elements are NaN

Determine whether input is numeric array

Determine whether input is MATLAB object

2-11

2 Function Reference

isreal

isrow

isscalar

isvector

length

ndgrid

ndims

permute

repmat

reshape

shiftdata

shiftdim

size

sort

squeeze

toeplitz

transpose

tril

triu

unshiftdata

vertcat

Determine whether array elements are real

Determine whether fi object is row vector

Determine whether input is scalar

Determine whether input is vector

Vector length

Generate arrays for N-D functions and interpolation

Number of array dimensions

Rearrange dimensions of multidimensional array

Replicate and tile array

Reshape array

Shift data to operate on specified dimension

Shift dimensions

Array dimensions

Sort elements of real-v alued fi object in ascending or descending order

Remove singleton dimensions

Create Toeplitz matrix

Transpose operation

Lowertriangularpartofmatrix

Uppertriangularpartofmatrix

Inverse of shiftdata

Vertically concatenate m ultiple fi objects

2-12

Plots

area

bar

barh

clabel

comet

comet3

compass

coneplot

contour

contour3

contourc

contourf

errorbar

eeplot

etr

ezcontour

ezcontourf

ezmesh

ezplot

ezplot3

ezpolar

ezsurf

ezsurfc

Create filled area 2-D plot

Create vertical bar graph

Create horizontal bar graph

Create contour plot elevation labels

Create 2-D comet plot

Create 3-D comet plot

Plot arrows emanating from origin

Plot velocity vectors as cones in 3-D vector field

Create contour graph of matrix

Create 3-D contour plot

Create two-level contour plot computation

Create filled 2-D contour plot

error bars along curve

Plot

Plot elimination tree

Easy-to-use contour plotter

Easy-to-use fille d contour plotter

asy-to-use 3-D mesh plotter

Easy-to-use function plotter

Easy-to-use 3-D parametric curve plotter

Easy-to-use polar coordinate plotter

Easy-to-use 3-D colored surface plotter

Easy-to-use combination surface/contour plotter

2-13

2 Function Reference

feather

fplot

gplot

hist

histc

line

loglog

mesh

meshc

meshz

patch

pcolor

plot

plot3

plotmatrix

plotyy

polar

quiver

quiver3

rgbplot

ribbon

rose

scatter

scatter3

Plot velocity vectors

Plot function between specified limits

Plot set of nodes using a djace ncy matrix

Create histogram plot

Histogram count

Create line object

Create log-log scale plot

Create mesh plot

Create mesh plot with contour plot

Create mesh plot with curtain plot

Create patch graphics object

Create pseudocolor plot

Create linear 2-D plot

Create 3-D line plot

Draw scatter plots

Creategraphwithy-axesonright and left sides

Plot polar coordinates

Create quiver or velocity plot

Create 3-D quiver or velocity plot

Plot colormap

Create ribbon plot

Create angle histogra m

Createscatterorbubbleplot

Create 3-D scatter or bubble p lot

2-14

Plots

semilogx

semilogy

slice

spy

stairs

stem

stem3

streamribbon

streamslice

streamtube

surf

surfc

surfl

surfnorm

text

treeplot

trimesh

triplot

trisurf

voronoi

voronoin

waterfall

xlim

Create semilogarithmic plot with logarithmic x-axis

Create semilogarithmic plot with logarithmic y-axis

Create volumetric slice plot

Visualize sparsity pattern

Create stairstep graph

Plot discrete sequence data

Plot 3-D discrete sequence data

Create 3-D stream ribbon plot

Draw streamlines in slice planes

Create 3-D stream tube plot

Create 3-D shaded surface plot

Create 3-D shaded surface plot with contour plot

Create surface plot with colormap-based lighting

Compute and display 3-D surface normals

Create text object in current axes

Plot picture of tree

Create triangular mesh plot

Create 2-D triangular plot

Create triangular surface plot

Create Voronoi diagram

Create n-D Voronoi diagram

Create waterfall plot

Set or query x-axis limits

2-15

2 Function Reference

ylim

zlim

Radix Conversion

bin

bin2num

dec

hex

hex2num

num2bin

num2hex

num2int

oct

sdec

Set or query y-axis limits

Set or query z-axis limits

Binary representation of stored integer of

fi object

Convert two’s complement binary string to number using

quantizer

object

Unsigned decimal representation of stored integer of

fi object

Hexadecimal representation of stored integer of

fi object

Convert hexadecimal string to number using

quantizer object

Convert number to binary string using

quantizer object

Convert number to hexadecimal equivalent using

quantizer object

Convert number to signed integer

Octal representation of stored integer of

fi object

Signed decimal representation of stored integer of

fi object

2-16

Relational Operators

Stati

stics

errmean

errpdf

errvar

logreport

max

maxlog

mean

median

Determine whether real-world values of two

Determine whe of one

fi objec

equal to anoth

fi objects are equal

ther real-world value

t is greater than or

Determine whether real-world value of one

fi object is greater than

another

Determine whether real-world value of

fi object is less than or equal to

another

Determin of one

e whether real-world value object is less than another

Determine whether real-world values of two

fi objects are not equal

Mean of quantization error

Probability density function of quantization error

Variance of quantization error

Quantization report

Largest element in array of fi objects

Log maximums

Average or mean value of fixed-point array

Median value of fixed-point array

2-17

2 Function Reference

min

minlog

noperations

noverflows

numberofelements

nunderflows

resetlog

Smallest element in array of fi objects

Log minimums

Number of operations

Number of overflows

Number of data elements in fi array

Number of underflows

Clear log for fi or quantizer object

Subscripted Assignment an d Reference

subsasgn

subsref

Subscripted assignment

Subscripted reference

2-18

fi Object Operations

abs

all

and

any

area

assignmentquantizer

bar

barh

bin

bitand

bitandreduce

bitcmp

bitconcat

bitget

bitor

bitorreduce

bitreplicate

bitrol

bitror

bitset

Absolute value of fi object

Determine whether all a rray elements are nonzero

Find logical AND of array or scalar inputs

Determine whether any array elements are nonzero

Create filled area 2-D plot

Assignment quantizer object of fi object

Create vertical bar graph

Create horizontal bar graph

Binary representation of stored integer of

fi object

Bitwise AND of two fi objects

Bitwise AND of consecutive range of bits

Bitwise complement of fi object

Concatenate bits of fi objects

Bitatcertainposition

Bitwise OR of two fi objects

Bitwise OR of consecutive range of bits

Replicate and concatenate bits of fi object

Bitwiserotateleft

Bitwiserotateright

Set bit at certain position

2-19

2 Function Reference

bitshift

bitsliceget

bitsll

bitsra

bitsrl

bitxor

bitxorreduce

buffer

ceil

clabel

comet

comet3

compass

complex

coneplot

conj

contour

contour3

contourc

contourf

conv

convergent

Shift bits specified number of places

Consecutive slice of bits

Bit shift left logical

Bit shift right arithmetic

Bitshiftrightlogical

Bitwise exclusive OR of two fi objects

Bitwise exclusive OR of consecutive range of b its

Buffer signal vector into matrix of data frames

Round toward positive infinity

Create contour plot elevation labels

Create 2-D comet plot

Create 3-D comet plot

Plot arrows emanating from origin

Construct complex fi object from real and imaginary parts

Plot velocity vectors as cones in 3-D vector field

Complex conjugate of fi object

Create contour graph of matrix

Create 3-D contour plot

Create two-level contour plot computation

Create filled 2-D contour plot

Convolution and polynomial multiplication of

fi obje cts

Round toward nearest integer with ties rounding to nearest even integer

2-20

fi Object Operations

cordiccexp

cordiccos

cordicsin

cordicsincos

ctranspose

dec

diag

disp

double

end

eps

errorbar

etreeplot

ezcontour

ezcontourf

ezmesh

ezplot

ezplot3

ezpolar

CORDIC-based approximation of complex exponential

CORDIC-based approximation of cosine

CORDIC-based approximation of sine

CORDIC-based approximation of sine and co sine

Complex conjugate transpose of fi object

Unsigned decimal representation of stored integer of

fi object

Diagonal matrices or diagonals of matrix

Display object

Double-precision floating-point real-world value of

fi object

Last index of array

Quantized relative accuracy for fi or quantizer objects

Determine whether real-world values of two

fi objects are equal

Plot error bars along curve

Plot elimination tree

Easy-to-use contour plotter

Easy-to-use fille d contour plotter

Easy-to-use 3-D mesh plotter

Easy-to-use function plotter

Easy-to-use 3-D parametric curve plotter

Easy-to-use polar coordinate plotter

2-21

2 Function Reference

ezsurf

ezsurfc

feather

filter

fimath

fix

flipdim

fliplr

flipud

floor

fplot

get

getlsb

getmsb

gplot

hankel

hex

Easy-to-use 3-D colored surface plotter

Easy-to-use combination surface/contour plotter

Plot velocity vectors

Construct fixed-point numeric object

One-dimensional digital filter of fi objects

Construct fimath object

Round toward zero

Flip array along specified dimension

Flip matrix left to right

Flip matrix up to down

Round toward negative infinity

Plot function between specified limits

Determine whether real-world value of one

fi object is greater than or

equal to ano the r

Property values of object

Least significant bit

Most significant bit

Plot set of nodes using a djace ncy matrix

Determine whether real-world value of one

fi object is greater than

another

Hankel matrix

Hexadecimal representation of stored integer of

fi object

2-22

fi Object Operations

hist

histc

horzcat

imag

innerprodintbits

int

int16

int32

int64

int8

intmax

intmin

ipermute

isboolean

iscolumn

isdouble

isempty

Create histogram plot

Histogram count

Horizontally concatenate multiple

fi objects

Imaginary part of complex number

Number of integer bits needed for fixed-point inner produ ct

Smallest built-in integer fitting stored integ er value of

fi obje ct

Stored integer value of fi object as built-in

int16

Stored integer value of fi object as built-in

int32

Stored integer value of fi object as built-in

int64

Stored integer value of fi object as built-in

int8

Largest positiv e stored intege r value representable by

numerictype of fi

object

Smallest stored integer value representable by

numerictype of fi

object

Inverse permute dimensions of multidimensional array

Determine whether input is Boolean

Determine whether fi object is column vector

Determine whether input is double-precision data type

Determine whether array is empty

2-23

2 Function Reference

isequal

isfi

isfimathlocal

isfinite

isfixed

isfloat

isinf

isnan

isnumeric

isobject

ispropequal

isreal

isrow

isscalar

isscaleddouble

Determine whether real-world values of two

fi objects are equal, or

determine whether properties of two

fimath, numerictype,orquantizer

objects are equal

Determine whether variable is fi object

Determine whether fi object has local fimath

Determine whether array elements are finite

Determine whether input is fixed-point data type

Determine whether input is floating-point data type

Determine whether array elements are infinite

Determine whether array elements are NaN

Determine whether input is numeric array

Determine whether input is MATLAB object

Determine whether properties of two

fi objects are equal

Determine whether array elements are real

Determine whether fi object is row vector

Determine whether input is scalar

Determine whether input is scaled double data type

2-24

fi Object Operations

isscaledtype

issigned

issingle

isvector

length

line

logical

loglog

logreport

lowerbound

lsb

max

maxlog

mean

median

mesh

meshc

meshz

Determine whether input is fixed-point or scaled double data type

Determine whether fi object is signed

Determine whether input is single-precision data type

Determine whether input is vector

Determine whether real-world value of

fi object is less than or equal to

another

Vector length

Create line object

Convert numeric values to logical

Create log-log scale plot

Quantization report

Lower bound of range of fi object

Scaling of least significant bit of fi object, or value of least significant bit of

quantizer object

Determine whether real-world value of one

fi object is less than another

Largest element in array of fi objects

Log maximums

Average or mean value of fixed-point array

Median value of fixed-point array

Create mesh plot

Create mesh plot with contour plot

Create mesh plot with curtain plot

2-25

2 Function Reference

min

minlog

minus

mpower

mrdivide

mtimes

ndgrid

ndims

nearest

not

noverflows

numberofelements

numerictype

nunderflows

oct

patch

pcolor

permute

plot

Smallest element in array of fi objects

Log minimums

Matrix difference between fi objects

Fixed-point matrix power (^)

Forward slash (/) or right-matrix division

Matrix product of fi objects

Generate arrays for N-D functions and interpolation

Number of array dimensions

Determine whether real-world values of two

fi objects are not equal

Round toward nearest integer with ties rounding toward positive infinity

Find logical NOT of array or scalar input

Number of overflows

Number of data elements in fi array

Construct numerictype object

Number of underflows

Octal representation of stored integer of

fi object

Find logical OR of array or scalar inputs

Create patch graphics object

Create pseudocolor plot

Rearrange dimensions of multidimensional array

Create linear 2-D plot

2-26

fi Object Operations

plot3

plotmatrix

plotyy

plus

polar

pow2

power

quantizer

quiver

quiver3

range

rdivide

real

realmax

realmin

reinterpretcast

repmat

rescale

resetlog

reshape

rgbplot

ribbon

Create 3-D line plot

Draw scatter plots

Creategraphwithy-axesonright and left sides

Matrix sum of fi objects

Plot polar coordinates

Efficient fixed-point multiplication

by 2

Fixed-point array power (.^)

Construct quantizer object

Create quiver or velocity plot

Create 3-D quiver or velocity plot

Numerical range of fi or quantizer object

Right-array division (./)

Real part of complex number

Largest positiv e fixed-point value or quantized number

Smallest positive normalized fixed-point value or quan tized number

Convert fixed-point data types without changing underlying data

Replicate and tile array

Change scaling of fi object

Clear log for fi or quantizer object

Reshape array

Plot colormap

Create ribbon plot

2-27

2 Function Reference

rose

round

scatter

scatter3

sdec

semilogx

semilogy

sfi

shiftdata

shiftdim

sign

single

size

slice

sort

spy

sqrt

squeeze

stairs

stem

stem3

Create angle histogra m

Round fi object toward nearest integer or round input data using

quantizer object

Createscatterorbubbleplot

Create 3-D scatter or bubble p lot

Signed decimal representation of stored integer of

fi object

Create semilogarithmic plot with logarithmic x-axis

Create semilogarithmic plot with logarithmic y-axis

Construct signed fixed-point numeric object

Shift data to operate on specified dimension

Shift dimensions

Perform sig num function on array

Single-precision floating-point real-world value of

fi object

Array dimensions

Create volumetric slice plot

Sort elements of real-v alued fi object in ascending or descending order

Visualize sparsity pattern

Square root of fi obje ct

Remove singleton dimensions

Create stairstep graph

Plot discrete sequence data

Plot 3-D discrete sequence data

2-28

fi Object Operations

streamribbon

streamslice

streamtube

stripscaling

subsasgn

subsref

sum

surf

surfc

surfl

surfnorm

text

times

toeplitz

transpose

treeplot

tril

trimesh

triplot

trisurf

triu

ufi

uint16

Create 3-D stream ribbon plot

Draw streamlines in slice planes

Create 3-D stream tube plot

Stored integer of fi object

Subscripted assignment

Subscripted reference

Sum of array elements

Create 3-D shaded surface plot

Create 3-D shaded surface plot with contour plot

Create surface plot with colormap-based lighting

Compute and display 3-D surface normals

Create text object in current axes

Element-by-element multiplication of

fi objects

Create Toeplitz matrix

Transpose operation

Plot picture of tree

Lowertriangularpartofmatrix

Create triangular mesh plot

Create 2-D triangular plot

Create triangular surface plot

Uppertriangularpartofmatrix

Construct unsigned fixed-point numeric object

Stored integer value of fi object as built-in

uint16

2-29

2 Function Reference

uint32

uint64

uint8

uminus

unshiftdata

uplus

upperbound

vertcat

voronoi

voronoin

waterfall

xlim

xor

ylim

zlim

Stored integer value of fi object as built-in

uint32

Stored integer value of fi object as built-in

uint64

Stored integer value of fi object as built-in

uint8

Negate elem ents of fi object array

Inverse of shiftdata

Unary plus

Upper bound of range of fi object

Vertically concatenate m ultiple fi objects

Create Voronoi diagram

Create n-D Voronoi diagram

Create waterfall plot

Set or query x-axis limits

Logical exclusive-OR

Set or query y-axis limits

Set or query z-axis limits

2-30

fimath Object Operations

add

disp

fimath

globalfimath

isequal

isfimath

mpy

removedefaultfimathpref

removeglobalfimathpref

resetdefaultfimath

resetglobalfimath

savedefaultfimathpref

saveglobalfimathpref

setdefaultfimath

sqrt

sub

Add two objects using fimath object

Display object

Construct fimath object

Configure global fimath and return handle object

Determine whether real-world values of two

fi objects are equal, or

determine whether properties of two

fimath, numerictype,orquantizer

objects are equal

Determine whether variable is

fimath object

Multiply two objects using fimath object

Remove global fimath preference

Set global fimath to MATLAB factory default

Save global fimath for next MATLAB session

Set MATLAB global fimath

Square root of fi obje ct

Subtract two objects using fimath object

2-31

2 Function Reference

fipref Object Operations

disp

fipref

isfipref

reset

savefipref

Display object

Construct fipref object

Determine whether input is fipref object

Reset objects to initial conditions

Save fi preferences for next MATLAB session

2-32

numerictype Object O perations

numerictype Object Operations

disp

divide

isboolean

isdouble

isequal

isfixed

isfloat

isnumerictype

aleddouble

issc

isscaledtype

issingle

isslopebiasscaled

sqrt

tostring

Display object

Divide two obje

cts

Determine whether input is Boolean

Determine whether input is double-precision data type

Determine values of t determine

fimath, n

objects a

whether real-world

fi objects are equal, or

whether properties of two

umerictype

,orquantizer

re equal

Determine whether input is fixed-point data type

Determine whether input is floating-point data type

mine whether input is

Deter

nume

rictype

object

Determine whether input is scaled double data type

Determine whether input is fixed-point or scaled double data type

etermine whether input is

ingle-precision data type

Determine whether numerictype object has nontrivial slope and bias

Square root of fi obje ct

Convert numerictype or quantizer object to string

2-33

2 Function Reference

quantizer Object Operations

bin2num

copyobj

denormalmax

denormalmin

disp

eps

errmean

errpdf

errva

entbias

expon

nentlength

expo

onentmax

exp

ponentmin

ractionlength

hex2num

Convert two’s complement binary string to number using

quantizer

object

Make independent c o py of quantizer object

Largest denormalized quantized number for

quantizer object

Smallest denormalized quantized number for

Display ob

Quantize or quanti

Mean of q

Probab quanti

Varia

Expon

nent length of

Expo

imum exponent for

Max

ect

obj

imum exponent for

Min

ject

action length of

roperty values of object

quantizer object

ject

d relative accuracy for

zer

objects

uantization error

ility density function of

zation error

nce of quantization error

ent bias for

quantizer object

quantizer

quantizer object

Convert hexadecimal string to number using

quantizer object

2-34

quantizer Object Operations

isequal

isfixed

isfloat

isquantizer

length

lsb

max

maxlog

min

minlog

noperations

noverflows

num2bin

num2hex

num2int

nunderflows

quantize

quantizer

Determine whether real-world values of two

fi objects are equal, or

determine whether properties of two

fimath, numerictype,orquantizer

objects are equal

Determine whether input is fixed-point data type

Determine whether input is floating-point data type

Determine whether input is

quantizer object

Vector length

Scaling of least significant bit of fi object, or value of least significant bit of

quantizer object

Largest element in array of fi objects

Log maximums

Smallest element in array of fi objects

Log minimums

Number of operations

Number of overflows

Convert number to binary string using

quantizer object

Convert number to hexadecimal equivalent using

quantizer object

Convert number to signed integer

Number of underflows

Apply quantizer object to data

Construct quantizer object

2-35

2 Function Reference

randquant

range

realmax

realmin

reset

resetlog

round

set

tostring

unitquantize

unitquantizer

wordlength

Generate uniformly distributed, quantized random number using

quantizer object

Numerical range of fi or quantizer object

Largest positiv e fixed-point value or quantized number

Smallest positive normalized fixed-point value or quan tized number

Reset objects to initial conditions

Clear log for fi or quantizer object

Round fi object toward nearest integer or round input data using

quantizer object

Set or display property values for

quantizer objects

Convert numerictype or quantizer object to string

Quantize except numbers within eps of +1

Constructor for unitquantizer object

Word length of quantizer object

2-36

Functions — Alphabetical List

abs

Purpose Absolute value of fi object

Syntax c = abs(a)

c = abs(a,T) c = abs(a,F) c = abs(a,T,F)

Description c = abs(a) returns the absolute value of fi object a with the same

numerictype object as a. Intermediate quantities are calculated using

the

fimath associated with a.

c = abs(a,T) returns a fi object with a value equal to the absolute

value of calculated using the Propagation Rules” on pa ge 3-3.

c = abs(a,F) returns a fi object with a value equal to the absolute

value of quantities are calculated using the object c is always associated with the global fimath.

a and numerictype object T. Intermediate quantities are

fimath associated with a.See“DataType

a and the same numerictype object as a.Intermediate

fimath object F, and the output fi

3-2

c = abs(a,T,F) returns a fi object with a value equal to the absolute

value of calculated using the

a and the numerictype object T. Intermediate quantities are

fimath object F, and the output fi object c is

always associated with the global fimath. See “Data Type Propagation Rules” on page 3-3.

Note When the Signedness of the input numerictype object T is Auto, the

abs function always returns an Unsigned fi object.

abs only supports fi objects with [Slope Bias] scaling when the bias is

zero and the fractional slope is one.

abs does not support complex fi

objects of data type Boolean.

When the object

a is real and has a signed data type, the absolute value

of the most negative value is problematic since it is not representable. In this case, the absolute value saturates to the most positive value

representable by the data type if the OverflowMode property is set to

saturate.IfOverflowMode is wrap, the absolute value of the most

negative value has no effect.

abs

Data Type Propagation Rules

For syntaxes for which you specify a numerictype object T,theabs function follows the data type propagation rules listed in the following table. In general, these rules can be summarized as “floating-point data types are propagated.” This allows you to write code that can be used with both fixed-point and floating-point inputs.

Data Type of Input fi Object a

fi Fixed fi Fixed

fi ScaledDouble fi Fixed ScaledDouble

fi double fi Fixed fi double

fi single fi Fixed fi single

Any fi data type

Examples Example 1

Data Type of numerictype object T

fi double fi double

fi single fi single

Data Type of Output c

Data type of

numerictype object T

with properties of

numerictype object T

Thefollowingexampleshowsthedifferencebetweentheabsolutevalue results for the most negative value representable by a signed data type when

OverflowMode is saturate or wrap.

P = fipref('NumericTypeDisplay','full',...

'FimathDisplay','full');

a = fi(-128)

3-3

abs

-128

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 8

abs(a)

ans =

127.9961

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 8

3-4

a.OverflowMode = 'wrap'

-128

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 8

RoundMode: nearest

OverflowMode: wrap

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

abs(a)

ans =

-128

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 8

RoundMode: nearest

OverflowMode: wrap

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

Example 2

abs

Thefollowingexampleshowsthedifferencebetweentheabsolutevalue results for complex and real value represe ntable by a signed data type when

re = fi(-1,1,16,15)

re =

-1

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 15

im = fi(0,1,16,15)

fi inputs that have the most negative

OverflowMode is wrap.

3-5

abs

im =

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 15

a = complex(re,im)

-1

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 15

3-6

abs(a,re.numerictype,fimath('overflowmode','wrap'))

ans =

1.0000

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 15

abs(re,re.numerictype,fimath('overflowmode','wrap'))

ans =

-1

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 15

Example 3

The following example shows how to specify numerictype and fimath objects as optional arguments to control the result of the abs function for real inputs. When you specify a

fimath object is used to compute intermediate quantities, and the

resulting

a = fi(-1,1,6,5,'overflowmode','wrap')

fi object is always associated with the global fimath.

-1

fimath object as an argument, that

abs

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 6

FractionLength: 5

RoundMode: nearest

OverflowMode: wrap

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

abs(a)

ans =

-1

3-7

abs

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 6

FractionLength: 5

RoundMode: nearest

OverflowMode: wrap

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

f = fimath('overflowmode','saturate')

RoundMode: nearest

OverflowMode: saturate

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

3-8

abs(a,f)

ans =

0.9688

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 6

FractionLength: 5

t = numerictype(a.numerictype, 'signed', false)

FractionLength: 5

abs(a,t,f)

ans =

FractionLength: 5

abs

DataTypeMode: Fixed-point: binary point scaling

Signedness: Unsigned WordLength: 6

DataTypeMode: Fixed-point: binary point scaling

Signedness: Unsigned WordLength: 6

Example 4

The following example shows how to specify numerictype and fimath objects as optional arguments to control the result of the abs function for complex inputs.

a = fi(-1-i,1,16,15,'overflowmode','wrap')

-1.0000 - 1.0000i

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 16

FractionLength: 15

3-9

abs

RoundMode: nearest

OverflowMode: wrap

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

t = numerictype(a.numerictype,'signed',false)

DataTypeMode: Fixed-point: binary point scaling

Signedness: Unsigned WordLength: 16

FractionLength: 15

abs(a,t)

3-10

ans =

1.4142

DataTypeMode: Fixed-point: binary point scaling

Signedness: Unsigned WordLength: 16

FractionLength: 15

RoundMode: nearest

OverflowMode: wrap

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: FullPrecision

MaxSumWordLength: 128

f = fimath('overflowmode','saturate','summode',...

'keepLSB','sumwordlength',a.wordlength,... 'productmode','specifyprecision',... 'productwordlength',a.wordlength,... 'productfractionlength',a.fractionlength)

RoundMode: nearest

OverflowMode: saturate

ProductMode: SpecifyPrecision

ProductWordLength: 16

ProductFractionLength: 15

SumMode: KeepLSB SumWordLength: 16 CastBeforeSum: true

abs(a,t,f)

abs

ans =

1.4142

DataTypeMode: Fixed-point: binary point scaling

Signedness: Unsigned WordLength: 16

FractionLength: 15

Algorithm Theabsolutevaluey of a real input a is defined as follows:

y = a if a >= 0

y =-a if a <0

The absolute value imaginary parts as follows:

y of a complex input a is related to its real and

3-11

abs

y = sqrt(real(a)*real(a) + imag(a)*imag(a))

The abs function computes the absolute value of complex inputs as follows:

1 Calculate the real and imaginary parts of a using the following

equations:

re = real(a)

im = imag(a)

2 Compute the squares of re and im using one of the following objects:

• The

3 Cast the squares of re and im to unsigned types if the input is signed.

4 Add the squares of re and im using one o f the following objects:

• The

fimath object F if F is specified as an argument.

fimath associated with a if F is not specified as an argument.

fimath object F if F is specified as an argument.

fimath object associated with a if F is not specified as an

argument.

5 Compute the square root of the sum computed in step four using the

sqrt function with the following additional arguments:

• The

numerictype object T if T is specified, or the numerictype

object of a otherwise.

• The

fimath object F if F is specified, or the fimath object associated

with

a otherwise.

3-12

Note Step three prevents the sum of the squares of the real and imaginary components from being negative. This is important because if either property is set to wrap then an error will occur when taking the square root in step five.

re or im has the maximum negative value and the OverflowMode

abs

3-13

add

Purpose Add two objects using fimath object

Syntax c = F.add(a,b)

Description c = F.add(a,b) adds objects a and b using fimath object F.Thisis

helpful in cases when you want to override the

b,orifthefimath properties associated with a and b are different. The

output

a and b must have the same dimensions unless one is a scalar. If either a or b is scalar, then c has the dimensions of the nonscalar object.

fi object c is always associated with the global fimath.

fimath objects of a and

If either numeric type, then the built-in object is cast to the word length of the

fi object, preserving best-precision fraction length.

a or b is a fi object, and the other is a MATLAB built-in

Examples In this example, c is the 32-bit sum of a and b with fraction length 16:

a = fi(pi); b = fi(exp(1)); F = fimath('SumMode','SpecifyPrecision','SumWordLength',32,... 'SumFractionLength',16); c = F.add(a,b)

5.8599

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 32

FractionLength: 16

Algorithm c = F.add(a,b) is similar to

a.fimath = F; b.fimath = F;

3-14

c=a+b c=

5.8599

DataTypeMode: Fixed-point: binary point scaling

Signedness: Signed WordLength: 32

FractionLength: 16

RoundMode: nearest

OverflowMode: saturate

ProductMode: FullPrecision

MaxProductWordLength: 128

SumMode: SpecifyPrecision SumWordLength: 32

SumFractionLength: 16

CastBeforeSum: true

but not identical. When you use add,thefimath properties of a and

b arenotmodified,andtheoutputfi object c is associated with the

global fimath. When you use the syntax

c=a+b,wherea and b

have their own fimath objects, the output fi object c gets assigned the same

fimath object as inputs a and b.See“fimathRulesfor

Fixed-Point Arithmetic” in the Fixed-Point Toolbox User’s Guide for more information.

add

See Also divide, fi, fimath, mpy, mrdivide, numerictype, rdivide, sub, sum

3-15

all

Purpose Determine whether all a rray elements a re nonzero

Description Refer to the MATLAB all reference page for more information.

3-16

Purpose Find logical AND of array or scalar inputs

Description Refer to the MATLAB and reference page for more information.

and

3-17

any

Purpose Determine whether any array elements are nonzero

Description Refer to the MATLAB any reference page for more information.

3-18

Purpose Create filled area 2-D plot

Description Refer to the MATLAB area reference page for more information.

area

3-19

assignmentquantizer

Purpose Assignment quantizer object of fi object

Syntax q = assignmentquantizer(a)

Description q = assignmentquantizer(a) returns the quantizer object q that is

used in assignment operations for the

Mathworks FIXED-POINT TOOLBOX 3 Reference

Specifications and Main Features

Frequently Asked Questions

User Manual