The Fred Fish Collection 1.5

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

/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 600-699 / ff695.lha / ICalc / Docs / UserGuide < prev next >

Wrap

Text File | 1992-07-13 | 36KB | 1,057 lines

3micalc 0m1mversion 20m.1m0 0mA complex-number expression parser (C) Martin W.Scott 1991, 1992 User Guide icalc User Guide icalc 1mIntroduction 0m3micalc 0mis a terminal-based calculator; the 1mi 0mstands for 1mimaginary0m, 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 introduces major additions, effectively making 3micalc 0ma C-like programming language. However, you can completely ignore these extensions if you shy away from programming - this version is (almost) entirely upward compatible with previous versions. In light of this, the more advanced (programming) documentation is kept separate from the simple instructions, in the 'Advanced Guide'. 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 0m3micalc 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.0 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.220446e-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.0 icalc User Guide icalc as the computer's internal representation of numbers can hold. 1mStarting icalc 0m3micalc 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. 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). 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 icalc -4- version 2.0 icalc User Guide icalc 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 0m3micalc 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, 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 icalc -5- version 2.0 icalc User Guide icalc 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.39082931 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 0m3micalc 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.40203477 - 8.45362342 i > asin(ans) -0.56637061 - 3 i > sin(ans) -5.40203477 - 8.45362342 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 > ln(-1) return a value, 3.14159265359*i (PI*i) in this case. (The natural logarithm onto the real line is defined for range icalc -6- version 2.0 icalc User Guide icalc (0, +infinity)). 1mUser0m-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.14159265 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. 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 icalc -7- version 2.0 icalc User Guide icalc 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.6349839 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.63994655 and continue to obtain closer answers by repeating the last line, > ans + Sum(n, n+99, 1/sqr(n)) 1.64160628 which is getting there (the infinite series sums to PI^2/6 = 1.64493407). One last example, to evaluate the sum of the all even numbers upto 100. icalc -8- version 2.0 icalc User Guide icalc > 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.56689375 > ans * Prod(n, n+99, (t = sqr(2*n))/(t-1)) 1.56883895 > ans * Prod(n, n+99, (t = sqr(2*n))/(t-1)) 1.56949005 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)) 0.51856952 - 0.01039404 i Although every() and vevery() are useful in some situations, most iterations are more easily performed by using Sum() and Prod(). icalc -9- version 2.0 icalc User Guide icalc 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.13010235 Note the use of complex argument to obtain the correct quadrant. 1mOther features 0m3micalc 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. 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, icalc -10- version 2.0 icalc User Guide icalc but non-essential for simple work. They are described in detail in the 'Advanced Guide'. 1mCommands 0m3micalc 0mhas a few commands to make life easier. One or two commands take a string as an argument. This string must be enclosed in double-quotes, e.g. "hello". It should be noted that commands may NOT be used within function or block declarations. 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:" 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 not be displayed (this is a compiler/OS bug). icalc -11- version 2.0 icalc User Guide icalc 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.) 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 0m3micalc 0mwas written in C, and compiled with Lattice C (version 5.10a). Berkeley Yacc was used to generate the parser. The source to version 2.0 of 3micalc 0mis available on request, for a small fee. See the 'ReadMe.First' document for further details. 1mCredits 0mThanks to the authors of Berkeley Yacc (it makes these things so much easier to write and modify) and to Lattice for a (fairly) stable compiler. Thanks also to Steve Koren for Sksh, and Mike Meyer et al for Mg3; together they make a great development environment. 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. icalc -12- version 2.0 icalc User Guide icalc Most of all, thanks to those people who have written to me regarding icalc, for their comments and contributions. 1mDistribution 0m3micalc 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, but are explained in the 'Advanced Guide'. icalc -13- version 2.0 icalc User Guide icalc 1mAppendix 1 0m- 1mOperators 0m(1min increasing order of precedence0m) = += -= *= /= 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 0mPI 4*atan(1) (that's one definition) E exp(1) GAMMA Euler's constant, 0.57721566... DEG Number of degrees in one radian PHI Golden ratio 1.61803398... LOG10 ln(10) LOG2 ln(2) TRUE 1 FALSE 0 INFINITY largest real number possible 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 -14- version 2.0 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. 1mSingle0m-1margument functions0m: 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 decimal places displayed error(n) abort evaluation with error n icalc -15- version 2.0 icalc User Guide icalc 1mArray functions0m: 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 1mSpecial functions0m: 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 -16- version 2.0