Otherware

home *** CD-ROM | disk | FTP | other *** search

/ Otherware / Otherware_1_SB_Development.iso / amiga / misc / icalc.lha / ICalc / Docs / UserGuide < prev

Wrap

Text File | 1992-08-03 | 37.1 KB | 1,123 lines

¢3micalc ¢0m¢1mversion 2¢0m.¢1m1 ¢0mA complex-number expression language (C) 1991,1992 Martin W.Scott All Rights Reserved. User Guide icalc User Guide icalc ¢1mIntroduction ¢0m¢3micalc ¢0mis a terminal-based calculator; the ¢1mi ¢0mstands for ¢1mimaginary¢0m, denoting the fact that the calculator works with complex numbers. There are many calculator programs for the Amiga, but to my knowledge, none with this ability. ¢3micalc ¢0malso performs real (normal) calculations too, and you can completely ignore the complex number facility if you wish. Version 2.0 of icalc introduced major additions, effectively making ¢3micalc ¢0ma C-like programming language. However, you can completely ignore these extensions if you shy away from programming. In light of this, the more advanced documentation is kept separate from the simple instructions, in the 'Advanced Guide', which covers such topics as number-bases, programming constructs, arrays and scripts. ¢1mComplex Numbers ¢0mA complex number is made up of two components: a real part, and an imaginary part. The imaginary part is just a real number multiplied by the special number i, which is defined to be the square root of -1. Thus, i*i = -1. This may all seem very artificial, but it's not; complex numbers exist as surely as real numbers do (or don't, depending on your mathematical philosophy). However, real numbers seem more tangible to us, since we use them (or approximations to them) in our everyday life. It is not the purpose of this guide to teach you anything about complex numbers - if you don't know about them, you probably don't need to, but if you do any numerical work, you will probably still find ¢3micalc ¢0museful, because real numbers are a subset of complex numbers, and can thus be manipulated by this program as in an ordinary calculator-type program. Don't be put off - I hardly ever need to use complex numbers - I just like the facility to be there for the odd occasion when I do use them. In what follows, examples are indented. Things you type are preceded by a '>' prompt sign, and output from ¢3micalc ¢0mis further indented. ¢1mExpressions ¢0m¢3micalc ¢0maccepts expressions in the usual form for computer expressions, i.e. multiplication must be explicitly shown by '*', and function arguments enclosed within parentheses. The exception to this is the method of inputing imaginary parts of complex numbers. If you want to enter the number 3 + 4i, you can type either > 3+4i or > 3+4*i icalc -2- version 2.1 icalc User Guide icalc but ¢3mnot ¢0m> 3+i4 # this won't do... since this would give an ambiguous grammar - is it i*4 or the variable "i4"? In almost all circumstances, the algebraic "4i" is preferred, but there is one exception, exponentation "^". If you want 3*i^3, you must type > 3*i^3 and not > 3i^3 The former gives the correct result, -3i, whilst the latter gives -27i. This is because the grammar sees "3i" as a number in its own right, and not an implicit multiplication. NB: Implicit multiplication (leaving out '*' sign) is only recognised in the case of a numerical multiple of i. See the appendices for the complete list of commands, operators, constants and builtin functions that ¢3micalc ¢0msupports. Expressions are separated by newlines or semi-colons ';'. You may also split an expression over multiple lines using a backslash '\' to indicate continuation to the next input line. Comments are introduced by '#', and the rest of the input line is ignored. You may also place comments after backslashes. ¢1mSample Expressions ¢0mBelow are a few examples of what ¢3micalc ¢0mwill accept. > x=4 # an assignment statement assigns to variable x the value 4. > # and now, two statements separated by a semi-colon > sqr(x); x*sqr(x); displays the values 16 and 64 (sqr(x) returns x*x). The next example demonstrates a problem inherent in machine calculations: > 2*sin(x)*cos(x) - sin(2*x) displays the value -2.22044604925e-16. The answer should be 0, and indeed is very close to that. The inaccuracy results because each term has a value as close to the actual value icalc -3- version 2.1 icalc User Guide icalc as the computer's internal representation of numbers can hold (see the Advanced Guide for a small discussion of this particular case). You can change the number of significant figures ¢3micalc ¢0mdisplays by the prec() function - see Appendix 4. ¢1mStarting icalc ¢0m¢3micalc ¢0mmay be started from either the CLI or Workbench. Once started, ¢3micalc ¢0mwill process the file whose name is contained in the environment variable ICALCINIT, defaulting to the file "s:icalc.init" if no environment variable is declared. This initialization file may be used to extend the functions available in ¢3micalc. ¢0mA sample file is given in the S directory of this distribution. If running under AmigaDOS 1.3, it is recommended that you use NEWCON: or ConMan to provide editing and history facilities. For users of AmigaDOS 2.0, the normal CON: window has these facilities built-in, and you may also add a close gadget. CLI Usage The synopsis for icalc is icalc [file-list] where file-list is a list of input files. ¢3micalc ¢0mwill read (process) the files in the list and exit. If a file-list is specified, ¢3micalc ¢0mwill assume that you do not wish to use the program interactively. If you do, you should specify one of the files as a dash "-"; this is taken to mean "use standard input". If no file-list is given, ¢3micalc ¢0mstarts an interactive session. You can obviously redirect output to a file if you wish (and redirect input from a file, but this is generally unnecessary). For example, if you wanted to use definitions contained in a file called "stat.ic", and then type some expressions in at the terminal, you would use icalc stat.ic - to start the program. Because the program makes extensive use of recursion, I recommend you use a stack size of about 20K when running ¢3micalc. ¢0mWorkbench Usage To start ¢3micalc ¢0mfrom the Workbench, simply double-click its icon. You may also pass arguments (definition/command files) to ¢3micalc ¢0min the usual Workbench manner (shift-select etc.). ¢3micalc ¢0mwill then open a window on the Workbench screen for an interactive session. You can specify the window to be opened by modifying the WINDOW tooltype (click once on the ¢3micalc ¢0micon, and select "Info" from the Workbench menu). By default, this is a CON: window. (As noted above, AmigaDOS 1.3 users could alter this to a NEWCON: window). icalc -4- version 2.1 icalc User Guide icalc You may also set the default tool of a definition file's project icon to be ¢3micalc. ¢0mThen simply double clicking the project icon will launch ¢3micalc ¢0mand read the definition file. Remember, however, to set the project icon's stack to 20000, or you may get a stack overflow error. Exiting icalc To end an interactive session of ¢3micalc ¢0m(from either CLI or Workbench) use the command "quit" or "exit". You can also type ^\ (press the control key and '\' simultaneously). If running under AmigaDOS 2.0, you can use the window's close-gadget. ¢1mVariables ¢0mVariables in ¢3micalc ¢0mcan be named arbitrarily, as long as no name conflicts with a pre-defined symbol name, such as sin or PI. The standard conventions apply: the first character must be a letter or underscore, followed by a string of letters, digits and underscores. Case IS significant. Variables are introduced by using them; If a variable is used before it has been initialized (i.e. has had a value assigned to it), ¢3micalc ¢0mwill warn the user and use the value zero. Assignments can appear anywhere in an expression, and are in fact expressions in their own right (as in the programming language C). So, you can do things like > apple = banana = apricot = 34 to assign the value 34 to all these variables. Since assignments are expressions, their value being the assignment value, you can also do > apple = sqr(banana = 12) which assigns the value 12 to "banana", and 144 to "apple". You can of course assign new values to existing variables. ¢1mConstants and ans ¢0m¢3micalc ¢0mcomes with several predefined constants, e.g. PI, GAMMA etc, which by convention are all in upper-case. You cannot assign a new value to a constant. There is a special constant, "ans", which isn't really a constant at all, but is made so to prevent assignments to it. "ans" contains the value of the previously evaluated expression, and so is useful when splitting a calculation up into smaller chunks. > 1 + 2 + 3 6 > ans * 12 72 You can also use it for recursive formulas. For example, icalc -5- version 2.1 icalc User Guide icalc the logistic equation xnext = rx(1-x) for parameter r = 3.5, initial x = 0.4 could be iterated as follows: > r = 3.5; 0.4 # initialize r and ans 3.5 0.4 > r*ans*(1-ans) 0.84 > r*ans*(1-ans) 0.4704 > r*ans*(1-ans) 0.87193344 > r*ans*(1-ans) 0.39082930673 and so on. Of course, you needn't use "ans" here; you could just use assignments to "x", but it illustrates the point. Note that once the necessary variables have been initialised, the same expression is evaluated repeatedly. Thus, if you are using a window with history capabilities you can save a lot of typing by pressing the up-arrow. There are other ways to perform repeated calculations in ¢3micalc. ¢0mYou can use so-called Special functions (explained below), or the C-style looping constructs described in the 'Advanced Guide'. ¢1mBuiltin Functions ¢0m¢3micalc ¢0mcomes with many builtin functions, for example sin, cos, sqrt, exp, ln etc. There are some special functions for complex numbers too, namely Im, Re, arg, norm. All functions take real or complex arguments, which can be any expression, although in some cases, the complex part is discarded. Consider > sin(12-3i) -5.40203477452 - 8.45362341558 i > asin(ans) -0.56637061436 - 3 i > sin(ans) -5.40203477452 - 8.45362341558 i Here we see a property of inverse trigonometric functions, their many-valuedness, due to their periodicity on the real line. The function asin returns a value in its PVR (principal value range) as do all many-valued functions in ¢3micalc. ¢0mSee the 'Advanced Guide' for exact definitions of PVRs of the inverse trigonometric functions used in ¢3micalc. ¢0mOther functions owe their many-valuedness to the fact that the argument of a complex number is 2*PI-periodic. In ¢3micalc ¢0mthe argument always falls in the range -PI < arg <= PI. Another thing to bear in mind if you're not using complex numbers is that expressions like icalc -6- version 2.1 icalc User Guide icalc > ln(-1) return a value, 3.14159265359*i (PI*i) in this case. (The natural logarithm onto the real line is defined for range (0, +infinity)). ¢1mUser¢0m-¢1mdefined Functions ¢0mUser-defined functions give ¢3micalc ¢0mits flexibility and power. Any function that can be stated as a normal expression (or list of expressions) may easily be defined and used like a builtin function. In this document, only very simple function definitions are explained. Functions more akin to those in a computer program are described in the 'Advanced Guide'. Functions are defined using the 'func' keyword, in the following manner: func <name> ( <parameter-list> ) = <expr> so to define the function f(z) = sin(sqrt(z)), simply type > func f(z) = sin(sqrt(z)) Note that z is ¢3mlocal ¢0mto the function, not a global variable. Thus, if z has been defined as a variable before defining f(z), it is unaltered when you call f(z). The standard initiation file 'icalc.init' contains many simple function definitions, and you may find it instructive to examine it. Multi-parameter functions may also be defined. For example, the volume of a right-circular cone is given by the formula volume = 1/3*PI*sqr(r)*h where r is the radius of the base, and h is the height of the cone. We can define a function to compute the volume as follows: > func conevol(r,h) = 1/3*PI*sqr(r)*h > conevol(1,3) 3.14159265359 It is also possible (though of limited use) to declare functions that take no parameters. Examples of multi-parameter functions are given in the sample definition files. NB: As with most programming languages, don't write circular definitions; ¢3micalc ¢0mdoes not detect them, and will swiftly run out of stack space. icalc -7- version 2.1 icalc User Guide icalc ¢1mSpecial Functions ¢0mCertain builtin functions in ¢3micalc ¢0mare called ¢3mspecial ¢0mbecause of the way they use their arguments. Normally, when you `call' a function, its arguments are first evaluated and then the function is called. With special functions however, the arguments are not evaluated; this means that the expressions themselves (and not just their values) can be used by the function in a number of ways. Special functions were introduced in version 1.1 of ¢3micalc. ¢0mbut since version 2.0, they have become largely redundant (with one or two exceptions) due to the C-style programming constructs added. However, for non-programmers or people who don't wish to use ¢3micalc ¢0mas a programming language, they do provide a means for performing several common operations which would otherwise prove difficult. Some special functions take integers as arguments; if you supply an expression with a non-integral value, this value will be stripped of its imaginary component, and the remaining real number rounded to the nearest integer. Currently, the special functions are as follows. Sum(var,upto,expr) This command calculates finite sums. The variable `var' is the index of summation, with an optional assignment. While the value of the index is less than or equal to the value of the upto argument, the value of expr is added to an internal summation variable, which is initially zero. Examples will help to clarify usage. To evaluate the sum of the first 100 natural numbers (naively) we could do > Sum(n=1,100,n) which gives the answer as 5050 (which is 100/2*(100+1)). Note the initial assignment of 1 to n. If no initial value is specified, a value of zero is assumed (and the user is notified of this). When a summation is complete, the index variable holds a value 1 greater than the value of upto. We can also use Sum() to provide approximations to infinite sums. > Sum(n=1, 100, 1/sqr(n)) 1.63498390018 Using the fact that n will now hold the value 101, we can continue the summation to 200 by the following: > ans + Sum(n, n+99, 1/sqr(n)) 1.63994654601 and continue to obtain closer answers by repeating the last line, icalc -8- version 2.1 icalc User Guide icalc > ans + Sum(n, n+99, 1/sqr(n)) 1.6416062829 which is getting there (the infinite series sums to PI^2/6 = 1.64493406685). One last example, to evaluate the sum of the all even numbers upto 100. > Sum(n=1, 50, 2*n) 2550 Prod(var,upto,expr) This command calculates finite products, in an analogous way to the Sum() special function. Examples will demonstrate its use. > Prod(n=1, 10, n) calculates 10!, which is 3628800. We can also use Prod() to investigate infinite products, although care should be taken. Consider Wallis's product for PI/2: PI 2╫2╫4╫4╫6╫6╫... -- = --------------- 2 1╫3╫3╫5╫5╫7╫... Here the product is 2/1 * 2/3 * 4/3 * 4/5 * ... and so we must find a method of producing the numerators and denominators from an index. It is easiest to evaluate the product in pairs of terms. Thus, for each term our numerator will be sqr(2*n), and our denominator will be (2*n-1)*(2*n+1) = sqr(2*n)-1. Note that sqr(2*n) appears in both the numerator and denominator. We can therefore optimise the calculation by using a temporary variable to hold this value. We proceed as follows: > Prod(n=1, 100, (t = sqr(2*n))/(t-1)) 1.56689374531 > ans * Prod(n, n+99, (t = sqr(2*n))/(t-1)) 1.56883895048 > ans * Prod(n, n+99, (t = sqr(2*n))/(t-1)) 1.56949005194 every(var,upto,expr) and vevery(var,upto,expr) These functions preform more general iterations than Sum() and Prod(). They return the value of the last expression evaluated, ie. expr evaluated when var = upto. The difference between every() and vevery() is that the latter produces verbose output - it prints the value of the index and the result of the expression for every iteration. Example: evaluate sin(sin(...(sin(z))...)) with sin() applied 10 times. Here we'll take z to be 1-i. > last = 1-i; every(n=1, 10, last = sin(last)) icalc -9- version 2.1 icalc User Guide icalc 0.51856951608 - 0.01039404248 i Although every() and vevery() are useful in some situations, most iterations are more easily performed by using Sum() and Prod(). multi(expr1, expr2, ... , exprN) This special function still exists for upward compatability, but it is syntactically equivalent to the C-style block introduced with version 2.0: { expr1 ; expr2 ; ... ; exprN; } (In fact, the semicolons can be omitted and new-lines used instead - see the 'Advanced Guide'). The value of a call to multi or a block expression is that of the last expression evaluated, namely exprN. If output has not been switched off with the 'silent' command, use of a block will print the result of it's last argument. In order to print the results of other expressions, the builtin function print() is supplied. print() takes one argument, prints it to the display, and returns its argument as a result. In this way, expressions can appear to return more than one result. An example: write a function that converts Cartesian coordinates into polar form, returning the radius and angle in degrees, and setting the variables r and theta to these values. > func rec2pol(x,y) = { > r=print(sqrt(x*x+y*y)) > theta=DEG*arg(x+i*y) > } > rec2pol(3,4) 5 53.1301023542 Note the use of complex argument to obtain the correct quadrant. ¢1mOther features ¢0m¢3micalc ¢0mnow has a full complement of common programming constructs (C-style) such as if-else, for-loops etc. This necessitated the addition of relational operators >=, > etc. and logical operators &&, ! etc. In order to make the range of applications wider, single-dimensional arrays may also be used in a very simple manner. icalc -10- version 2.1 icalc User Guide icalc User-function arguments may be arrays, pointers to variables and even expressions (in the sense of expressions to 'special' functions) although in this area, syntax differs considerably from the C programming language. All these and other extensions are very useful facilities, but non-essential for simple work. They are described in detail in the 'Advanced Guide'. ¢1mCommands ¢0m¢3micalc ¢0mhas a few commands to make life easier. One or two commands take a string as an argument. Strings are enclosed in double-quotes, e.g. "hello", although you may drop the trailing quote if you wish. It should be noted that commands may NOT be used within function or block declarations. bye quit exit not surprisingly, these commands terminate ¢3micalc. ¢0msilent stops generation of any further output. However, errors and warnings are still displayed. It is useful for initialization files containing lots of definitions. verbose restores generation of output. help reminds you what other commands are available. vars lists all currently defined variables and their values, and allocated arrays. consts lists all predefined constants and their values. builtins lists all built-in functions available, including special functions. functions lists all user-defined functions, with their parameter lists. echo <string> simply prints given string (like Shell echo command). pwd prints the current directory of ¢3micalc. ¢0mcd <new-directory> changes current directory of ¢3micalc. ¢0mEg. cd "s:" icalc -11- version 2.1 icalc User Guide icalc exec <command-string> executes command as if it had been typed in a Shell. Eg. exec "ed s:icalc.init". If ¢3micalc ¢0mis started from the Workbench, output from exec'd commands will only be displayed if you are using AmigaDos 2.0 or above (this is a compiler/OS bug). read <file> reads and evaluates contents of named file (in same manner as if passed on command-line to ¢3micalc ¢0mor as a Workbench argument. writevars <file> dumps all variables defined in current session (including arrays) to specified file, for subsequent restoration with the read command at another session. At present user-function definitions are NOT saved (and are never likely to be in future versions). The file is in human-readable form. There are a couple of other commands detailed in the 'Advanced Guide'. ¢1mBugs ¢0mOne major bug was fixed in release 1.1a - the sqrt() builtin was not returning values in the correct quadrant. Consequently, the inverse trigonometric functions, which are defined using sqrt(), broke. This has now been corrected. Thanks to Pierre Ardichvili for pointing this out. (Version 1.1a fixed this bug, but wasn't widely distributed because version 2.0 was (supposedly) imminent.) From version 2.1, new routines were written to replace the ones supplied with the SAS/C compiler (specifically the scanf and printf "%g" routines) thus removing all bugs associated with these routines (such as printing "0." and "-0." amongst others). Thanks to Eric Rankin for reporting the display bugs. I hope that's all the major bugs ironed out, but there may be the odd little bug in there somewhere -- if you find any, PLEASE let me know and I'll try to fix them. If there's something you hate about ¢3micalc ¢0mand would like changed, or something you'd love that's not in, drop me a line (at the address below), or email me. ¢1mSource ¢0m¢3micalc ¢0mwas written in C, and compiled with SAS/C (version 5.10a). Berkeley Yacc was used to generate the parser. The source to version 2.1 of ¢3micalc ¢0mis available on request, for a small fee. See the 'ReadMe.First' document for further details. icalc -12- version 2.1 icalc User Guide icalc ¢1mCredits ¢0mThanks to the authors of Berkeley Yacc (it makes these things so much easier to write and modify) and to SAS for a (fairly) stable C compiler. Thanks also to Steve Koren for Sksh, and Mike Meyer et al for Mg3; together they make a great development environment. Jeremy McDonald provided me with a routine for displaying numbers in any base (from 2 to 36) which has been used as the core of the number-displaying routine used in ¢3micalc ¢0m-- thanks Jeremy! Many of the algorithms used in the sample script-files that come with ¢3micalc ¢0mwere based on those in "Numerical Recipes in C", by Press et al. The book is very readable, and well worth obtaining if you use numerical algorithms in your work. This was my first yacc-based project, and I learnt a lot from "The Unix Programming Environment" by Brian Kernighan and Rob Pike. Their "hoc" taught me a lot about using Yacc. Most of all, thanks to those people who have written to me regarding icalc, for their comments and contributions. ¢1mDistribution ¢0m¢3micalc ¢0mis freeware, copyrighted software. This copyright applies to all files in the ¢3micalc ¢0mdistribution. You are permitted to distribute it at only a nominal charge to cover costs. All files should be included unmodified. Under no circumstances should ¢3micalc ¢0mbe sold for profit. ¢1mThe Bottom Line ¢0mAlthough ¢3micalc ¢0mis not shareware, contributions would be most welcome, as I'm a poor student, and have put a lot of work into this project. But they're NOT required - bug reports, praise, suggestions, neat programs etc. are welcome (and indeed encouraged) with or without contribution. Thanks to those kind people (small in number) who have written to me. I can be contacted via snail mail at: Martin W. Scott, 23 Drum Brae North, Edinburgh, EH4 8AT United Kingdom. or you can email me; my address is mws@castle.ed.ac.uk Thanks for reading this far. The appendices follow; some details in them will not have been covered in this document, icalc -13- version 2.1 icalc User Guide icalc but are explained in the 'Advanced Guide'. icalc -14- version 2.1 icalc User Guide icalc ¢1mAppendix 1 ¢0m- ¢1mOperators ¢0m(¢1min increasing order of precedence¢0m) = += -= *= /= assignment ?: ternary operator || logical or && logical and == != equal, not equal > >= < <= greater-than etc. + - addition, subtraction * / multiplication, division - ! unary minus, logical not ^ exponentation ' conjugate operator ¢1mAppendix 2 ¢0m- ¢1mConstants ¢0mABASE index of first element for arrays DEG Number of degrees in one radian E exp(1) FALSE 0 GAMMA Euler's constant, 0.57721566... INFINITY (almost) the largest real number possible LOG10 ln(10) LOG2 ln(2) PHI Golden ratio 1.61803398... PI 4*atan(1) (that's one definition) TRUE 1 ¢1mAppendix 3 ¢0m- ¢1mKeywords ¢0mfunc function declaration array (external) array definition local local variable definition return return from function if-else control-flow constructs while-do do-while for icalc -15- version 2.1 icalc User Guide icalc ¢1mAppendix 4 ¢0m- ¢1mBuiltin functions ¢0mParameters are evaluated from left to write. Parameters shown: z implies complex number expected, x implies real number expected, n implies integer expected. a implies array identifier expected. Conversions will be made if required. Functions you think missing below may well be defined in one of the support scripts. ¢1mSingle¢0m-¢1margument functions¢0m: sin(z) trigonometric functions cos(z) tan(z) asin(z) inverse trigonometric functions acos(z) atan(z) sinh(z) hyperbolic trigonometric functions cosh(z) tanh(z) exp(z) exponential function ln(z) natural logarithm sqr(z) square sqrt(z) square root conj(z) conjugate (see also ' operator) abs(z) absolute value (sqrt(norm(z)) norm(z) not really norm; if z=x+iy, norm(z) = x▓+y▓ arg(z) principal argument (in (-PI,PI]) Re(z) real part of complex number Im(z) imaginary part of complex number ceil(x) ceil of real part (eg. ceil(1.2) = 2) floor(x) floor of real part (eg. floor(1.2) = 1) int(x) return real part rounded to nearest integer sgn(x) sign of real part (eg. sgn(-1.6) = -1) time(x) system time in seconds, less its argument print(z) prints and returns value of its argument prec(n) adjust number of significant figures displayed sigzeros(n) set # of leading zeros considered significant error(n) abort evaluation with error n outbase(n) print numbers using base-n icalc -16- version 2.1 icalc User Guide icalc ¢1mArray functions¢0m: display(a) display contents of an array sizeof(a) returns number of elements in array resize(a,n) changes dimension of array to new size n arraybase(n) change first index of arrays to n (returns old base) ¢1mSpecial functions¢0m: Sum calculate a finite sum Prod calculate a finite product every perform a general iteration quietly vevery perform a general iteration verbosely multi evaluate many expressions (defunct) min returns minimum real part in parameters max returns maximum real part in parameters min and max take an arbitrary number of arguments. icalc -17- version 2.1