Complex Library / Reference

 Omikron Basic on the Internet: http://www.berkhan.com

General Info -turn page-Table of Contents


2.1 Library Logging On and Logging Off
2.2 Functions to Switch between Real and Complex Format
2.3 Input Functions
2.4 Output Functions
2.5 Basic Arithmetic Operations
2.6 Important Non-analytical Functions
2.7 Transcendental Functions
2.8 Polynomial Functions
2.9 Matrix Functions
2.10 Complex Line Integral
 
 




This chapter features a description of all functions and procedures of the Library. Time and space is too limited, of course, to explain the theoretical background of each procedure at this time. You do have to know your way around the theory of complex numbers in order to make practical use of the Library.
 
 


2.1 Library Logging On
and Logging Off (Initializing)

Cinit
Call this procedure once at the beginning of your program. The Complex Library may not be used prior to the call.
Important: This procedure changes the DATA pointer. So, if you want to read your own DATA after calling Cinit you previously have to restore the DATA pointer to the desired DATA.
 
 
Cexit
Call this procedure once at the end of your program. The Complex Library may not be used subsequently.
 
 
Complex
Only displays a copyright notice of the Complex Library.

 
 


2.2 Functions to Switch between
Real and Complex Format


FN Cmplx$(Real#,Imag#)
Real# REAL of complex number.
Imag# IMAG of complex number.
The function returns a string, which represents the complex number.
 
 
FN Re#(Z$)
Z$ Complex number.
The function returns the REAL of the complex number Z$ as a real number.
 
 
FN Im#(Z$)
Z$ Complex number.
The function returns the IMAG of the complex number Z$ as a real number.

Example:
PRINT "The IMAG of the number is: ";FN Im#(Z$)
 
 
FN Re$(Z$)
Z$ Complex number.
The function returns the REAL of the complex number Z$ as a complex number.
 
 
FN Im$(Z$)
Z$ Complex number.
The function returns the IMAG of the complex number Z$ as a complex number.

 
 

2.3 Input Functions

Cinput(T$,R Z$)
T$ This string is initially displayed on the screen. If T$ is empty, then the query is performed with "x+iy=? ".
Z$ After the return, this contains the entered complex number.
This procedure serves the input of complex numbers on the screen. Two real numbers, separated by commas, are expected: first the REAL, then the IMAG. The input has to be concluded with [Return].
 
 
Cread(R Z$)
Z$ After the return, this contains the read in complex number.
This procedure serves to read in complex numbers from DATA lines. The complex numbers have to be posted in the DATA lines as two floating point numbers each (REAL, IMAG).

Example:
The number
0.3,0.7i is supposed to be read in from DATA lines:

Cinit
RESTORE Cdata
Cread A$
'
'Here, A$ is processed by your program.
'
INPUT "End with [Return]";Dummy
Cexit
END
-Cdata
DATA 0.3,0.7

 
 
Cmat_Read(&A$(,),M,N)
A$(0:M,0:N) The complex numbers are read into this field.
M Dimension of rows.
N Dimension of columns.
This procedure reads in a whole matrix with the dimensions (M,N) from DATA lines. The complex numbers have to be posted in the DATA lines as two floating point numbers each (REAL, IMAG).
First, all elements of line zero are read in, then the elements of the first line, and so forth.

Example:
The matrix
Demo$(2,1) is supposed to be read in:

Cinit
RESTORE Demo_Data
DIM Demo$(1,2)
Cmat_Read &Demo$(,),1,2
'
'Here, the Demo$(,) is being processed by your 'program.
'
INPUT "End with [Return]";Dummy
Cexit
END
-Demo_Data
DATA 3,7,1,-1,5,6.7:'Elements of line zero.
DATA 1.3,2,-7.3,4,5,6:'Elements of first line.
 
 
Cpoly_Read(&A$(),N)
A$(0:N) The complex polynomial coefficients are read into this field.
N Degree of polynomial (highest power).
This field serves to read in the coefficients of a complex polynomial. The degree of the polynomial (highest power) is indicated with the parameter N. First, the coefficient for Z^0 is read in, then the one for Z^1, and so forth. The DATA pointer has to be set to the desired data first, of course.

Example:
An example can be found with Cpoly_Add.
 
 
Cinput_File(Handle,R Z$)
Handle That is the logical file number indicated with OPEN (1 to 16).
Z$ After the return, this contains the read in complex number.
This procedure may be used to read a complex number from a file previously opened with OPEN "I". The number has to be first saved with Cwrite_File.

Example:
Loads 10 complex numbers into the field C$(0:9). The file "Complex.DAT" has to have been created first, of course:

Cinit
DIM C$(9)
OPEN "I",3,FN Get_Fsspec$(0,0,"Complex.DAT")
FOR I=0 TO 9
 Cinput_File 3,C$(I)
NEXT I
'
'Here, Demo$(,) is being processed by your program.

CLOSE 3
INPUT "End with [Return]";Dummy
Cexit
END

 
 
 





2.4 Output Functions
Cwrite_File(Handle,Z$)
Handle This is the logical file number indicated in OPEN (1 to 16).
Z$ Has to contain the complex number, which is supposed to be written.
A complex number is written to a file. The file has to have been opened previously with OPEN "O" or OPEN "A".

Example:
The example shows how to save a number with the Complex Library using Z$, and then how to input it again using Cinput_File:

Cinit
OPEN "O",1,FN Get_Fsspec$(0,0,"Demo.DAT")
Z$=FN Cmplx$(5.5,-3.14)
Cwrite_File 1,Z$
CLOSE 1
OPEN "I",1,FN Get_Fsspec$(0,0,"Demo.DAT")
Cinput_File 1,X$

Cprint X$
CLOSE 1
INPUT "End with [Return]";Dummy
Cexit
END
 
 
Cprint(Z$)
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides an unformatted output of a complex number in the form of "Re+iIm". After the output, the write pointer is located at the beginning of the next line.
 
 
Cprint_(Z$)
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides an unformatted output of a complex number in the form of "Re+iIm". After the output, the write pointer is located directly behind the output number.
 
 
Cprint(T$,Z$)
T$ This variable may be used to pass text, which is output before the complex number.
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides an unformatted output of a complex number in the form of "Re+iIm" with preceding text. After the output, the write pointer is located at the beginning of the next line.
 
 
Cprint_(T$,Z$)
T$ This variable may be used to pass text, which is output before the complex number.
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides an unformatted output of a complex number in the form of "Re+iIm" with preceding text. After the output, the write pointer is located directly behind the output number.
 
 
Cprint_Using(F$,Z$)
F$ This variable may be used to pass a format string as in PRINT USING, which is then used for the formatting of the complex number.
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides a formatted output of a complex number. After the output, the write pointer is located at the beginning of the next line.
 
 
Cprint_Using_(F$,Z$)
F$ This variable may be used to pass a format string as in PRINT USING, which is then used for the formatting of the complex number.
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides a formatted output of a complex number. After the output, the write pointer is located directly behind the output number.
 
 
Cprint_Using(T$,F$,Z$)
T$ This variable may be used to pass a text, which is output before the complex number.
F$ This variable may be used to pass a format string as in PRINT USING, which is then used for the formatting of the complex number.
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides a formatted output of a complex number with preceding text. After the output, the write pointer is located at the beginning of the next line.
 
 
Cprint_Using_(T$,F$,Z$)
T$ This variable may be used to pass a text, which is output before the complex number.
F$ This variable may be used to pass a format string as in PRINT USING, which is then used for the formatting of the complex number.
Z$ Has to contain the complex number, which is supposed to be output.
This procedure provides a formatted output of a complex number with preceding text. After the output, the write pointer is located directly behind the output number.
 
 
Cmat_Print_Using(F$,&A$(,),M,N)
F$ This variable may be used to pass a format string as in PRINT USING, which is then used for the formatting of the complex number.
A$(0:M,0:N) This field has to contain the complex elements of the matrix, which is supposed to be output.
M Dimension of the rows.
N Dimension of the columns.
This procedure provides a formatted output of a matrix consisting of complex numbers. After the output, the write pointer is located at the beginning of the next line.
 
 
Cpoly_Print_Using(F$,&A$(),N)
F$ This variable may be used to pass a format string as in PRINT USING, which is then used for the formatting of the complex number.
A$(0:N) This field has to contain the complex coefficients of the polynomial, which is supposed to be output.
N Degree of polynomial (highest power).
This procedure provides a formatted output of a complex polynomial. After the output, the write pointer is located at the beginning of the next line.






2.5 Basic Arithmetic Operations
 
FN Cadd$(Z1$,Z2$)
Z1$ Complex number.
Z2$ Complex number.
The function returns the sum of the two numbers (Z1$+Z2$).
 
 
FN Csub$(Z1$,Z2$)
Z1$ Complex number.
Z2$ Complex number.
The function returns the difference of the two numbers (Z1$-Z2$).
 
 
FN Cmul$(Z1$,Z2$)
Z1$ Complex number.
Z2$ Complex number.
The function returns the product of the two numbers (Z1$*Z2$).
 
 
FN Cdiv$(Z1$,Z2$)
Z1$ Complex number.
Z2$ Complex number.
The function returns the quotient of the two numbers (Z1$/Z2$).
 
 
FN Rmul$(Re#,Z$)
Re# Real number.
Z$ Complex number.
The function returns the product of the two numbers (Re#*Z$).
 
 
FN Rdiv$(Z$,Re#)
Z$ Complex number.
Re# Real number.
The function returns the quotient of the two numbers (Z$/R#).
 
 
FN Imul$(Im#,Z$)
Im# Imaginary number.
Z$ Complex number.
The function returns the product of the two numbers (Im#*Z$).
 
 
FN Idiv$(Z$,Im#)
Z$ Complex number.
Im# Imaginary number.
The function returns the quotient of the two numbers (Z$/Im#).
 
 
FN Cmul_I$(Z$)
Z$ Complex number.
The function returns the product of the complex number and i (i*Z$).
 
 
FN Cdiv_I$(Z$)
Z$ Complex number.
The function returns the quotient from the complex number and i (Z$/i).
 
 
FN Cch_S$(Z$)
Z$ Complex number.
The function returns the negative value of the complex number (-Z$).

 
 




2.6 Important Non-analytical Functions

FN Cconj$(Z$)
Z$ Complex number.
The function returns the complex-conjugated value of the complex number.
 
 
FN Cabs$(Z$)
Z$ Complex number.
The function calculates the amount of the complex number (SQR(Re^2+Im^2)). The result is returned as a complex number.
 
 
FN Cabs#(Z$)
Z$ Complex number.
The function calculates the amount of the complex number (SQR(Re^2+Im^2)). The result is returned as a real number.
 
 
FN Cabs_Sqrd$(Z$)
Z$ Complex number.
The function calculates the square of the amount of the complex number (Re^2+Im^2). The result is returned as a complex number. This function is a bit faster than FN Cabs$(Z$).
 
 
FN Cabs_Sqrd#(Z$)
Z$ Complex number.
The function calculates the square of the amount of the complex number (Re^2+Im^2). The result is returned as a real number. This function is a bit faster than FN Cabs#(Z$).
 
 
Cart_To_Polar(Z$,R A#,R P#)
Z$ Complex number.
A# Absolute amount of the complex number Z$ (distance from point of origin).
P# Phase of the complex number Z$ (angle with the real axis).
The procedure calculates amount and phase of the complex number Z$. The value of the phase is dependent on the set angle mode (DEG and/or RAD).
 
 
FN Polar_To_Cart$(A#,P#).
A# Absolute amount of a complex number (distance from point of origin).
P# Phase of a complex number (angle with real axis).
If you pass the spherical coordinates of a complex number to this function, the number will be returned in the form of a string.

 
 






2.7 Transcendental Functions

Interval limits have been indicated with a few of the following functions. In that case, for example, [100,200] signifies the interval that encompasses the points 100 and 200, and [100,200[ signifies the inclusion of 100 but the exclusion of 200.
A few of the functions (such as the logarithm) appear twice. This is due to the fact that these functions can only be unambiguously defined by a section in the complex plane. Different choices are available when choosing this section; in the beginning, one chooses the section so that the complex function, in the form of the maximum analytical continuation, is the result of the corresponding real function. The section defined in such a way has been assigned the default name in the Complex Library, which the real function possesses as well. If a different section has been chosen, this can be recognized by the extension "_P" behind the procedure or function name. "_P" is meant to point towards the section [0,INF] (positive).
Most users will usually choose the main branches, that is the names without extension. The definition of the functions in the sections, however, is a question of conventions and the implementations in the Complex Library may therefore be different from implementations on other systems.
 
 

FN Cexp$(Z$)
Z$ Complex number.
Exponential function with complex argument for base number e.
 
 
FN Iexp$(Im#)
Im# Imaginary number.
Exponential function with purely imaginary argument for base number e.
 
 
FN Rexp$(Re#)
Re# Real number.
Exponential function with purely real argument for base number e.
 
 
FN Csin$(Z$)
Z$ Complex number.
Sine with complex argument.
 
 
FN Ccos$(Z$)
Z$ Complex number.
Cosine with complex argument.
 
 
FN Ctan$(Z$)
Z$ Complex number.
Tangent with complex argument.
 
 
FN Ccot$(Z$)
Z$ Complex number.
Cotangent with complex argument.
 
 
FN Csec$(Z$)
Z$ Complex number.
Secant with complex argument.
 
 
FN Ccosec$(Z$)
Z$ Complex number.
Cosecant with complex argument.
 
 
FN Csinh$(Z$)
Z$ Complex number.
Hyperbolic sine with complex argument.
 
 
FN Ccosh$(Z$)
Z$ Complex number.
Hyperbolic cosine with complex argument.
 
 
FN Ctanh$(Z$)
Z$ Complex number.
Hyperbolic tangent with complex argument.
 
 
FN Ccoth$(Z$)
Z$ Complex number.
Hyperbolic cotangent with complex argument.
 
 
FN Csech$(Z$)
Z$ Complex number.
Hyperbolic secant with complex argument.
 
 
FN Ccosech$(Z$)
Z$ Complex number.
Hyperbolic cosecant with complex argument.
 
 
FN Cln$(Z$)
Z$ Complex number.
Main branch of natural logarithm with section [-INF,0].
 
 
FN Cln_P$(Z$)
Z$ Complex number.
Natural logarithm with section [0,+INF].
 
 
FN Casin$(Z$)
Z$ Complex number.
Arc sine with section [-INF,-1[ and ]1,+INF].
 
 
FN Cacos$(Z$)
Z$ Complex number.
Arc cosine with section [-INF,-1[ and ]1,+INF].
 
 
FN Catan$(Z$)
Z$ Complex number.
Arc tangent with section and [-INF*i,-i[ and ]i,INF*i].
 
 
FN Cacot$(Z$)
Z$ Complex number.
Arc cotangent with section [-i,i].
 
 
FN Casinh$(Z$)
Z$ Complex number.
Inverse hyperbolic sine with section [-INF*i,-i] and [i,INF*i].
 
 
FN Cacosh$(Z$)
Z$ Complex number.
Inverse hyperbolic cosine with section [-INF,1].
 
 
FN Catanh$(Z$)
Z$ Complex number.
Inverse hyperbolic tangent with section [-INF,-1] and [1,INF].
 
 
FN Cacoth$(Z$)
Z$ Complex number.
Inverse hyperbolic cotangent with section [-1,1].
 
 
FN Crecp$(Z$)
Z$ Complex number.
Reciprocal value (1/Z$).
 
 
FN Crecp2$(Z$,A$)
Z$ Complex number.
A$ Complex number by which the value Z$ is supposed to be shifted.
Shifted reciprocal value (1/(Z$-A$)).
 
 
FN Csqr$(Z$)
Z$ Complex number.
The square root of the main branch, section [-INF,0].
 
 
FN Csqr_P$(Z$)
Z$ Complex number.
Square root, section [0,INF].
 
 
FN Csqrd$(Z$)
Z$ Complex number.
The square of the complex number Z$.
 
 
FN Rpower$(Z$,E#)
Z$ Complex number.
E# Real exponent.
Calculates Z$^E#.
 
 
FN Cpower$(Z$,E$)
Z$ Complex number.
E$ Complex exponent.
Calculates Z$^E$.
 
 
FN C1_P_Sqrd$(Z$)
Z$ Complex number.
Calculates 1+Z$^2.
 
 
FN C1_M_Sqrd$(Z$)
Z$ Complex number.
Calculates 1-Z$^2.
 
 
FN Cm1_P_Sqrd$(Z$)
Z$ Complex number.
Calculates -1+Z$^2.
 
 
FN Cm1_M_Sqrd$(Z$)
Z$ Complex number.
Calculates -1-Z$^2.
 
 
FN C1_P_Sqrd$(Z$)
Z$ Complex number.
Calculates 1+Z$^2.
 
 
Croots(Z$,&A$(),N)
Z$ Complex number.
A$(0:N) The roots of the complex number Z$ are returned in this field.
N Indicates the degree of the root calculation.
Calculates the (N+1)th root from Z$. Because a complex number has exactly N Nth roots, the procedure calculates the N values as well. These are returned in the string field A$(), which has to be dimensioned to no less than N-1.

Example:
Calculate the 3rd radicals from -7.


Cinit
DIM R$(2)
Z$=FN Cmplx$(-7,0)
Croots Z$,&R$(),2
Cprint R$(0):Cprint R$(1):Cprint R$(2)
INPUT "End with [Return]";Dummy
Cexit
END

 
 






2.8 Polynomial Functions
The Complex Library offers a variety of diverse functions, which simplify handling of polynomials with complex coefficients. Such a polynomial is completely determined by its coefficients, that is by a quantity of complex numbers (a vector). The Complex Library thus depicts a polynomial with a one-dimensional string array by the first element (e.g., Poly$(0)) representing the constant coefficient and Poly$(N) the coefficient of Z$^N.
 
 
Cpoly_Clear(&A$(),N)
A$(0:N) Complex coefficients of polynomial.
N Degree of polynomial (highest power).
After the dimensioning, the elements of a string field contain empty strings (the empty strings do not represent complex zeros). This procedure sets the elements of the field A$(0:N) to complex zeros.

Example:
We want to work with a polynomial for which we have chosen the name
Polynom$(). The maximum power in our polynomial is Z$^15. First, we want to create the polynomial and set it to zero:

Cinit
DIM Polynom$(15)
Cpoly_Clear &Polynom$(),15
Cpoly_Print_Using "",&Polynom$(),15
INPUT "End with [Return]";Dummy
Cexit
END
 
 
Cpoly_Equal(&A$(),&C$(),N)
A$(0:N) Complex coefficients of the source polynomial.
C$(0:N) Complex coefficients of the target polynomial.
N Degree of polynomial (highest power).
This procedure assigns the polynomial A$(0:N) to the polynomial C$(0:N) and thus corresponds to the BASIC command C=A with the difference that, in this case, a whole polynomial is assigned and not only an individual number.
 
 
Cpoly_Add(&A$(),&B$(),&C$(),M,N)
A$(0:M) Complex coefficients of the first addend.
B$(0:N) Complex coefficients of the second addend.
C$(0:MAX(M,N)) Complex coefficients of the sum polynomial.
M Degree of polynomial A$() (highest power).
N Degree of polynomial B$() (highest power).
This procedure adds the polynomial A$() to the polynomial B$() and returns the result in C$() (C$()=A$()+B$()). This is carried out through the addition of the coefficients with the same power.

Example:
Addition of the polynomials
Poly1$(0:3) and Poly2$(0:8), with the result returned in Poly3$().

Cinit
DIM Poly1$(3),Poly2$(8),Poly3$(8)
RESTORE Polynomials
Cpoly_Read &Poly1$(),3
Cpoly_Read &Poly2$(),8
Cpoly_Add &Poly1$(),&Poly2$(),&Poly3$(),3,8
Cpoly_Print_Using "",&Poly3$(),8
INPUT "End with [Return]";Dummy
Cexit
END
-Polynomials
DATA 1.2,-1,7.5,-2,3.14,3,5.3,7.2
DATA -5.7,-22.13,1,2.5,7,-2.77,11.23,0.123,5.6
DATA 5.4,-2.2,1.3,2,7,-2.33,11.1,2.123,4.56
 
 
Cpoly_Sub(&A$(),&B$(),&C$(),M,N)
A$(0:M) Complex coefficients of the addend.
B$(0:N) Complex coefficients of the subtrahend.
C$(0:MAX(M,N)) Complex coefficients of the difference polynomial.
M Degree of polynomial A$() (highest power).
N Degree of polynomial B$() (highest power).
This procedure subtracts the polynomial B$() from the polynomial A$() and returns the results in C$() (C$()=A$()-B$()), which is carried out through the subtraction of the coefficients with the same power.
 
 
Cpoly_Mul(&A$(),&B$(),&C$(),M,N)
A$(0:M) Complex coefficients of the multiplicand.
B$(0:N) Complex coefficients of the multiplier.
C$(0:M+N) Complex coefficients of the product polynomial.
M Degree of polynomial A$() (highest power).
N Degree of polynomial B$() (highest power).
This procedure multiplies the polynomial A$() by the polynomial B$() and returns the result in C$()(C$()=A$()*B$()). This is carried out through the component multiplication with subsequent summation of equal powers.
 
 
Cpoly_S_Mul(&A$(),Z$,&C$(),N)
A$(0:N) Complex coefficients of the multiplicand.
Z$ Complex number as multiplier.
C$(0:N) Complex coefficients of the product polynomial.
N Degree of polynomial A$() (highest power).
This procedure multiplies the polynomial A$() by the complex number Z$ and returns the result in C$() (C$()=A$()*Z$). This operation is also called a scalar multiplication.
 
 
Cpoly_Div(&A$(),&B$(),&C$(),&D$(),L,M,R N,R O)
A$(0:L) Complex coefficients of the dividend.
B$(0:M) Complex coefficients of the divisor.
C$(0:N) Complex coefficients of the quotient polynomial.
D$(0:O) Complex coefficients of the remainder polynomial.
L Degree of polynomial A$() (highest power).
M Degree of polynomial B$() (highest power).
N Degree of polynomial C$() (highest power).
O Degree of polynomial D$() (highest power).
This procedure divides the polynomial A$() by the polynomial B$() and returns the result in C$() and the remainder of the division in D$() (C$()=A$()/B$() and D$()=A$() MOD B$()). If O=0, then the division has no remainder.
 
 
Cpoly_S_Div(&A$(),Z$,&C$(),N)
A$(0:N) Complex coefficients of the dividend.
Z$ Complex number as divisor.
C$(0:N) Complex coefficients of the quotient polynomial.
N Degree of polynomial A$() (highest power).
This procedure divides the polynomial A$() by a complex number Z$ and posts the result in C$() (C$()=A$()/Z$). This operation is also called a scalar division.
 
 
FN Cpoly_Value$(&A$(),Z$,N)
A$(0:N) Complex coefficients of the polynomial.
Z$ Complex number.
N Degree of polynomial A$() (highest power).
This functions calculates the function value of the polynomial A$() at location Z$ and returns the result as a complex number.
 
 
Cpoly_Zeros(&A$(),&C$(),N,R E,R E$)
A$(0:N) Complex coefficients of the polynomial.
C$(0:N) The procedure returns the complex zero points of the polynomial in this field.
N Degree of polynomial A$() (highest power).
E After the return, this variable can contain the following values:
E=0 : no error
E=1 : leading coefficient equals zero.
E=2 : not all zero points have been located.
E$ If an error has occurred, this string variable contains one of the error texts from the previous field after the return; otherwise, an empty string is returned.
This procedure calculates the zero points of the polynomial A$() and returns the result in C$().

Example:
Calculation of the zero points of the polynomial

Z^3+(-3+i2)*Z^2+(-12-i12)*Z+30-i20.

First, two fields are being dimensioned, namely those for the complex coefficients and the zero points. Then the coefficients are entered into the field. If
Cpoly_Zeros does not report any errors, then the result is displayed on the screen; otherwise, an error message is issued.

Cinit
DIM Poly$(3),Zeros$(2)
Poly$(0)=FN Cmplx$(30,-20):Poly$(1)=FN Cmplx$(-12,-12)
Poly$(2)=FN Cmplx$(-3,2):Poly$(3)=C_R$
Cpoly_Zeros &Poly$(0),&Zeros$(0),3,E,E$
IF E
 THEN PRINT "Error No.:";E,E$
 ELSE PRINT "Zero points of the polynomial ";   
  PRINT "Z^3+(-3+i2)*Z^2+(-12-i12)*Z+30-i20"
  PRINT
  FOR I=0 TO 2
   PRINT I+1;". Zero point: ";:Cprint Zeros$(I)
  NEXT I
ENDIF
PRINT :INPUT "End with [Return]";E
Cexit
END
 
 






2.9 Matrix Functions
Matrices are represented in the Complex Library by 2-dimensional string fields. A matrix begins with the element (0,0). The matrix Z$ (3,3) is thus also a 4x4 matrix and not a 3x3 matrix!
What is important is that the result matrix generally may NOT be identical with one of the argument matrices! This is only permitted if so indicated in a few exceptional cases.
 
 


Cmat_Clear(&A$(,),M,N)
A$(0:M,0:N) The complex elements of the matrix.
M Highest row number.
N Highest column number.
All elements of the matrix A$(,) are set to zero.

Example:
Setting the matrix
Z$(8,11) to zero.

Cinit
DIM Z$(8,11)
Cmat_Clear &Z$(,),8,11
Cmat_Print_Using "",&Z$(,),8,11
INPUT "End with [Return]";Dummy
Cexit
END
 
 
Cmat_Id(&A$(,),N)
A$(0:N,0:N) The complex elements of the matrix.
N Highest row or column number, respectively (square matrix).
This procedure generates a square unit matrix from A$(,). All elements of the main diagonal are set to one and the rest to zero.
 
 
Cmat_Equal(&A$(,),&C$(,),M,N)
A$(0:M,0:N) The complex elements of the source matrix.
C$(0:M,0:N) The complex elements of the target matrix.
M Highest row number.
N Highest column number.
The matrix A$(,) is assigned to the matrix C$(,) (C$(,)=A$(,)). This procedure also copies the content of the matrix A$(,) to the matrix C$(,).
 
 
Cmat_Herm_Conj(&A$(,),&C$(,),M,N)
A$(0:M,0:N) The complex elements of the source matrix.
C$(0:M,0:N) The complex elements of the hermetically conjugated matrix.
M Highest row number.
N Highest column number.
This procedure calculates the hermetically conjugated matrix for A$(,) and assigns the result to the matrix C$(,). If A$(,) is a square matrix (N=M), then A$(,) may be in concordance with C$(,).
 
 
Cmat_Add(&A$(,),&B$(,),&C$(,),M,N)
A$(0:M,0:N) The complex elements of the first addend matrix.
B$(0:M,0:N) The complex elements of the second addend matrix.
C$(0:M,0:N) The complex elements of the sum matrix.
M Highest row number.
N Highest column number.
The matrix A$(,) is added to the matrix B$(,) and the result assigned to the matrix C$(,) (C$(,)=A$(,)+B$(,)). C$(,) may be in concordance with A$(,) or B$(,).
 
 
Cmat_Sub(&A$(,),&B$(,),&C$(,),M,N)
A$(0:M,0:N) The complex elements of the addend matrix.
B$(0:M,0:N) The complex elements of the subtrahend matrix.
C$(0:M,0:N) The complex elements of the difference matrix.
M Highest row number.
N Highest column number.
The matrix B$(,) is subtracted from the matrix A$(,) and the result assigned to the matrix C$(,) (C$(,)=A$(,)-B$(,)). C$(,) may be in concordance with A$(,) or B$(,).
 
 
Cmat_Mul(&A$(,),&B$(,),&C$(,),L,M,N)
A$(0:L,0:M) The complex elements of the multiplicand matrix.
B$(0:M,0:N) The complex elements of the multiplier matrix.
C$(0:L,0:N) The complex elements of the product matrix.
L Highest row number of A$(,) and C$(,).
M Highest column number of A$(,) and highest row number of B$(,).
N Highest column number of B$(,) and C$(,).
The matrix A$(,) is multiplied with the matrix B$(,) and the result assigned to the matrix C$(,) (C$(,)=A$(,)*B$(,)). Please make sure that the individual matrices have the correct dimensions.
 
 
Cmat_S_Mul(&A$(,),Z$,&C$(,),M,N)
A$(0:M,0:N) The complex elements of the multiplicand matrix.
Z$ Complex number as multiplier.
C$(0:M,0:N) The complex elements of the product matrix.
M Highest row number.
N Highest column number.
The matrix A$(,) is multiplied with the complex number Z$ and the result assigned to the matrix C$(,) (C$(,)=A$(,)*Z$. C$(,) may be in concordance with A$(,). This operation is also called a scalar multiplication.
 
 
Cmat_S_Div(&A$(,),Z$,&C$(,),M,N)
A$(0:M,0:N) The complex elements of the dividend matrix.
Z$ Complex number as divisor.
C$(0:M,0:N) The complex elements of the quotient matrix.
M Highest row number.
N Highest column number.
The matrix A$(,) is divided by the complex number Z$ and the result assigned to the matrix C$(,) (C$(,)=A$(,)/Z$. C$(,) may be in concordance with A$(,). This operation is also called a scalar division.
 
 
Cmat_Inv_By_X(&A$(,),&C$(,),N)
A$(0:N,0:N) The complex elements of the source matrix.
C$(0:N,0:N) The complex elements of the inverse matrix.
N Highest row and/or column number.
This procedure calculates the inverse matrix for A$(,) and assigns the result to the matrix C$(,). The REAL of the matrix A$(,) has to be separately reversible for this procedure, otherwise an error message will be issued.
 
 
Cmat_Inv_By_Y(&A$(,),&C$(,),N)
A$(0:N,0:N) The complex elements of the source matrix.
C$(0:N,0:N) The complex elements of the inverse matrix.
N Highest row and/or column number.
This procedure calculates the inverse matrix for A$(,) and assigns the result to the matrix C$(,). The IMAG of the matrix A$(,) has to be separately reversible for this procedure, otherwise an error message will be issued.
 
 
Cmat_Inv(&A$(,),&C$(,),N,R D$)
A$(0:N,0:N) The complex elements of the source matrix.
C$(0:N,0:N) The complex elements of the inverse matrix.
N Highest row and/or column number.
D$ After the return, this contains the determinant of the matrix A$(,).
This procedure calculates the inverse matrix for A$(,) and assigns the result to the matrix C$(,). Neither the REAL nor the IMAG of the matrix A$(,) have to be separately reversible for this procedure. Cmat_Inv is thus the most usual inversion, but also requires the longest calculation time.
 
 
Cmat_Simeq(&A$(,),&B$(,),&C$(,),N,R E)
A$(0:N,0:N) The complex coefficients on the left side of the system of equations.
B$(0:N,0) The complex values on the right side of the system of equations.
C$(0:N,0) The complex elements of the solution vector.
N Number of the last row of the system of equations.
E After the return, E can contain the following values:
E=0 : no error
E=1 : the system of equations could not be solved.


This procedure generally solves the complex system of equations A$(,)*C$(,0)=B$(,0), with A$(,) and B$(,0) being pre-determined. The vector C$(,0) contains the results after the return.
Cmat_Simeq corresponds with the inversion of
A$(,) and subsequent multiplication of the inverse with C$(,0) (standard procedure); however, it works significantly faster than this procedure.
 
 
FN Cmat_Det$(&A$(,),N)
A$(0:N,0:N) The complex elements of the source matrix.
N Highest row and/or column number.
This function calculates the determinant of the complex matrix A$(,).

Example:
Calculation of the determinant of the 5x5 unit matrix.

Cinit
DIM Z$(4,4)
Cmat_Id(&Z$(,),4):'Generate unit matrix.
A$=FN Cmat_Det$(&Z$(,),4):'Calculate determinant.

Cprint(A$):'Output result.
INPUT "End with [Return]";Dummy
Cexit
END
 
 





2.10 Complex Line Integral


Both of these functions in this chapter may be used to integrate complex functions according to a user defined curve and the Gauss algorithm.
The calculation is carried out especially fast if the functions to be integrated fulfill certain and rather high demands of differentiability. Otherwise, the algorithm will calculate the same interval relatively often and thus slows down. In that case it would be more advantageous to use a method according to Romberg or something similar instead of the Gauss algorithms. However, at this time the Complex Library does not offer an appropriate function yet.

 
 

FN Cintegral_Gauss$(&FN Func$(""),&FN Path$(0),&FN Der$(0), A#,B#,Er#,N)
FN Func$(Z$) The function to be integrated. A complex parameter is passed to it and it has to return the complex function value of the passed number as a result.
FN Path$(T#) This function has to describe the integration path in dependency of the real parameter T#, which will be passed to this function by Cintegral_Gauss.
FN Der$(T#) This function has to calculate the first derivative with respect to T# and return it as a complex number.
A# Start value of the parameterized curve.
B# Destination value of the parameterized curve.
Er# Relative maximum error between two iteration steps.
N Number of sections, into which the interval to be integrated will be decomposed. A good value of N is often twice the number of maxima of the function in the viewed interval.

This function calculates a line integral on the complex plane according to the Gauss algorithm. For this calculation, the addresses of three functions have to be passed to the function. These three functions have to be defined by the user and will be called during the calculation by Cintegral_Gauss.
A Gauss integration is carried out independently in each section. The number of sections have to be adjusted to correspond with the variation of the function using the section to be integrated; the larger the variation, the more sections. Too many sections will increase the calculation time, too few, however, have the same effect because then the routine spends it initial recursion steps of the process with generating a sufficiently detailed interval distribution. The intervals are split into increasingly smaller sections recursively until the value falls below
Er#. Of course, Er# does not indicate the maximum number of absolute error, since the errors add up over several iteration steps!

Example:
Let's take the multiplication with the real number 2 as the function to illustrate a very simple example. The integration is supposed to be carried out alongside a parabola, start at point (0,0), and end at (2,4). Since the integration path is supposed to be a parabola, the parameter
T# extends from 0 to 2 due to the parabola equation (X#=T#, Y#=T#^2). The derivative of the REAL to T# is thus constant 1 and the derivative of the IMAG 2*T#. The result of the integration happens to be -12+i16, as one can follow up easily with an analytical calculation.

Cinit
T=&FN Times_2$("")
P=&FN Path$(0)
D=&FN Derivative$(0)
I$=FN Cintegral_Gauss$(T,P,D,0,2,0.1,2)

Cprint(I$)
INPUT "End with [Return]";Dummy
Cexit
END


'Now we still have to define the three functions.
DEF FN Times_2$(Z$)=FN Rmul$(2,Z$)
DEF FN Path$(T#)=FN Cmplx$(T#,T#^2)
DEF FN Derivative$(T#)=FN Cmplx$(1,2*T#)

Example:
In a second example we define a function as
Z$^2+Z$+3.

Cinit
T=&FN Square$("")
P=&FN Path$(0)
D=&FN Derivative$(0)
I$=FN Cintegral_Gauss$(T,P,D,0,2,0.1,2)

Cprint(I$)
INPUT "End with [Return]";Dummy
Cexit
END


'Now we still have to define the three functions.
DEF FN Square$(Z$):LOCAL Temp$
 Temp$=FN Cadd$(Z$,C_R$):
'Horner schematic used.
 Temp$=FN Cmul$(Temp$,Z$)
 Three$=FN Rmul$(3,C_R$)
RETURN FN Cadd$(Temp$,Three$)
DEF FN Path$(T#)=FN Cmplx$(T#,T#^2)
DEF FN Derivative$(T#)=FN Cmplx$(1,2*T#)

Example:
The program "Integral.BAS" in the DEMO folder depicts another example for the use of the integration routine. A line integral is calculated via a closed curve. A
ccording to the residue theorem, the result is thus i*2*PI multiplied by the sum of the residues of the functions within that section. In this example, the integration path is the circle with radius 1 around an inputable point of the complex plane. The function is l/Z, the only residuum is thus located in the origin. If, therefore, the circle integrated along, encircles zero, then the result is i*2*PI, otherwise it is zero.
If the iteration path runs very close by a pole point (close to a residuum) of the function (example:
0+i0), this will lead to a larger iteration depth to reach the preset relative precision. Calculation times are therefore much longer and the absolute precision also decreases significantly if the integration path runs close by the pole. It might become necessary to increase the relative precision to still achieve acceptable results in such cases.
 
 
FN Cintegral_Gauss2$(&FN Func$(""),&FN Path$(0),&FN Der$(0), A#,B#,N)
FN Func$(Z$) The function to be integrated. A complex parameter is passed to it and it has to return the complex function value of the passed number as a result.
FN Path$(T#) This function has to describe the integration path in dependency of the real parameter T#, which will be passed to this function by Cintegral_Gauss.
FN Der$(T#) This function has to calculate the first derivation with respect to T# and return it as a complex number.
A# Start value of the parameterized curve.
B# Destination value of the parameterized curve.
N Number of sections, into which the interval to be integrated will be decomposed. A good value of N is often twice the number of maxima of the function in the viewed interval.

This function also calculates the complex line integral. However, in contrast to its bigger brother, Cintegral_Gauss$, this function is not iterative until a pre-defined error threshold has been undercut but rather calculates the integral once with the pre-defined number of sections. This is the speedier method for harmless functions; however, this method will fail in the case of divergences and discontinuities.
This can be seen clearly if you enter
(0.999#,0) as the center point in the program "Integral.BAS" and integrate with 4 supporting points. The result is i4.18 instead of i6.28. If you then use 1D-15 as the relative error for Cintegral_Gauss$, you will receive the exact same value.

Example:
Once more we use the function definition of
Z$^2+Z$+3, but this time we calculate the function values using the polynomial functions of the Complex Library:

Cinit

DIM Poly$(2)
Poly=&Poly$(0)
Poly$(0)=FN Cmplx$(3,0)
Poly$(1)=C_R$:Poly$(2)=C_R$
T=&FN Square$("")
P=&FN Path$(0)
D=&FN Derivative$(0)
I$=FN Cintegral_Gauss2$(T,P,D,0,2,2)

Cprint(I$)
INPUT "End with [Return]";Dummy
Cexit
END

'The only thing left to do is
'to define the three functions.
DEF FN Square$(Z$)=FN Cpoly_Value$(Poly,Z$,2)

DEF FN Path$(T#)=FN Cmplx$(T#,T#^2)
DEF FN Derivative$(T#)=FN Cmplx$(1,2*T#)

 

 Omikron Basic on the Internet: http://www.berkhan.com

General Info -turn page-Table of Contents

(c) Copyright 1998-1999 by Berkhan-Software