     [file fixedversion.txi not included]

The Basics of the Fixed Point Types
***********************************

When implementing algorithms in hardware, it is common to reduce the accuracy of the representation of numbers to a smaller number of bits. This allows much lower complexity in the hardware, at the cost of accuracy and potential overflow problems. Such representations are known as fixed point.

This toolbox supplies a fixed point type that allows Octave to model the effects of such a reduction in accuracy of the representation of numbers. The major advantage of this toolbox is that with correctly written Octave scripts, the same code can be used to test both fixed and floating point representations of numbers.

The authors have tried to take all care to ensure the correct functionality of this package. However, as this code is relatively recent we expect that there will be a certain number of problems. We welcome all reports of bugs, etc or even success stories. The authors can be contacted at the e-mail address David.Bateman@motorola.com.

The License used with this Package
==================================

The license used with this package is the GNU General Public License, a copy of which is distributed with this package in the file COPYING. Some commercial users have seemed quite concerned about the use of software licensed under the GPL in their development. To ease these concerns, the authors state in clear English the terms of the GPL allow that

 1. Any algorithm developed with this package remains the sole property of the party developing the algorithm.

 2. Changes can be made to the fixed point package, with the constraint that if you supply a version of the fixed point package to another party it must equally be covered by the terms of the GPL.

We believe that there is little reason to make proprietary changes to the fixed point package itself. So this clear distinction between the fixed point code itself and algorithms developed with it means that there should be little concern for a use of this package in the development of a proprietary algorithms.

Proprietary changes to the fixed point package itself are possible. The GPL only comes into play in if you distribute the fixed point package with these changes. The algorithms developed on these modified versions of the fixed point package remain proprietary in all cases.

Fixed Point Representation
==========================

Fixed point numbers can be represented digitally in several manners, including sign-magnitude, ones-complement and twos-complement. The most commonly used technique is twos-complement due to the easier implementation of certain operations in this representation. As such this toolbox uses the twos-complement representation of numbers

All fixed point objects in this toolbox are represented by an int that is used in the following manner

1 bit representing the sign,

IS bits representing the integer part of the number, and

DS bits representing the decimal part of the number.

The numbers that can then be represented are then given by

     - 2 ^ IS <= X <= 2 ^IS -1

and the distance between two values of X that are not represented by the same fixed point value is 2 ^ (-DS) .

The number of bits that can be used in the representation of the fixed point objects is determined by the number of bits in an int on the platform. Valid values include 32- and 64-bits. To avoid issues with overflows in additions, one of these bits can not be used. Therefore valid values of IS and DS are given by

     0 < ( IS + DS ) < N - 2

where N is either 32 or 64, depending on the number of bits in an int. It should be noted that given the above criteria it is possible to create a fixed point representation that lacks a representation of the number 1. This makes the implementation of certain operators difficult, and so the valid representations are further limited to

     0 < ( IS, DS, IS + DS ) < N - 2

This does not mean that other numbers can not be represented by this toolbox, but rather that the numbers must be scaled prior to their being represented.

This toolbox allows both fixed point real and complex scalars to be represented, as well as fixed point real and complex matrices. The real and imaginary parts of the fixed point number and each element of a fixed point matrix has its own fixed point representation.

Creating Fixed Point Numbers
============================

Before using a fixed point type, some variables must be created that use this type. This is done with the function fixed. The function fixed can be used in several manners, depending on the number and type of the arguments that are given. It can be used to create scalar, complex, matrix and complex matrix values of the fixed type.

The generic call to fixed is fixed(IS,DS,F), where the variables are

IS
     The number of bits to use in the representation of the integer part of the fixed point value. This can be either a real or complex value, and can be either a scalar or a matrix. As the fixed point representation of complex values uses separate representations for the real and imaginary parts, a complex value of IS gives the representation of the real and imaginary parts separately. IS must contain only integer or complex integer values greater than zero, and less than 30 or 62 as discussed in the previous section.

DS
     Similarly to IS, DS represents the number of bits in the decimal part of the fixed point representation. The same conditions as for IS apply to DS

F
     This variable can be either a scalar, complex, matrix or complex matrix of values that will be converted to a fixed point representation. It can equally be another fixed point value, in which case fixed has the effect of changing the representation of F to another representation given by IS and DS.

If matrices are used for IS, DS, or F, then the dimensions of all of the matrices must match. However, it is valid to have IS or DS as scalar values, which will be expanded to the same dimension as the other matrices, before use in the conversion to a fixed point value. The variable F however, must be a matrix if either IS or DS is a matrix.

The most basic use of the function fixed can be seen in the example

     octave:1> a = fixed(7,2,1)
     ans = 1
     octave:2> isfixed(a)
     ans = 1
     octave:3> whos a
     *** local user variables:

     prot  type                       rows   cols  name
     ====  ====                       ====   ====  ====
      rwd  fixed scalar                  1      1  a

which demonstrates the creation of a real scalar fixed point value with 7 bits of precision in the integer part, 2 bits in the decimal part and the value 1. The function isfixed can be used to identify whether a variable is of the fixed point type or not. Equally, using the whos function allows the variable to be identified as "fixed scalar".

Other examples of valid uses of fixed are

     octave:1> a = fixed(7, 2, 1);
     octave:2> b = fixed(7, 2+1i, 1+1i);
     octave:3> c = fixed(7, 2, 255*rand(10,10) - 128);
     octave:4> is = 3*ones(10,10) + 4*eye(10);
     octave:5> d = fixed(is, 1, eye(10));
     octave:6> e = fixed(7, 2, 255*rand(10,10)-128 +
     >			1i*(255*rand(10,10)-128));
     octave:7> whos

     *** local user variables:

     prot  type                       rows   cols  name
     ====  ====                       ====   ====  ====
      rwd  fixed scalar                  1      1  a
      rwd  fixed complex                 1      1  b
      rwd  fixed matrix                 10     10  c
      rwd  fixed matrix                 10     10  d
      rwd  fixed complex matrix         10     10  e

With two arguments given to fixed, it is assumed that F is zero or a matrix of zeros, and so fixed called with two arguments is equivalent to calling with three arguments with the third arguments being zero. For example

     octave:1> a = fixed([7,7], [2,2], zeros(1,2));
     octave:2> b = fixed([7,7], [2,2]);
     octave:3> assert(a == b);

Called with a single argument fixed, and a fixed point argument, b = fixed(A) is equivalent to b = a. If A is not itself fixed point, then the integer part of A is used to create a fixed point value, with the minimum number of bits needed to represent it. For example

     octave:1> b = fixed(1:4);

creates a fixed point row vector with 4 values. Each of these values has the minimum number of bits needed to represent it. That is b(1) uses 1 bit to represent the integer part, b(2:3) use 2 bits and b(4) uses 3 bits. The single argument used with fixed can equally be a complex value, in which case the real and imaginary parts are treated separately to create a composite fixed point value.

Overflow Behavior of Fixed Point Numbers
========================================

When converting a floating point number to a fixed point number the overflow behavior of the fixed point type is such that it implements clipping of the data to the maximum or minimum value that is representable in the fixed point type. This effectively simulates the behavior of an analog to digital conversion. For example

     octave:1> a = fixed(7,2,200)
     a = 127.75
     octave:2> a = fixed(7,2,-200)
     a = -128

However, the overflow behavior of the fixed point type is distinctly different if the overflow occurs within a fixed point operation itself. In this case the excess bits generated by the overflow are dropped. For example

     octave:1> a = fixed(7,2,127) + fixed(7,2,2)
     a = -127
     octave:2> a = fixed(7,2,-127) + fixed(7,2,-2)
     a = 127

The case where the representation of the fixed point object changes is different again. In this case the sign is maintained, while the most-significant bits of the representation are dropped. For example

     octave:1> a = fixed(6, 2, fixed(7, 2, -127.25))
     a = -63.25
     octave:2> a = fixed(6, 2, fixed(7, 2, 127.25))
     a = 63.25
     octave:3> a = fixed(7, 1, fixed(7, 2, -127.25))
     a = -127.5
     octave:4> a = fixed(7, 1, fixed(7, 2, 127.25))
     a = 127

In addition to the overflow issue discussed above, it is important to take into account what happens when an operator is used on two fixed point values with different representations. For example

     octave:1> a = fixed(7,2,1);
     octave:2> b = fixed(6,3,1);
     octave:3> c = a + b;
     octave:4> fprintf("%d integer, and %d decimal bits\n", c.int, c.dec);
     7 integer, and 3 decimal bits

as can be seen the fixed point value is promoted to have an output fixed point representation such that c.int = max(a.int,b.int) and c.dec = max(a.dec,b.dec). If this promotion causes the maximum number of bits in a fixed point representation to be exceeded, then an error will occur.

Fixed Point Built-in Variables
==============================

After the fixed point type is first used, four variables are initialized. These are

fixed_point_version
     The version number of the fixed point code

fixed_point_warn_overflow
     If non-zero warn of fixed point overflows. The default is 0.

fixed_point_count_operations
     If non-zero count number of fixed point operations, for later complexity analysis

fixed_point_debug
     If non-zero keep a copy of fixed point value to allow easier debugging with gdb

and they can be accessed as normal Octave built-in variables. The variable fixed_point_version can be used to create tests in the users code, to work-around any eventual problems in the fixed point type. For example

     if (strcmp(fixed_point_version, "0.6.0"))
       a = fixed([a.int, b.int], [a.dec, b.dec],
                [a.x, b.x]);
     else
       a = concat(a, b);
     endif

although this is not a real example, since both versions of the above code work with the released version of the fixed point type.

When optimizing the number of bits in a fixed point type, it is normal to expect overflows to occur, causing errors in the calculations which due to the implementation have little effect on the end result of the system.  However, it is sometimes useful to know exactly where overflows are happening or not. A non-zero value of variable fixed_point_warn_overflow permits the errors conditions in fixed point operations to cause a warning message to be printed by octave. The default behavior is to have fixed_point_warn_overflow be 0.

The octave fixed point type can keep track of all of the fixed point operations and their type. This is very useful for a simple complexity analysis of the algorithms. To allow the fixed point type to track operations the variable fixed_point_count_operations must be non-zero. The count of operations can then be reset with the reset_fixed_operations, and the number of operations since the last reset can be given by the  display_fixed_operations function.

The final in-built variable of the fixed point type is fixed_point_debug.  In normal operation this variable is of no use. However setting it to a non-zero value causes a copy of the floating point representation of a fixed point value to be stored internally. This makes debugging code using the fixed point type significantly easier using gdb.

Accessing Internal Fields
=========================

Once a variable has been defined as a fixed point object, the parameters of the field of this structure can be obtained by adding a suffix to the variable. Valid suffixes are '.x', '.sign', '.int' and '.dec', which return

.x
     The floating point representation of the fixed point number

.sign
     The sign of the fixed point number

.int
     The number of bits representing the integer part of the fixed point number

.dec
     The number of bits representing the decimal part of the fixed point number

As each fixed point value in a matrix can have a different number of bits in its representation, these suffixes return objects of the same size as the original fixed point object. For example

     octave:1> a = [-3:3];
     octave:2> b = fixed(7,2,a);
     octave:3> b.sign
     ans =

       -1  -1  -1   0   1   1   1
     octave:4> b.int
     ans =

       7  7  7  7  7  7  7
     octave:5> b.dec
     ans =

       2  2  2  2  2  2  2
     octave:5> c = b.x;
     octave:6> whos

     *** local user variables:

     prot  type                       rows   cols  name
     ====  ====                       ====   ====  ====
      rwd  matrix                        1      7  a
      rwd  fixed matrix                  1      7  b
      rwd  matrix                        1      7  c

The suffixes '.int' and '.dec' can also be used to change the internal representation of a fixed point value. This can result in a loss of precision in the representation of the fixed point value, which models the same process as occurs in hardware. For example

     octave:1> b = fixed(7,2,[3.25, 3.25]);
     octave:2> b(1).dec = [0, 2];
     b =

          3  3.25

However, the value itself should not be changed using the suffix '.x'. For instance

     octave:3> b.x = [3, 3];
     error: can not directly change the value of a fixed structure
     error: assignment failed, or no method for `fixed matrix = matrix'
     error: evaluating assignment expression near line 3, column 6

Function Overloading
====================

An important consideration in the use of the fixed point toolbox is that many of the internal functions of Octave, such as diag, can not accept fixed point objects as an input. This package therefore uses the dispatch function of Octave-Forge to overload the internal Octave functions with equivalent functions that work with fixed point objects, so that the standard function names can be used. However, at any time the fixed point specific version  of the function can be used by explicitly calling its function name. The correspondence between the internal function names and the fixed point versions is as follows

abs   -   fabs,
atan2   -   fatan2,
ceil   -   fceil,
conj   -   fconj,
cos   -   fcos,
cosh   -   fcosh,
cumprod   -   fcumprod,
cumsum   -   fcumsum,
diag   -   fdiag,
exp   -   fexp,
floor   -   ffloor,
imag   -   fimag,
log10   -   flog10,
log   -   flog,
prod   -   fprod,
real   -   freal,
reshape   -   freshape,
round   -   fround,
sin   -   fsin,
sinh   -   fsinh,
sort   -   fsort,
sqrt   -   fsqrt,
sum   -   fsum,
sumsq   -   fsumsq,
tan   -   ftan,
tanh   -   ftanh.

The version of the function that is chosen is determined by the first argument of the function. So, considering the atan2 function, if the first argument is a Matrix, then the normal version of the function is called regardless of whether the other argument of the function is a fixed point objects or not.

Many other Octave functions work correctly with fixed point objects and so overloaded versions are not necessary. This includes such functions as size and any.

It is also useful to use the '.x' option discussed in the previous section, to extract a floating point representation of the fixed point object for use with some functions.

Putting it all Together
=======================

Now that the basic functioning of the fixed point type has been discussed, it is time to consider how to put all of it together. The list of functions available for the fixed point type can be found in a later section of this document (see Function Reference)

The main advantage of this fixed point type over an implementation of specific fixed point code, is the ability to define a function once and use as either fixed or floating point. Consider the example

     function [b, bf] = testfixed(is,ds,n)
     a = randn(n,n);
     af = fixed(is,ds,a);
     b = myfunc(a,a);
     bf = myfunc(af,af);
     endfunction

     function y = myfunc(a,b)
     y = a + b;
     endfunction

In this case b and bf will be returned from the function testfixed as floating and fixed point types respectively, while the underlying function myfunc does not explicitly define that it uses a fixed point type. This is a major advantage, as it is critical to understand the loss of precision in an algorithm when converting from floating to fixed point types for an optimal hardware implementation. This mixing of functions that treat both floating and fixed point types can even apply to Oct-files (see Oct-files).

The main limitation to the above is the use of the concatenation operator, such as [a,b], that is hard-coded in versions of Octave prior to 2.1.58 and is thus not aware of the fixed-point type. Therefore, such code should be avoided in earlier versions of Octave and the function concat supplied with this package used instead.

Problems of Precision in Calculations
=====================================

When dimensioning the fixed point variables, care must be taken so that all intermediate operations don't cause a loss in the precision. This can occur with any operator or function that takes a large argument and gives a small result. Minor variations in the initial argument can result in large changes in the final result.

For instance, consider the log operator, in the example

     octave:1> a = fixed(7,2,5.25);
     octave:2> b = exp(log(a))
     b = 4.25

The logarithm log(a) is 1.65, which is rounded to 1.5. The exponential exp(log(a)) is then 4.48 which is rounded to 4.25.

A particular case in point is the power operator for complex number, which is implemented by the standard C++ class as

     X ^ Y = exp ( Y * log(X) )

Unless a large decimal precision is specified for this operator, the results will be wildly different than expected. For example

     octave:1> fixed(7,2,4*1i) ^ fixed(7,2,1)
     ans = 0.000 + 2.250i
     octave:2> fixed(7,5,4*1i) ^ fixed(7,5,1)
     ans = 0.000000 + 3.812500i

If the user chooses to use certain functions and operators, it is their responsibility to understand the implementation of the these operators, as used by their compilers to ensure the desired behavior. Alternatively, the user is recommended to implement certain operations as lookup tables, rather than use the built-in operator or function. This is how such general functions are implemented in hardware and so this is not a significant problem.

Lookup Tables
=============

It is common to implement complex functions in hardware by an equivalent lookup table. This has the advantage of speed, saving on the complexity of a full implementation of certain functions, and avoiding rounding errors if the complex function is implemented as a combination of sub-functions. The disadvantage is that the lookup requires the use of a read-only memory in hardware. Due to size limitations on this memory it might not be possible to represent all possible values of a function.

This section discusses the use of lookup tables with the fixed point type. It is assumed that the function lookup of Octave-forge is installed. The easiest way to explain the use of a fixed point lookup table is to discuss an example. Consider a fixed point value in the range -pi:pi, and we wish to represent the sine function in this range. The creation of the lookup table can then be performed as follows.

     octave:1> is = 2; ds = 6;
     octave:2> x = [-3.125:0.125:3.125];  % 3.125 ~ pi
     octave:3> y = sin(x);
     octave:4> table_float = create_lookup_table(x, y);
     octave:5> table_fixed = create_lookup_table(fixed(is,ds,x),
     >                          fixed(is,ds,y));

A real implementation of this function in hardware might use to the symmetry of the sine function to only require the lookup table for [0:pi/2] to be stored. However, for simulation there is little reason to introduce this complication.

To evaluate the value of the function use the lookup table created by create_lookup_table, the function lookup_table is then used. This function can either be used to give the closest evalued value below the desired value, or it can be used to interpolate the table as might be done in hardware. For example

     octave:6> x0 = [-pi:0.01:pi];
     octave:7> y0 = sin(x);
     octave:8> y1 = lookup_table(table_float, x0, "linear");
     octave:9> y2 = lookup_table(table_fixed, fixed(is,ds,x0), "linear");

Known Problems
==============

Before reporting a bug compare it to this list of known problems

Concatenation
     For versions of Octave prior to 2.1.58, the concatenation of fixed point objects returns a Matrix type. That is [fixed(7,2,[1, 2]), fixed(7,2,3)] returns a matrix when it should return another fixed point matrix. This problem is due to the implementation of matrix concatenation in earlier versions of Octave being hard-coded for the basic types it knows rather than being expandable.

     The workaround is to explicitly convert the returned value back to the correct fixed point object. For instance

          octave:1> a = fixed(7,2,[1,2]);
          octave:2> b = fixed(7,2,3);
          octave:3> c = fixed([a.int, b.int], [a.dec, b.dec],
          >           [a.x, b.x]);

     Alternatively, use the supplied function concat that explicitly performs the above above, but can also be used for normal matrices.

     Since Octave version 2.1.58, [fixed(7,2,[1,2]),fixed(7,2,3)] returns another fixed point object as expected.

Saving fixed point objects

     Saving of fixed point variables is only implemented in versions of Octave later than 2.1.53. If you are using a recent version of Octave then saving a fixed point variable is as simple as

          octave:2> save a.mat a

     where A is a fixed point variable. To reload the variable within octave, the fixed point types must be installed prior to a call to load. That is

          octave:1> dummy = fixed(1,1);
          octave:2> load a.mat

     With versions of octave later than 2.1.53, fixed point variables can be saved in the octave binary and ascii formats, as well as the HDF5 format. If you are using an earlier version of octave, you can not directly save a fixed point variable. You can however save the information it contains and reconstruct the data afterwards by doing something like

          octave:2> x = a.x; is = a.int; ds = a.dec;
          octave:3> save a.mat x is ds;

     where A is a fixed point object.

Some functions and operators return very poor results
     Please read the previous section. Also if the problem manifests when using complex arguments, try to understand your compilers constructor of complex operators and functions from the base fixed point operators and functions. The relevant file for the gcc 3.x versions of the compiler can be found in /usr/include/g++-v3/bits/std_complex.h.

Function foo returns fixed point types while bar
     does not?  If the existing functions, written as m-files, respect the use (or rather non-use) of the concatentaion operator, then these functions will operate correctly. However, many functions don't and thus will return a floating type for a fixed point input, when run on versions of Octave earlier than 2.1.58. All functions should be checked by the user for their correct operation before using them.

     Additionally, existing oct-files will not operate correctly with fixed point inputs, as they are not aware of the fixed point type and will just extract the floating point value to operate on.

     A third class of function are the inbuilt functions like any, size, etc. As the fixed point type includes the underlying functions for these to work correctly, they give the correct result even though there is no corresponding fixed point specific version of these functions.

Why is my code so slow when using fixed point
     This is due to several reasons, firstly the normal functions in octave use optimized libraries to accelerate their operation. This is not possible when using fixed point.

     Also there is no fixed point type native to the machines Octave runs on. This naturally makes the fixed point type slow, due to the fact that the fixed point operators check for overflows, etc at all steps in the operation and act accordingly. This is particularly true in the case of matrix multiplication where each multiplication and addition can be subject to overflows. Thus

          octave:1> x = randn(100,100);
          octave:2> y0 = fixed(7,6,x*x);
          octave:3> y1 = fixed(7,6,x)*fixed(7,6,x);

     does not give equivalent operations for Y0 and Y1. With all this additionally checking, you can not expect your code to run as fast when using the fixed point type.

When running under cygwin I get a dlopen error.

     The build under cygwin is slightly different, in that most of the fixed point functions are compiled as a shared library that is linked to the main oct-file. This is to allow other oct-files to use the fixed-point type which is not possible under cygwin otherwise, since compilation under cygwin requires that all symbols are resolved at compile time.

     If the shared libraries are not installed somewhere that can be found when running octave, then you will get an error like

          octave:1> a = fixed(7,2,1)
          error: dlopen: Win32 error 126
          error: `fixed' undefined near line 1 column 5
          error: evaluating assignment expression near line 1, column 3

There are two files liboctave_fixed.dll and liboctave_fixed.dll.a that must be installed. Typically, these should be installed in the same directory that you can liboctave.dll and liboctave.dll.a respectively. If you use the same --prefix option to configure both octave and octave-forge then this should happen automatically.

Using the fixed-point type in C++ and oct-files
***********************************************

Octave supplies a matrix template library to create matrix and vector objects from basic types. All of the properties of these Octave classes will not be described here. However the base classes and the particularly of the classes created using the Octave matrix templates will be discussed.

There are two basic fixed point types: FixedPoint and FixedPointComplex representing the fixed point representation of real and complex numbers respectively. The Octave matrix templates are used to created the classes FixedMatrix, FixedRowVector and FixedColumnVector from the base class FixedPoint. Similar the complex fixed point types FixedComplexMatrix, FixedComplexRowVector and FixedComplexColumnVectors are constructed from the base class FixedPointComplex

This section discusses the definitions of the base classes, their extension with the Octave matrix templates, the upper level Octave classes and the use of all of these when writing oct-files.

The FixedPoint Base Class
=========================

FixedPoint Constructors
-----------------------

FixedPoint::FixedPoint ()
     Create a fixed point object with only a sign bit

FixedPoint::FixedPoint (unsigned int is, unsigned int ds)
     Create a fixed point object with is bits for the integer part and ds bits for the decimal part. The fixed point object will be initialized to be zero

FixedPoint::FixedPoint (unsigned int is, unsigned int ds, FixedPoint &x)
     Create a fixed point object with is bits for the integer part and ds bits for the decimal part, loaded with the fixed point value x. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint::FixedPoint (unsigned int is, unsigned int ds, const double x)
     Create a fixed point object with is bits for the integer part and ds bits for the decimal part, loaded with the value x. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint::FixedPoint (unsigned int is, unsigned int ds, unsigned int i, unsigned int d)
     Create a fixed point object with is bits for the integer part and ds bits for the decimal part, loading the integer part with i and the decimal part with d. It should be noted that i and d are both unsigned and are the strict representation of the bits of the fixed point value.

FixedPoint::FixedPoint (const int x)
     Create a fixed point object with the minimum number of bits for the integer part is needed to represent x. If is is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint::FixedPoint (const double x)
     Create a fixed point object with the minimum number of bits for the integer part is needed to represent the integer part of x. If is is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint::FixedPoint (const FixedPoint &x)
     Create a copy of the fixed point object x

FixedPoint Specific Methods
---------------------------

double FixedPoint::fixedpoint()
     Method to create a double from the current fixed point object

double fixedpoint (const FixedPoint &x)
     Create a double from the fixed point object x

int FixedPoint::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the current fixed point object is zero.

int sign (FixedPoint &x)
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point object x is zero.

char FixedPoint::signbit ()
     Return the sign bit of the current fixed point number (0 for positive number, 1 for negative number).

char signbit (FixedPoint &x)
     Return the sign bit of the fixed point number x (0 for positive number, 1 for negative number).

int FixedPoint::getintsize ()
     Return the number of bit is used to represent the integer part of the current fixed point object.

int getintsize (FixedPoint &x)
     Return the number of bit is used to represent the integer part of the fixed point object x.

int FixedPoint::getdecsize ()
     Return the number of bit ds used to represent the decimal part of the current fixed point object.

int getdecsize (FixedPoint &x)
     Return the number of bit ds used to represent the decimal part of the fixed point object x.

unsigned int FixedPoint::getnumber ()
     Return the integer representation of the fixed point value of the current fixed point object.

unsigned int getnumber (FixedPoint &x)
     Return the integer representation of the fixed point value of the fixed point object x.

FixedPoint FixedPoint::chintsize (const int n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is changed to n. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint FixedPoint::chdecsize (const int n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds changed to n. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint FixedPoint::incintsize (const int n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint FixedPoint::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint FixedPoint::incdecsize (const int n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint FixedPoint::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint Operators
--------------------

FixedPoint operator +
     Unary + of a fixed point object

FixedPoint operator -
     Unary - of a fixed point object

FixedPoint operator !
     Unary ! operator of the fixedpoint object, with the the sign bit. This is not the same operator as - and is not the same operator as the octave ! operator.

FixedPoint operator ++
     Unary increment operator (pre and postfix). Uses the smallest representable value to increment (ie 2 ^ (- ds) )

FixedPoint operator --
     Unary decrement operator (pre and postfix). Uses the smallest representable value to decrement (ie 2 ^ (- ds) )

FixedPoint operator = (const FixedPoint &x)
     Assignment operators. Copies fixed point object x

FixedPoint operator += (const FixedPoint &x)
FixedPoint operator -= (const FixedPoint &x)
FixedPoint operator *= (const FixedPoint &x)
FixedPoint operator /= (const FixedPoint &x)
     Assignment operators, working on both the input and output objects. The output object's fixed point representation is promoted such that the largest values of is and ds are taken from the input and output objects. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPoint operator <<= (const int s)
FixedPoint operator << (const FixedPoint &x, const int s)
     Perform a left-shift of a fixed point object. This is equivalent to a multiplication by a power of 2. The sign-bit is preserved.  This differs from the rshift function discussed below in the is and ds are unchanged.

FixedPoint operator >>= (const int s)
FixedPoint operator >> (const FixedPoint &x, const int s)
     Perform a right-shift of the fixed point object. This is  equivalent to a division by a power of 2. Note that the sign-bit is preserved. This differs from the rshift function discussed below in the is and ds are unchanged.

FixedPoint operator + (const FixedPoint &x, const FixedPoint &y)
FixedPoint operator - (const FixedPoint &x, const FixedPoint &y)
FixedPoint operator * (const FixedPoint &x, const FixedPoint &y)
FixedPoint operator / (const FixedPoint &x, const FixedPoint &y)
     Two argument operators. The output objects fixed point representation is promoted such that the largest values of is and ds are taken from the two arguments. If the result of this operation causes is + ds to be greater than  sizeof(int)*8 - 2, the error handler is called.

bool operator == (const FixedPoint &x, const FixedPoint &y)
bool operator != (const FixedPoint &x, const FixedPoint &y)
bool operator < (const FixedPoint &x, const FixedPoint &y)
bool operator <= (const FixedPoint &x, const FixedPoint &y)
bool operator > (const FixedPoint &x, const FixedPoint &y)
bool operator >= (const FixedPoint &x, const FixedPoint &y)
     Fixed point comparison operators. The fixed point object x and y can have different representations (values of is and ds).

std::istream &operator >> (std::istream &s, FixedPoint &x)
     Read a fixed point object from s stream and store it into x keeping the fixed point representation in x. If the value read is not a fixed  point object, the error handler is invoked.

std::ostream &operator << (std::ostream &s, const FixedPoint &x)
     Send into the stream s, a formatted fixed point value x

FixedPoint Functions
--------------------

FixedPoint rshift (const FixedPoint &x, int s)
     Do a right shift of s bits of a fixed precision number (equivalent to a division by a power of 2). The representation of the fixed point object is adjusted to suit the new fixed point object (i.e. ds++ and is = is == 0 ? 0 : is-1)

FixedPoint lshift (const FixedPoint &x, int s)
     Do a left shift of s bits of a fixed precision number (equivalent to a multiplication by a power of 2). The representation of the fixed point object is adjusted to suit the new fixed point object (i.e. is++ and ds = ds == 0 ? 0 : ds-1)

FixedPoint abs (const FixedPoint &x)
     Returns the modulus of x

FixedPoint cos (const FixedPoint &x)
     Returns the cosine of x

FixedPoint cosh (const FixedPoint &x)
     Returns the hyperbolic cosine of x

FixedPoint sin (const FixedPoint &x)
     Returns the sine of x

FixedPoint sinh (const FixedPoint &x)
     Returns the hyperbolic sine of x

FixedPoint tan (const FixedPoint &x)
     Returns the tangent of x

FixedPoint tanh (const FixedPoint &x)
     Returns the hyperbolic tangent of x

FixedPoint sqrt (const FixedPoint &x)
     Returns the square root of x

FixedPoint pow (const FixedPoint &x, int y)
FixedPoint pow (const FixedPoint &x, double y)
FixedPoint pow (const FixedPoint &x, const FixedPoint &y)
     Returns the x raised to the power y

FixedPoint exp (const FixedPoint &x)
     Returns the exponential of x

FixedPoint log (const FixedPoint &x)
     Returns the logarithm of x

FixedPoint log10 (const FixedPoint &x)
     Returns the base 10 logarithm of x

FixedPoint atan2 (const FixedPoint &y, const FixedPoint &x)
     Returns the arc tangent of x and y

FixedPoint floor (const FixedPoint &x)
     Returns the rounded value of x downwards to the nearest integer

FixedPoint ceil (const FixedPoint &x)
     Returns the rounded value of x upwards to the nearest integer

FixedPoint rint (const FixedPoint &x)
     Returns the rounded value of x to the nearest integer

FixedPoint round (const FixedPoint &x)
     Returns the rounded value of x to the nearest integer. The difference with rint is that 0.5 is rounded to 1 and not 0. This conforms to the behavior of the octave round function.

std::string getbitstring (const FixedPoint &x)
     Return a string containing the bits of x

The FixedPointComplex Base Class
================================

The FixedPointComplex class is derived using the C++ compilers inbuilt complex class and is instantiated as std::complex<FixedPoint>. Therefore the exact behavior of the complex fixed point type is determined by the complex class used by the C++ compiler. The user is advised to understand their C++ compilers implementation of the complex functions that they use, and particularly the effects that they will have on the precision of fixed point operations.

FixedPointComplex Constructors
------------------------------

FixedPointComplex::FixedPointComplex ()
     Create a complex fixed point object with only a sign bit

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part. The fixed point object will be initialized to zero.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, FixedPoint &x)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value x in the real part and zero in the imaginary. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, FixedPoint &r, FixedPoint &i)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value r in the real part and i the imaginary part. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, FixedPointComplex &x)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the complex fixed point value x. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, const double x)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value x in the real part and zero in the imaginary. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, const double r, const double i)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value r in the real part and i in the imaginary part. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, const Complex c)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value c in the real and imaginary parts. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (unsigned int is, unsigned int ds, const Complex a, const Complex b)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value a in the integer parts of the of the value and b in the decimal part. It should be noted that a and b are both unsigned and are the strict representation of the bits of the fixed point value and considered as integers. If is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (const Complex& is, const Complex& ds)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with zero in the real and imaginary parts. The real part of is is used for the real part of the complex fixed point object, while the imaginary part of is is used for the imaginary part. If either the sum of the real or imaginary parts of is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (const Complex& is, const Complex& ds, const Complex& c)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the complex fixed point value c in the real and imaginary parts. The real part of is is used for the real part of the complex fixed point object, while the imaginary part of is is used for the imaginary part. If either the sum of the real or imaginary parts of is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (const Complex& is, const Complex& ds, const FixedPointComplex& c)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the complex fixed point value c in the real and imaginary parts. The real part of is is used for the real part of the complex fixed point object, while the imaginary part of is is used for the imaginary part. If either the sum of the real or imaginary parts of is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (const Complex& is, const Complex& ds, const Complex& a, const Complex& b)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the fixed point value a in the integer parts of the of the value and b in the decimal part. It should be noted that a and b are both unsigned and are the strict representation of the bits of the fixed point value and considered as integers. If either the sum of the real or imaginary parts of is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (const std::complex<FixedPoint> &c)
     Create a complex fixed point object with the minimum number of bits for the integer part is needed to represent the real and imaginary integer parts of x. If is is greater than sizeof(int)*8 - 2, the error handler is called. The real and imaginary parts are treated separately.

FixedPointComplex::FixedPointComplex (const FixedPointComplex &x)
     Create a copy of the complex fixed point object x

FixedPointComplex::FixedPointComplex (const FixedPoint &x)
     Create a copy of the fixed point object x, into a complex fixed point object leaving the imaginary part at zero.

FixedPointComplex::FixedPointComplex (const FixedPoint &r, const FixedPoint &i)
     Create a copy of the fixed point objects r and i, into a the real and imaginary parts of a complex fixed point object respectively

FixedPointComplex::FixedPointComplex (const int x)
     Create a fixed point object with the minimum number of bits for the integer part is needed to represent x. If is is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex::FixedPointComplex (const double x)
     Create a fixed point object with the minimum number of bits for the integer part is needed to represent the integer part of x. If is is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex (const Complex& is, const Complex& ds, const double& d)
     Create a complex fixed point object with is bits for the integer part and ds bits for the decimal part of both real and imaginary parts, loaded with the double value d in the real and zero in the imaginary parts. The real part of is is used for the real part of the complex fixed point object, while the imaginary part of is is used for the imaginary part. If either the sum of the real or imaginary parts of is + ds is greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex Specific Methods
----------------------------------

Complex FixedPointComplex::fixedpoint()
     Method to create a Complex from the current fixed point object

Complex fixedpoint (const FixedPointComplex &x)
     Create a Complex from the fixed point object x

Complex FixedPointComplex::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the current fixed point object is zero. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex sign (FixedPointComplex &x)
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point object x is zero. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex FixedPointComplex::getintsize ()
     Return the number of bit is used to represent the integer part of the current fixed point object. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex getintsize (FixedPointComplex &x)
     Return the number of bit is used to represent the integer part of the fixed point object x. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex FixedPointComplex::getdecsize ()
     Return the number of bit ds used to represent the decimal part of the current fixed point object.  Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex getdecsize (FixedPointComplex &x)
     Return the number of bit ds used to represent the decimal part of the fixed point object x. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex FixedPointComplex::getnumber ()
     Return the integer representation of the fixed point value of the current fixed point object. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

Complex getnumber (FixedPointComplex &x)
     Return the integer representation of the fixed point value of the fixed point object x. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex FixedPointComplex::chintsize (const Complex n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is changed to n. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex FixedPointComplex::chdecsize (const Complex n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds changed to n. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex FixedPointComplex::incintsize (const Complex n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex FixedPointComplex::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex FixedPointComplex::incdecsize (const Complex n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex FixedPointComplex::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called. Real and imaginary parts treated separately and returned in the real and imaginary parts of the return object.

FixedPointComplex Operators
---------------------------

FixedPointComplex operator +
     Unary + of a complex fixed point object

FixedPointComplex operator -
     Unary - of a complex fixed point object

FixedPointComplex operator = (const FixedPointComplex &x)
     Assignment operators. Copies complex fixed point object x

FixedPointComplex operator += (const FixedPointComplex &x)
FixedPointComplex operator -= (const FixedPointComplex &x)
FixedPointComplex operator *= (const FixedPointComplex &x)
FixedPointComplex operator /= (const FixedPointComplex &x)
     Assignment operators, working on both the input and output objects. The output object's fixed point representation is promoted such that the largest values of is and ds are taken from the input and output objects. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedPointComplex operator + (const FixedPointComplex &x, const FixedPointComplex &y)
FixedPointComplex operator - (const FixedPointComplex &x, const FixedPointComplex &y)
FixedPointComplex operator * (const FixedPointComplex &x, const FixedPointComplex &y)
FixedPointComplex operator / (const FixedPointComplex &x, const FixedPointComplex &y)
     Two argument operators. The output objects complex fixed point representation is promoted such that the largest values of is and ds are taken from the two arguments. If the result of this operation causes is + ds to be greater than  sizeof(int)*8 - 2, the error handler is called.

bool operator == (const FixedPointComplex &x, const FixedPointComplex &y)
bool operator != (const FixedPointComplex &x, const FixedPointComplex &y)
     Complex fixed point comparison operators. The complex fixed point object x and y can have different representations (values of is and ds).

std::istream &operator >> (std::istream &s, FixedPointComplex &x)
     Read a fixed point object from s stream and store it into x keeping the fixed point representation in x. If the value read is not a fixed  point object, the error handler is invoked.

std::ostream &operator << (std::ostream &s, const FixedPointComplex &x)
     Send into the stream s, a formatted fixed point value x

FixedPointComplex Functions
---------------------------

FixedPoint abs (const FixedPointComplex &x)
     Returns the modulus of x

FixedPoint norm (const FixedPointComplex &x)
     Returns the squared magnitude of x

FixedPoint arg (const FixedPointComplex &x)
     Returns the arc-tangent of x

FixedPointComplex std::polar (const FixedPoint &r, const FixedPoint &p)
     Convert from polar fixed point to a complex fixed point object

FixedPoint real (const FixedPointComplex &x)
     Returns the real part of x

FixedPoint imag (const FixedPointComplex &x)
     Returns the imaginary part of x

FixedPointComplex conj (const FixedPointComplex &x)
     Returns the conjugate of x

FixedPointComplex cos (const FixedPointComplex &x)
     Returns the transcendental cosine of x

FixedPointComplex cosh (const FixedPointComplex &x)
     Returns the transcendental hyperbolic cosine of x

FixedPointComplex sin (const FixedPointComplex &x)
     Returns the transcendental sine of x

FixedPointComplex sinh (const FixedPointComplex &x)
     Returns the transcendental hyperbolic sine of x

FixedPointComplex tan (const FixedPointComplex &x)
     Returns the transcendental tangent of x

FixedPointComplex tanh (const FixedPointComplex &x)
     Returns the transcendental hyperbolic tangent of x

FixedPointComplex sqrt (const FixedPointComplex &x)
     Returns the square root of x

FixedPointComplex pow (const FixedPointComplex &x, int y)
FixedPointComplex pow (const FixedPointComplex &x, const FixedPoint &y)
FixedPointComplex pow (const FixedPointComplex &x, const FixedPointComplex &y)
FixedPointComplex pow (const FixedPoint &x, const FixedPointComplex &y)
     Returns the x raised to the power y. Be careful of precision errors associated with the implementation of this function as a complex type

FixedPointComplex exp (const FixedPointComplex &x)
     Returns the exponential of x.  Be careful of precision errors associated with the implementation of this function as a complex type

FixedPointComplex log (const FixedPointComplex &x)
     Returns the transcendental logarithm of x.  Be careful of precision errors associated with the implementation of this function as a complex type

FixedPointComplex log10 (const FixedPointComplex &x)
     Returns the transcendental base 10 logarithm of x. Be careful of precision errors associated with the implementation of this function as a complex type

FixedPointComplex floor (const FixedPointComplex &x)
     Returns the rounded value of x downwards to the nearest integer, treating the real and imaginary parts separately

FixedPointComplex ceil (const FixedPointComplex &x)
     Returns the rounded value of x upwards to the nearest integer, treating the real and imaginary parts separately

FixedPointComplex rint (const FixedPointComplex &x)
     Returns the rounded value of x to the nearest integer, treating the real and imaginary parts separately

FixedPointComplex round (const FixedPointComplex &x)
     Returns the rounded value of x to the nearest integer. The difference with rint is that 0.5 is rounded to 1 and not 0. This conforms to the behavior of the octave round function. Treats the real and imaginary parts separately

The Derived Classes using the Octave Template Classes
=====================================================

It is not the purpose of this section to discuss the use of the Octave template classes, but rather only the additions to the fixed point classes that are based on these. For instance the basic constructors and operations that are available in the normal floating point Octave classes are available within the fixed point classes.

The notable exceptions are operations involving matrix decompositions, including inversion, left division, etc. The reason for this is that the precision of these operators and functions will be highly implementation dependent. As additional these operators and functions are used rarely with a fixed point type, there is no point in implementing these operators and function within the fixed point classes.

In addition the the functions and operators previously described for the FixedPoint and the FixedPointComplex types are all available, in the same from as previously. So these functions are not documented below. Only the constructors and methods that vary from the previously described versions are described.

To fully understand these classes, the user is advised to examine the header files fixedMatrix.h, fixedRowVector.h and fixedColVector.h for the real fixed point objects and fixedCMatrix.h, fixedCRowVector.h and fixedCColVector.h for the complex fixed point objects. In addition the files MArray.h and MArray2.h from Octave should also be examined.

FixedMatrix class
-----------------

FixedMatrix::FixedMatrix (const MArray2<int> &is, const MArray2<int> &ds)
FixedMatrix::FixedMatrix (const Matrix &is, const Matrix &ds)
     Create a fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedMatrix::FixedMatrix (unsigned int is, unsigned int ds, const FixedMatrix& a)
FixedMatrix::FixedMatrix (const MArray2<int> &is, const MArray2<int> &ds, const FixedMatrix& a)
FixedMatrix::FixedMatrix (const Matrix &is, const Matrix &ds, const FixedMatrix& a)
     Create a fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point matrix a

FixedMatrix::FixedMatrix (unsigned int is, unsigned int ds, const Matrix& a)
FixedMatrix::FixedMatrix (const MArray2<int> &is, const MArray2<int> &ds, const Matrix& a)
FixedMatrix::FixedMatrix (const Matrix &is, const Matrix &ds, const Matrix& a)
     Create a fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the matrix a

FixedMatrix::FixedMatrix (unsigned int is, unsigned int ds, const Matrix& a, const Matrix& b)
FixedMatrix::FixedMatrix (const MArray2<int> &is, const MArray2<int> &ds, const Matrix& a, const Matrix& b)
FixedMatrix::FixedMatrix (const Matrix &is, const Matrix &ds, const Matrix& a, const Matrix& b)
     Create a fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will have the integer parts loaded by the matrix a and the decimal part by the matrix b. It should be noted that a and b are both considered as unsigned integers and are the strict  representation of the bits of the fixed point value.

Matrix FixedMatrix::fixedpoint ()
     Method to create a Matrix from a fixed point matrix x

Matrix fixedpoint (const FixedMatrix &x)
     Create a Matrix from a fixed point matrix x

Matrix FixedMatrix::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point element is zero, for every element of the current fixed point object.

Matrix sign (const FixedMatrix &x)
     Return -1 for negative numbers, 1 for positive and 0 if zero, for every element of the fixed point object x.

Matrix FixedMatrix::signbit ()
     Return the sign bit for every element of the current fixed point matrix (0 for positive number, 1 for negative number).

Matrix signbit (const FixedMatrix &x)
     Return the sign bit for every element of the fixed point matrix x (0 for positive number, 1 for negative number).

Matrix FixedMatrix::getintsize ()
     Return the number of bit is used to represent the integer part of each element of the current fixed point object.

Matrix getintsize (const FixedMatrix &x)
     Return the number of bit is used to represent the integer part of each element of the fixed point object x.

Matrix FixedMatrix::getdecsize ()
     Return the number of bit ds used to represent the decimal part of each element of the current fixed point object.

Matrix getdecsize (const FixedMatrix &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

Matrix FixedMatrix::getnumber ()
     Return the integer representation of the fixed point value of the each eleement of the current fixed point object.

Matrix getnumber (const FixedMatrix &x)
     Return the integer representation of the fixed point value of the each eleement of the fixed point object x.

FixedMatrix FixedMatrix::chintsize (const Matrix &n)
FixedMatrix FixedMatrix::chintsize (const double n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the integer part is of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedMatrix FixedMatrix::chdecsize (const double n)
FixedMatrix FixedMatrix::chdecsize (const Matrix &n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the decimal part ds of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedMatrix FixedMatrix::incintsize (const double n)
FixedMatrix FixedMatrix::incintsize (const Matrix &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedMatrix FixedMatrix::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedMatrix FixedMatrix::incdecsize (const double n)
FixedMatrix FixedMatrix::incdecsize (const Matrix &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedMatrix FixedMatrix::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedRowVector class
--------------------

FixedRowVector::FixedRowVector (const MArray<int> &is, const MArray<int> &ds)
FixedRowVector::FixedRowVector (const RowVector &is, const RowVector &ds)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedRowVector::FixedRowVector (unsigned int is, unsigned int ds, const FixedRowVector& a)
FixedRowVector::FixedRowVector (const MArray<int> &is, const MArray<int> &ds, const FixedRowVector& a)
FixedRowVector::FixedRowVector (const RowVector &is, const RowVector &ds, const FixedRowVector& a)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point row rector a

FixedRowVector::FixedRowVector (unsigned int is, unsigned int ds, const RowVector& a)
FixedRowVector::FixedRowVector (const MArray<int> &is, const MArray<int> &ds, const RowVector& a)
FixedRowVector::FixedRowVector (const RowVector &is, const RowVector &ds, const RowVector& a)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the row vector a

FixedRowVector::FixedRowVector (unsigned int is, unsigned int ds, const RowVector& a, const RowVector& b)
FixedRowVector::FixedRowVector (const MArray<int> &is, const MArray<int> &ds, const RowVector& a, const RowVector& b)
FixedRowVector::FixedRowVector (const RowVector &is, const RowVector &ds, const RowVector& a, const RowVector& b)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will have the integer parts loaded by the row vector a and the decimal part by the row vector b. It should be noted that a and b are both considered as unsigned integers and are the strict  representation of the bits of the fixed point value.

RowVector FixedRowVector::fixedpoint ()
     Method to create a RowVector from a fixed point row vector x

RowVector fixedpoint (const FixedRowVector &x)
     Create a RowVector from a fixed point row vector x

RowVector FixedRowVector::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point element is zero, for every element of the current fixed point object.

RowVector sign (const FixedRowVector &x)
     Return -1 for negative numbers, 1 for positive and 0 if zero, for every element of the fixed point object x.

RowVector FixedRowVector::signbit ()
     Return the sign bit for every element of the current fixed point row vector (0 for positive number, 1 for negative number).

RowVector signbit (const FixedRowVector &x)
     Return the sign bit for every element of the fixed point row vector x (0 for positive number, 1 for negative number).

RowVector FixedRowVector::getintsize ()
     Return the number of bit is used to represent the integer part of each element of the current fixed point object.

RowVector getintsize (const FixedRowVector &x)
     Return the number of bit is used to represent the integer part of each element of the fixed point object x.

RowVector FixedRowVector::getdecsize ()
     Return the number of bit ds used to represent the decimal part of each element of the current fixed point object.

RowVector getdecsize (const FixedRowVector &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

RowVector FixedRowVector::getnumber ()
     Return the integer representation of the fixed point value of the each eleement of the current fixed point object.

RowVector getnumber (const FixedRowVector &x)
     Return the integer representation of the fixed point value of the each eleement of the fixed point object x.

FixedRowVector FixedRowVector::chintsize (const RowVector n)
FixedRowVector FixedRowVector::chintsize (const double n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the integer part is of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedRowVector FixedRowVector::chdecsize (const double n)
FixedRowVector FixedRowVector::chdecsize (const RowVector n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the decimal part ds of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedRowVector FixedRowVector::incintsize (const double n)
FixedRowVector FixedRowVector::incintsize (const RowVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedRowVector FixedRowVector::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedRowVector FixedRowVector::incdecsize (const double n)
FixedRowVector FixedRowVector::incdecsize (const RowVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedRowVector FixedRowVector::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedColumnVector class
-----------------------

FixedColumnVector::FixedColumnVector (const MArray<int> &is, const MArray<int> &ds)
FixedColumnVector::FixedColumnVector (const ColumnVector &is, const ColumnVector &ds)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedColumnVector::FixedColumnVector (unsigned int is, unsigned int ds, const FixedColumnVector& a)
FixedColumnVector::FixedColumnVector (const MArray<int> &is, const MArray<int> &ds, const FixedColumnVector& a)
FixedColumnVector::FixedColumnVector (const ColumnVector &is, const ColumnVector &ds, const FixedColumnVector& a)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point column vector a

FixedColumnVector::FixedColumnVector (unsigned int is, unsigned int ds, const ColumnVector& a)
FixedColumnVector::FixedColumnVector (const MArray<int> &is, const MArray<int> &ds, const ColumnVector& a)
FixedColumnVector::FixedColumnVector (const ColumnVector &is, const ColumnVector &ds, const ColumnVector& a)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the column vector a

FixedColumnVector::FixedColumnVector (unsigned int is, unsigned int ds, const ColumnVector& a, const ColumnVector& b)
FixedColumnVector::FixedColumnVector (const MArray<int> &is, const MArray<int> &ds, const ColumnVector& a, const ColumnVector& b)
FixedColumnVector::FixedColumnVector (const ColumnVector &is, const ColumnVector &ds, const ColumnVector& a, const ColumnVector& b)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will have the integer parts loaded by the column vector a and the decimal part by the column vector b. It should be noted that a and b are both considered  as unsigned integers and are the strict  representation of the bits of the fixed point value.

ColumnVector FixedColumnVector::fixedpoint ()
     Method to create a ColumnVector from a fixed point column vector x

ColumnVector fixedpoint (const FixedColumnVector &x)
     Create a ColumnVector from a fixed point column vector x

ColumnVector FixedColumnVector::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point element is zero, for every element of the current fixed point object.

ColumnVector sign (const FixedColumnVector &x)
     Return -1 for negative numbers, 1 for positive and 0 if zero, for every element of the fixed point object x.

ColumnVector FixedColumnVector::signbit ()
     Return the sign bit for every element of the current fixed point column vector (0 for positive number, 1 for negative number).

ColumnVector signbit (const FixedColumnVector &x)
     Return the sign bit for every element of the fixed point column vector x (0 for positive number, 1 for negative number).

ColumnVector FixedColumnVector::getintsize ()
     Return the number of bit is used to represent the integer part of each element of the current fixed point object.

ColumnVector getintsize (const FixedColumnVector &x)
     Return the number of bit is used to represent the integer part of each element of the fixed point object x.

ColumnVector FixedColumnVector::getdecsize ()
     Return the number of bit ds used to represent the decimal part of each element of the current fixed point object.

ColumnVector getdecsize (const FixedColumnVector &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

ColumnVector FixedColumnVector::getnumber ()
     Return the integer representation of the fixed point value of the each eleement of the current fixed point object.

ColumnVector getnumber (const FixedColumnVector &x)
     Return the integer representation of the fixed point value of the each eleement of the fixed point object x.

FixedColumnVector FixedColumnVector::chintsize (const ColumnVector n)
FixedColumnVector FixedColumnVector::chintsize (const double n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the integer part is of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedColumnVector FixedColumnVector::chdecsize (const double n)
FixedColumnVector FixedColumnVector::chdecsize (const ColumnVector n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the decimal part ds of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedColumnVector FixedColumnVector::incintsize (const double n)
FixedColumnVector FixedColumnVector::incintsize (const ColumnVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedColumnVector FixedColumnVector::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedColumnVector FixedColumnVector::incdecsize (const double n)
FixedColumnVector FixedColumnVector::incdecsize (const ColumnVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedColumnVector FixedColumnVector::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexMatrix class
------------------------

FixedComplexMatrix::FixedComplexMatrix (const MArray2<int> &is, const MArray2<int> &ds)
FixedComplexMatrix::FixedComplexMatrix (const Matrix &is, const Matrix &ds)
     Create a complex fixed point matrix with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds)
     Create a complex fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedComplexMatrix::FixedComplexMatrix (unsigned int is, unsigned int ds, const FixedComplexMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (Complex is, Complex ds, const FixedComplexMatrix& a)

FixedComplexMatrix::FixedComplexMatrix (const MArray2<int> &is, const MArray2<int> &ds, const FixedComplexMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (const Matrix &is, const Matrix &ds, const FixedComplexMatrix& a)
     Create a complex fixed point matrix with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex fixed point matrix a

FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const FixedComplexMatrix &x)
FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const FixedMatrix &r, const FixedMatrix &i)
     Create a complex fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex fixed point matrix a, or the real part by r and the imaginary by i.

FixedComplexMatrix::FixedComplexMatrix (unsigned int is, unsigned int ds, const FixedMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (Complex is, Complex ds, const FixedMatrix& a)

FixedComplexMatrix::FixedComplexMatrix (const MArray2<int> &is, const MArray2<int> &ds, const FixedMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (const Matrix &is, const Matrix &ds, const FixedMatrix& a)
     Create a complex fixed point matrix with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point matrix a

FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const FixedMatrix &x)
     Create a complex fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point matrix a.

FixedComplexMatrix::FixedComplexMatrix (unsigned int is, unsigned int ds, const ComplexMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (Complex is, Complex ds, const ComplexMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (const MArray2<int> &is, const MArray2<int> &ds, const ComplexMatrix& a)
FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const ComplexMatrix& a)
     Create a complex fixed point matrix with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex matrix a

FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const ComplexMatrix &x)
FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const Matrix &r, const Matrix &i)
     Create a complex fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex matrix a, or the real part by r and the imaginary by i.

FixedComplexMatrix::FixedComplexMatrix (unsigned int is, unsigned int ds, const Matrix& a)
FixedComplexMatrix::FixedComplexMatrix (Complex is, Complex ds, const Matrix& a)
FixedComplexMatrix::FixedComplexMatrix (const MArray2<int> &is, const MArray2<int> &ds, const Matrix& a)
FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const Matrix& a)
     Create a complex fixed point matrix with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the matrix a

FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const Matrix &x)
     Create a complex fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the matrix a.

FixedComplexMatrix::FixedComplexMatrix (unsigned int is, unsigned int ds, const ComplexMatrix& a, const ComplexMatrix& b)
FixedComplexMatrix::FixedComplexMatrix (Complex is, Complex ds, const ComplexMatrix& a, const ComplexMatrix& b)
FixedComplexMatrix::FixedComplexMatrix (const MArray2<int> &is, const MArray2<int> &ds, const ComplexMatrix& a, const ComplexMatrix& b)

FixedComplexMatrix::FixedComplexMatrix (const Matrix &is, const Matrix &ds, const ComplexMatrix& a, const ComplexMatrix& b)
FixedComplexMatrix::FixedComplexMatrix (const ComplexMatrix &is, const ComplexMatrix &ds, const ComplexMatrix& a, const ComplexMatrix& b)
     Create a fixed point matrix with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds.The fixed point elements themselves will have the integer parts loaded by the complex matrix a and the decimal part by the complex matrix b. It should be noted that a and b are both considered as unsigned complex integers and are the strict representation of the bits of the fixed point value.

ComplexMatrix FixedComplexMatrix::fixedpoint ()
     Method to create a Matrix from a fixed point matrix x

ComplexMatrix fixedpoint (const FixedComplexMatrix &x)
     Create a Matrix from a fixed point matrix x

ComplexMatrix FixedComplexMatrix::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point element is zero, for every element of the current fixed point object.

ComplexMatrix sign (const FixedComplexMatrix &x)
     Return -1 for negative numbers, 1 for positive and 0 if zero, for every element of the fixed point object x.

ComplexMatrix FixedComplexMatrix::getintsize ()
     Return the number of bit is used to represent the integer part of each element of the current fixed point object.

ComplexMatrix getintsize (const FixedComplexMatrix &x)
     Return the number of bit is used to represent the integer part of each element of the fixed point object x.

ComplexMatrix FixedComplexMatrix::getdecsize ()
     Return the number of bit ds used to represent the decimal part of each element of the current fixed point object.

ComplexMatrix getdecsize (const FixedComplexMatrix &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

ComplexMatrix FixedComplexMatrix::getnumber ()
     Return the integer representation of the fixed point value of the each eleement of the current fixed point object.

ComplexMatrix getnumber (const FixedComplexMatrix &x)
     Return the integer representation of the fixed point value of the each eleement of the fixed point object x.

FixedComplexMatrix FixedComplexMatrix::chintsize (const ComplexMatrix &n)
FixedComplexMatrix FixedComplexMatrix::chintsize (const double n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the integer part is of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexMatrix FixedComplexMatrix::chdecsize (const double n)
FixedComplexMatrix FixedComplexMatrix::chdecsize (const ComplexMatrix &n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the decimal part ds of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexMatrix FixedComplexMatrix::incintsize (const double n)
FixedComplexMatrix FixedComplexMatrix::incintsize (const ComplexMatrix &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexMatrix FixedComplexMatrix::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexMatrix FixedComplexMatrix::incdecsize (const double n)
FixedComplexMatrix FixedComplexMatrix::incdecsize (const ComplexMatrix &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexMatrix FixedComplex::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexRowVector class
---------------------------

FixedComplexRowVector::FixedComplexRowVector (const MArray<int> &is, const MArray<int> &ds)
FixedComplexRowVector::FixedComplexRowVector (const RowVector &is, const RowVector &ds)
     Create a complex fixed point row vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds)
     Create a complex fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedComplexRowVector::FixedComplexRowVector (unsigned int is, unsigned int ds, const FixedComplexRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (Complex is, Complex ds, const FixedComplexRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const MArray<int> &is, const MArray<int> &ds, const FixedComplexRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const RowVector &is, const RowVector &ds, const FixedComplexRowVector& a)
     Create a complex fixed point row vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex fixed point row vector a

FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const FixedComplexRowVector &x)
FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const FixedRowVector &r, const FixedRowVector &i)
     Create a complex fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex fixed point row vector a, or the real part by r and the imaginary by i.

FixedComplexRowVector::FixedComplexRowVector (unsigned int is, unsigned int ds, const FixedRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (Complex is, Complex ds, const FixedRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const MArray<int> &is, const MArray<int> &ds, const FixedRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const RowVector &is, const RowVector &ds, const FixedRowVector& a)
     Create a complex fixed point row vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point row vector a

FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const FixedRowVector &x)
     Create a complex fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point row vector a.

FixedComplexRowVector::FixedComplexRowVector (unsigned int is, unsigned int ds, const ComplexRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (Complex is, Complex ds, const ComplexRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const MArray<int> &is, const MArray<int> &ds, const ComplexRowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const ComplexRowVector& a)
     Create a complex fixed point row vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex row vector a

FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const ComplexRowVector &x)
FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const RowVector &r, const RowVector &i)
     Create a complex fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex row vector a, or the real part by r and the imaginary by i.

FixedComplexRowVector::FixedComplexRowVector (unsigned int is, unsigned int ds, const RowVector& a)
FixedComplexRowVector::FixedComplexRowVector (Complex is, Complex ds, const RowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const MArray<int> &is, const MArray<int> &ds, const RowVector& a)
FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const RowVector& a)
     Create a complex fixed point row vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the row vector a

FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const RowVector &x)
     Create a complex fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the row vector a.

FixedComplexRowVector::FixedComplexRowVector (unsigned int is, unsigned int ds, const ComplexRowVector& a, const ComplexRowVector& b)
FixedComplexRowVector::FixedComplexRowVector (Complex is, Complex ds, const ComplexRowVector& a, const ComplexRowVector& b)
FixedComplexRowVector::FixedComplexRowVector (const MArray<int> &is, const MArray<int> &ds, const ComplexRowVector& a, const ComplexRowVector& b)
FixedComplexRowVector::FixedComplexRowVector (const RowVector &is, const RowVector &ds, const ComplexRowVector& a, const ComplexRowVector& b)
FixedComplexRowVector::FixedComplexRowVector (const ComplexRowVector &is, const ComplexRowVector &ds, const ComplexRowVector& a, const ComplexRowVector& b)
     Create a fixed point row vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will have the integer parts loaded by the complex row vector a and the decimal part by the complex row vector b. It should be noted that a and b are both considered as unsigned complex integers and are the strict representation of the bits of the fixed point value.

ComplexRowVector FixedComplexRowVector::fixedpoint ()
     Method to create a RowVector from a fixed point row vector x

ComplexRowVector fixedpoint (const FixedComplexRowVector &x)
     Create a RowVector from a fixed point row vector x

ComplexRowVector FixedComplexRowVector::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point element is zero, for every element of the current fixed point object.

ComplexRowVector sign (const FixedComplexRowVector &x)
     Return -1 for negative numbers, 1 for positive and 0 if zero, for every element of the fixed point object x.

ComplexRowVector FixedComplexRowVector::getintsize ()
     Return the number of bit is used to represent the integer part of each element of the current fixed point object.

ComplexRowVector getintsize (const FixedComplexRowVector &x)
     Return the number of bit is used to represent the integer part of each element of the fixed point object x.

ComplexRowVector FixedComplexRowVector::getdecsize ()
     Return the number of bit ds used to represent the decimal part of each element of the current fixed point object.

ComplexRowVector getdecsize (const FixedComplexRowVector &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

ComplexRowVector getdecsize (const FixedComplexRowVector &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

ComplexRowVector FixedComplexRowVector::getnumber ()
     Return the integer representation of the fixed point value of the each eleement of the current fixed point object.

FixedComplexRowVector FixedComplexRowVector::chintsize (const ComplexRowVector &n)
FixedComplexRowVector FixedComplexRowVector::chintsize (const double n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the integer part is of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexRowVector FixedComplexRowVector::chdecsize (const double n)
FixedComplexRowVector FixedComplexRowVector::chdecsize (const ComplexRowVector &n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the decimal part ds of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexRowVector FixedComplexRowVector::incintsize (const Complex n)
FixedComplexRowVector FixedComplexRowVector::incintsize (const ComplexRowVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexRowVector FixedComplexRowVector::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexRowVector FixedComplexRowVector::incdecsize (const Complex n)
FixedComplexRowVector FixedComplexRowVector::incdecsize (const ComplexRowVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexRowVector FixedComplexRowVector::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexColumnVector class
------------------------------

FixedComplexColumnVector::FixedComplexColumnVector (const MArray<int> &is, const MArray<int> &ds)
FixedComplexColumnVector::FixedComplexColumnVector (const ColumnVector &is, const ColumnVector &ds)
     Create a complex fixed point column vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds)
     Create a complex fixed point column vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to zero.

FixedComplexColumnVector::FixedComplexColumnVector (unsigned int is, unsigned int ds, const FixedComplexColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (Complex is, Complex ds, const FixedComplexColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const MArray<int> &is, const MArray<int> &ds, const FixedComplexColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const ColumnVector &is, const ColumnVector &ds, const FixedComplexColumnVector& a)
     Create a complex fixed point column vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex fixed point column vector a

FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const FixedComplexColumnVector &x)
FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const FixedColumnVector &r, const FixedColumnVector &i)
     Create a complex fixed point column vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex fixed point column vector a, or the real part by r and the imaginary by i.

FixedComplexColumnVector::FixedComplexColumnVector (unsigned int is, unsigned int ds, const FixedColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (Complex is, Complex ds, const FixedColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const MArray<int> &is, const MArray<int> &ds, const FixedColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const ColumnVector &is, const ColumnVector &ds, const FixedColumnVector& a)
     Create a complex fixed point column vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point column vector a

FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const FixedColumnVector &x)
     Create a complex fixed point column vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the fixed point column vector a.

FixedComplexColumnVector::FixedComplexColumnVector (unsigned int is, unsigned int ds, const ComplexColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (Complex is, Complex ds, const ComplexColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const MArray<int> &is, const MArray<int> &ds, const ComplexColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const ComplexColumnVector& a)
     Create a complex fixed point column vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex column vector a

FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const ComplexColumnVector &x)
FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const ColumnVector &r, const ColumnVector &i)
     Create a complex fixed point column vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the complex column vector a, or the real part by r and the imaginary by i.

FixedComplexColumnVector::FixedComplexColumnVector (unsigned int is, unsigned int ds, const ColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (Complex is, Complex ds, const ColumnVector& a)

FixedComplexColumnVector::FixedComplexColumnVector (const MArray<int> &is, const MArray<int> &ds, const ColumnVector& a)
FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const ColumnVector& a)
     Create a complex fixed point column vector with the number of bits in the integer part of the real and imaginary part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the column vector a

FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const ColumnVector &x)
     Create a complex fixed point column vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will be initialized to the column vector a.

FixedComplexColumnVector::FixedComplexColumnVector (unsigned int is, unsigned int ds, const ComplexColumnVector& a, const ComplexColumnVector& b)
FixedComplexColumnVector::FixedComplexColumnVector (Complex is, Complex ds, const ComplexColumnVector& a, const ComplexColumnVector& b)
FixedComplexColumnVector::FixedComplexColumnVector (const MArray<int> &is, const MArray<int> &ds, const ComplexColumnVector& a, const ComplexColumnVector& b)
FixedComplexColumnVector::FixedComplexColumnVector (const ColumnVector &is, const ColumnVector &ds, const ComplexColumnVector& a, const ComplexColumnVector& b)
FixedComplexColumnVector::FixedComplexColumnVector (const ComplexColumnVector &is, const ComplexColumnVector &ds, const ComplexColumnVector& a, const ComplexColumnVector& b)
     Create a fixed point column vector with the number of bits in the integer part of each element represented by is and the number in the decimal part by ds. The fixed point elements themselves will have the integer parts loaded by the complex column vector a and the decimal part by the compelx column vector b. It should be noted that a and b are both considered  as unsigned compelx integers and are the strict representation of the bits of the fixed point value.

ComplexColumnVector FixedComplexColumnVector::fixedpoint ()
     Method to create a ColumnVector from a fixed point column vector x

ComplexColumnVector fixedpoint (const FixedComplexColumnVector &x)
     Create a ColumnVector from a fixed point column vector x

ComplexColumnVector FixedComplexColumnVector::sign ()
     Return -1 for negative numbers, 1 for positive and 0 if the fixed point element is zero, for every element of the current fixed point object.

ComplexColumnVector sign (const FixedComplexColumnVector &x)
     Return -1 for negative numbers, 1 for positive and 0 if zero, for every element of the fixed point object x.

ComplexColumnVector FixedComplexColumnVector::getintsize ()
     Return the number of bit is used to represent the integer part of each element of the current fixed point object.

ComplexColumnVector getintsize (const FixedComplexColumnVector &x)
     Return the number of bit is used to represent the integer part of each element of the fixed point object x.

ComplexColumnVector FixedComplexColumnVector::getdecsize ()
     Return the number of bit ds used to represent the decimal part of each element of the current fixed point object.

ComplexColumnVector getdecsize (const FixedComplexColumnVector &x)
     Return the number of bit ds used to represent the decimal part of each element of the fixed point object x.

ComplexColumnVector FixedComplexColumnVector::getnumber ()
     Return the integer representation of the fixed point value of the each eleement of the current fixed point object.

ComplexColumnVector getnumber (const FixedComplexColumnVector &x)
     Return the integer representation of the fixed point value of the each eleement of the fixed point object x.

FixedComplexColumnVector FixedComplexColumnVector::chintsize (const ComplexColumnVector &n)
FixedComplexColumnVector FixedComplexColumnVector::chintsize (const double n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the integer part is of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexColumnVector FixedComplexColumnVector::chdecsize (const double n)
FixedComplexColumnVector FixedComplexColumnVector::chdecsize (const ComplexColumnVector &n)
     Return a fixed point object equivalent to the current fixed point object but with the number of bits representing the decimal part ds of every element changed to n. If the result of this operation causes any element of is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexColumnVector FixedComplexColumnVector::incintsize (const double n)
FixedComplexColumnVector FixedComplexColumnVector::incintsize (const ComplexColumnVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by n. If n is negative, then is is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexColumnVector FixedComplexColumnVector::incintsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the integer part is increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexColumnVector FixedComplexColumnVector::incdecsize (const double n)
FixedComplexColumnVector FixedComplexColumnVector::incdecsize (const ComplexColumnVector &n)
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by n. If n is negative, then ds is decreased. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

FixedComplexColumnVector FixedComplexColumnVector::incdecsize ()
     Return a fixed point object equivalent to the current fixed point number but with the number of bits representing the decimal part ds increased by 1. If the result of this operation causes is + ds to be greater than sizeof(int)*8 - 2, the error handler is called.

The Upper Level Octave Classes
==============================

There are 4 upper level classes that define the interface of the fixed point type to the octave interpreter. These mirror similar definitions for floating values in octave and are

  octave_fixed   ->   octave_scalar
  octave_fixed_complex   ->   octave_complex
  octave_fixed_matrix    ->   octave_matrix
  octave_fixed_complex_matrix   ->   octave_complex_matrix

These fixed point classes use the same base classes as the corresponding floating classes, and so have similar capabilities. However, one notable addition are the methods to obtain the base fixed point objects from these classes, and also correspond to similar floating point methods. These are

  fixed_value   ->   scalar_value
  fixed_complex_value   ->   complex_value
  fixed_matrix_value    ->   matrix_value
  fixed_complex_matrix_value   ->   complex_matrix_value

and can be used in all fixed point classes, subject to a possible reduction operations (eg. casts a FixedComplexMatrix as a FixedPoint). In addition the methods scalar_value, complex_value, matrix_value and complex_matrix_value can all be used.

The user should examine the files ov-fixed-cx-mat.h, ov-fixed-complex.h,  ov-fixed-mat.h and ov-fixed.h and the base classes  in the files ov-base-fixed.h, ov-base-fixed-mat.h, and file ov-base.h within octave to see the methods that are available for the upper level classes.

Writing Oct-files with the Fixed Point Type
===========================================

It is not the purpose of this section to discuss how to write an oct-file, or discuss what they are, but rather the specifics of using oct-files with the fixed point type. An oct-file is a means of writing an octave function in a compilable language like C++, rather than as a script file. This results in a significant acceleration in the code. The reader is referred to the tutorial available at http://octave.sourceforge.net/coda/coda.html. The examples discussed here assume that the oct-file is written entirely in C++.

Using C++ Templates in Oct-files
--------------------------------

When using the fixed point toolbox, you will almost certainly want to compare an implementation in fixed-point against the corresponding implementation in floating point. This allows the degradation due to the conversion to a fixed-point algorithm to be easily observed. The concept of C++ templates allows easy implementation of both fixed and floating point versions of the same code. For example consider

     template <class A, class B>
     A myfunc(const A &a, const B &b) {
       return (a + b);
     }

     // Floating point instantiations
     template double myfunc (const double&, const double&);
     template Complex myfunc (const Complex&, const double&);
     template Matrix myfunc (const Matrix&, const double&);
     template ComplexMatrix myfunc (const ComplexMatrix&, const double&);

     // Fixed point instantiations
     template FixedPoint myfunc (const FixedPoint&, const FixedPoint&);
     template FixedPointComplex myfunc (const FixedPointComplex&,
     				   const FixedPoint&);
     template FixedMatrix myfunc (const FixedMatrix&, const FixedPoint&);
     template FixedComplexMatrix myfunc (const FixedComplexMatrix&,
     				    const FixedPoint&);

Eight versions of the function myfunc are created, that allow its use with all floating and fixed types.

Specific Problems of Oct-files using Fixed Point
------------------------------------------------

The fact that the fixed point type is loadable, means that the symbols of this type are not available till the first use of a fixed point variable. This means that the function fixed must be called at least once prior to accessing fixed point values in an oct-file. If a user function is called, that uses a fixed point type, before the type is loaded the result will be an error message complaining of unknown symbols. For example

     octave:1> fixed_inc(a)
     error: /home/dbateman/octave/fixed/fixed_inc.oct: undefined symbol:
     _ZN24octave_base_fixed_matrixI18FixedComplexMatrixE7subsref
     ERKSsRKSt4listI17octave_value_listSaIS5_EE
     error: `fixed_inc' undefined near line 1 column 1

This should not in itself result in an abnormal exit from Octave.

Another problem when accessing fixed point variables within oct-files, is that the Octave octave_value class knows nothing about this type. So you can not directly call a method such as fixed_value() on the input arguments, but rather must cast the representation of the octave_value as a fixed type and then call the relevant method. An example of extracting a fixed point value from an octave_value variable arg is then

       octave_value arg;
       ...
       if (arg.type_id () == octave_fixed::static_type_id ()) {
         FixedPoint f = ((const octave_fixed&) arg.get_rep()).fixed_value();

Similarly, the return value from an oct-file is itself either an octave_value or an octave_value_list. So a special means of creating the return value must be used. For example

       octave_value_list retval;
       Matrix m;
       FixedPoint f;
       ...
       retval(0) = octave_value(m);
       retval(1) = new octave_fixed (f);

Specific points to note when using Oct-files and Cygwin
-------------------------------------------------------

When using the GNU C++ compiler under Cygwin to create a shared object, such as an oct-file, the symbols must be resolved at compile time. This is as opposed to a Unix platform where the resolution of the symbols can be left till runtime. For this reason the fixed point type, when built under Cygwin is split into an oct-file and a shared library called liboctave_fixed.dll. This is as opposed to the situation under Unix, where only the Oct-file containing all of the fixed point type is needed.

This has the implication that when you build an Oct-file under Cygwin using the fixed point type, that they must be linked to liboctave_fixed.dll. An appropriate means to do this is for example

     % mkoctfile -loctave_fixed myfile.cc

The file liboctave_fixed.dll and liboctave_fixed.dll.a must be located somewhere that the compiler can find them. If these are installed in the same directory as liboctave.dll and liboctave.dll.a respectively, then mkoctfile will find them automatically.

A Simple Example of an Oct-file
-------------------------------

An example of a simple oct-file written in C++ using the fixed point type can be seen below. It integrates the ideas discussed previously.

     #include <octave/config.h>
     #include <octave/oct.h>
     #include "fixed.h"

     template <class A, class B>
     A myfunc(const A &a, const B &b) {
       return (a + b);
     }

     // Floating point instantiations
     template double myfunc (const double&, const double&);
     template Complex myfunc (const Complex&, const double&);
     template Matrix myfunc (const Matrix&, const double&);
     template ComplexMatrix myfunc (const ComplexMatrix&, const double&);

     // Fixed point instantiations
     template FixedPoint myfunc (const FixedPoint&, const FixedPoint&);
     template FixedPointComplex myfunc (const FixedPointComplex&,
     				   const FixedPoint&);
     template FixedMatrix myfunc (const FixedMatrix&, const FixedPoint&);
     template FixedComplexMatrix myfunc (const FixedComplexMatrix&,
     				    const FixedPoint&);

     DEFUN_DLD (fixed_inc, args, ,
     "-*- texinfo -*-\n\
     @deftypefn {Loadable Function} {@var{y} =}  fixed_inc (@var{x})\n\
     Example code of the use of the fixed point types in an oct-file.\n\
     Returns @code{@var{x} + 1}\n\
     @end deftypefn")
     {
       octave_value retval;
       FixedPoint one(1,0,1,0);  // Fixed Point value of 1

       if (args.length() != 1)
         print_usage("fixed_inc");
       else
         if (args(0).type_id () == octave_fixed_matrix::static_type_id ()) {
           FixedMatrix f = ((const octave_fixed_matrix&) args(0).get_rep()).
             fixed_matrix_value();
           retval = new octave_fixed_matrix (myfunc(f,one));
         } else if (args(0).type_id () == octave_fixed::static_type_id ()) {
           FixedPoint f = ((const octave_fixed&) args(0).get_rep()).
             fixed_value();
           retval = new octave_fixed (myfunc(f,one));
         } else if (args(0).type_id () ==
                     octave_fixed_complex::static_type_id ()) {
           FixedPointComplex f = ((const octave_fixed_complex&)
     			     args(0).get_rep()).fixed_complex_value();
           retval = new octave_fixed_complex (myfunc(f,one));
         } else if (args(0).type_id () ==
                     octave_fixed_complex_matrix::static_type_id ()) {
           FixedComplexMatrix f = ((const octave_fixed_complex_matrix&)
                     args(0).get_rep()).fixed_complex_matrix_value();
           retval = new octave_fixed_complex_matrix (myfunc(f,one));
         } else {
           // promote the operation to complex matrix. The narrowing op in
           // octave_value will later change the type if needed. This is not
           // optimal but is convenient....
           ComplexMatrix f = args(0).complex_matrix_value();
           retval = octave_value (myfunc(f,1.));
         }
       return retval;
     }

Fixed Point Type Applied to Real Signal Processing Example
**********************************************************

As an example of the use of the fixed point toolbox applied to a real signal processing example, we consider the implementation of a Radix-4 IFFT in an OFDM modulator. Code for this IFFT has been written as a C++ template class, and integrated as an Octave Oct-file. This allowed a single version of the code to be instantiated to perform both the fixed and floating point implementations of the same code. The instantiations of this class are

     template Fft<double,Complex,ComplexRowVector>;
     template Fft<FixedPoint,FixedPointComplex,FixedComplexRowVector>;

     template Ifft<double,Complex,ComplexRowVector>;
     template Ifft<FixedPoint,FixedPointComplex,FixedComplexRowVector>;

The code for this example is available as part of the release of this software package.

A particular problem of a hardware implementation of an IFFT is that each butterfly in the radix-4 IFFT consists of the summation of four terms with a suitable phase. Thus, an additional 2 output bits are potentially needed after each butterfly of the radix-4 IFFT. There are several ways of addressing this issue

 1. Increase the number of bits in the fixed point representation by two after each radix-4 butterfly. There are then two ways of treating these added bits:

      A. Accept them and let the size of the representation of the fixed point numbers grows. For large IFFT's this is not acceptable

      B. Cut the least significant bits of representation, either after each butterfly, or after groups of butterflies. This reduces the number of bits in the representation, but still trades off complexity to avoid an overflow condition

 2. Keep the fixed point representation used in the IFFT fixed, but reduce the input signal level to avoid overflows. The IFFT can then have internal overflows.

An overflow will cause a bit-error which is not necessarily critical. The last option is therefore attractive in that it allows the minimum complexity in the hardware implementation of the IFFT. However, careful investigation of the overflow effects are needed, which can be performed with the fixed point toolbox.

The table below shows the case of a 64QAM OFDM signal similar to that used in the 802.11a standard. In this table the OFDM modulator has been represented using fixed point, while the rest of the system is assumed to be perfect. The table shows the tradeoff between the backoff of the RMS power in the frequency domain signal relative to the fixed point representation for several different fixed point representations.

    Backoff    BER       BER        BER
        dB   8+1 Bits   10+1 Bits  12+1 Bits
    -------  --------   ---------  ---------
      5.00   2.11e-01   2.27e-01   2.30e-01
      6.00   1.09e-01   1.18e-01   1.21e-01
      7.00   4.23e-02   5.25e-02   5.53e-02
      8.00   1.17e-02   1.36e-02   1.48e-02
      9.00   5.34e-03   2.21e-03   2.33e-03
     10.00   7.49e-03   3.78e-04   3.71e-04
     11.00   1.22e-02   0.00e+00   0.00e+00
     12.00   2.00e-02   0.00e+00   0.00e+00
     13.00   3.12e-02   0.00e+00   0.00e+00
     14.00   4.34e-02   0.00e+00   0.00e+00
     15.00   6.12e-02   2.31e-07   0.00e+00
     16.00   7.53e-02   2.31e-06   0.00e+00
     17.00   9.00e-02   1.87e-05   0.00e+00
     18.00   1.15e-01   5.56e-05   0.00e+00
     19.00   1.30e-01   4.69e-04   0.00e+00
     20.00   1.55e-01   1.30e-03   0.00e+00
     21.00   1.84e-01   2.96e-03   0.00e+00
     22.00   1.98e-01   7.41e-03   0.00e+00
     23.00   2.30e-01   1.09e-02   0.00e+00
     24.00   2.50e-01   1.99e-02   0.00e+00
     25.00   2.73e-01   2.99e-02   0.00e+00
     26.00   2.99e-01   4.38e-02   0.00e+00
     27.00   3.39e-01   6.09e-02   2.31e-07
     28.00   3.51e-01   7.57e-02   2.31e-06
     29.00   3.86e-01   8.99e-02   9.72e-06
     30.00   3.97e-01   1.16e-01   6.99e-05

Two regions are clearly visible in this table. When the backoff of the RMS power is small, the effects of the overflow in the IFFT dominate, and reduce the performance. When the backoff is large, there are fewer bits in the fixed point representation relative to the average signal power and therefore a slow degradation in the performance. It is clear that somewhere between 11 and 13 bits in the representation of the fixed point numbers in the IFFT is optimal, with a backoff of approximately 13dB.

Function Reference
******************

_SECTION(Fixed Point Type)