F R E E T K T U T O R I A L ================================== Copyright (c) 1986 by Universal Technical Systems, Inc. FREETK is an equation processing software product which lets you explore and use of some of the essential features of the full TK Solver Plus. For this tutorial, we will use a sample problem involving loan analysis. Note: One or more characters describing a single key are enclosed in square brackets, e.g., [Enter] for the Enter or Return key, [F3] for the function key F3, [;] for the semicolon key, etc. * Type: freetk and press [Enter] to load the program. A copyright notice will be displayed for a brief period, after which the program will start by itself. You can press any key to start the program immediately. (If you want to return to DOS after the program is loaded, press [/] and choose "Quit" from the option menu.) Two sheets, the Variable Sheet and the Rule Sheet, are now displayed. The cursor is in the Rule Sheet, conveniently placed for the first step in setting up the sample loan analysis problem. ENTERING RULES IN THE RULE SHEET * Type in the equation: price - downpay = loan and press [Down-Arrow] Note that TK automatically entered the variable names on the Variable Sheet for you and moved the cursor to the next row down. (A rule may also be entered by pressing [Enter], in which case the cursor remains on the same row.) ENTERING INPUT VALUES * Press [;] to switch the cursor to the Variable Sheet -- the cursor should appear in the Input field of the variable "price". * Type in an amount for the price, say: 15500 and press [Down-Arrow]. (Note that [Down-Arrow] both enters the value in the Input field for "price" and moves the cursor down one row into the Input field for "downpay".) * Type in a down payment amount: 3500 and press [Enter] Now you are done with problem formulation and are ready to see how TK solves a model, consisting in this case of a single equation. 1 SOLVING * Press [F9] to solve. TK will calculate price - downpay and display the result in the Output field of the variable "loan". This is what your screen should look like: ==================== VARIABLE SHEET ================================= St Input---- Name---- Output-- Unit----- Comment--------------------- 15500 price 3500 downpay loan 12000 ==================== RULE SHEET ===================================== S Rule--------------------------------------------------------------- price - downpay = loan TK calculated how much the loan should be. This is of course very simple and could have been figured out with or even without a calculator, so let us expand the model. ADDING A NEW EQUATION * Press [;] to switch the cursor back to the Rule Sheet. * On the second line, enter the formula for monthly payment: payment = loan * (rate / (1 - (1 + rate)^-term)) TK added the new variables in the Variable Sheet, and you just need to enter input values for some of them in order to obtain a new solution. Before entering values, however, it must be noted that this equation is set up to use months for the variable "term" and decimal fraction per month for the variable "rate". Figuring out the number of months in a four year term can be done in your head, but converting an annual rate of 12.5% to a decimal fraction per month is more difficult. Instead of calculating 12.5/1200 outside of TK and entering the value .01041666666666667, you need only type 12.5/1200 and press [Enter]. TK will automatically calculate the value and display it. ENTERING VALUES FOR NEW VARIABLES. * Press [;] to switch the cursor to the Variable Sheet * Enter 12.5/1200 in the Input field for "rate" * Enter 48 in the Input field for "term" Now you will let TK calculate the monthly payment according to the information you gave it. SOLVING * Press [F9] to solve. 2 TK will calculate the monthly payment and display the value in the Output field of the variable "payment". This is what your screen should look like: ==================== VARIABLE SHEET ================================= St Input---- Name---- Output-- Unit----- Comment--------------------- 15500 price 3500 downpay loan 12000 payment 318.95999 .01041667 rate 48 term ==================== RULE SHEET ===================================== S Rule--------------------------------------------------------------- price - downpay = loan payment = loan * (rate / (1 - (1 + rate)^-term)) REVERSE CALCULATION (BACKSOLVING) Suppose you know how much you can afford for a monthly payment and want to know how long it will take to pay off the loan. Observe that you don't have to rewrite any equations when you are using TK. It does not matter to TK whether any particular variable is on the left side or the right side of the equal sign, or even if a variable appears on both sides of the equal sign. What was once an unknown variable can be made into a known variable by entering a value in its Input field, and a new solution can then be found for another variable. All TK has to know is the relationship between the variables and it can solve for any of them. This is 'backsolving' in its fullest sense. CHANGING INPUT VALUES * Go to the status (St) field of the variable "term" and press [B] to blank the Input field. (In effect, this changes "term" from a known variable to an unknown variable.) * Go to the Input field of "payment" and enter 350 as the monthly payment. (Note that the value 318.95999 disappears from the Output field. "payment", which used to be an unknown variable, is now a known variable.) Without needing to isolate new unknowns on one side of an equation or rewrite an equation in any way, we are now ready for a new solution. * Press F9 to solve. Less the Rule Sheet, which remains the same, this is what your screen should look like: 3 ==================== VARIABLE SHEET ================================= St Input---- Name---- Output-- Unit----- Comment--------------------- 15500 price 3500 downpay loan 12000 350 payment .01041667 rate term 42.636479 So we see that increasing the monthly payment from 318.96 to 350 would take nearly half a year off the loan term. All well and good, except where is there a bank which will lend money for a term of 42.636479 months? SOLVING WITH ITERATION Of course, you could blank out the Input value for "payment", enter an Input value of 42 for "term", and press [F9] to solve for a monthly payment of 354.22 on a loan of 42 months (three and a half years). However, a more interesting problem would result from a constraint of an absolute maximum of 350 for a monthly payment. Assuming you can shop around for different interest rates, how low an interest rate would you have to find in order to pay off the loan in 42 months at 350 per month? How much lower for a 36 month term? * Check that 350 is entered in the Input field for "payment" * Go to the Input field for "rate" and press [Spacebar] [Down-Arrow] (this is another way of blanking the Input field) * Enter 42 in the Input field for "term". * Press [F9] to solve. What went wrong? An asterisk appeared in the Status (S) field of the second rule on the Rule Sheet, indicating that the equation was not solved, and nothing showed up in the Output field for "rate". TK's Direct Solver did not find a solution because "rate" appears twice in the second rule, whereas the Direct Solver can solve an equation only for a single unknown appearing in the equation just once. TK can handle such a situation by taking a guess at the unknown value, and then refining it in successive approximations until the error in the rule falls below an acceptably small limit. This process is called iteration. (Technically speaking, TK's Iterative Solver uses a modified Newton-Raphson method.) The problem can be presented to the Iterative Solver by making "rate" a guess variable and assigning it a guess value. This is easily accomplished with one step: * Go to the Status (St) field of "rate", then press [G] 4 Note that a G appeared in the Status field indicating that "rate" is now a guess variable; also, the last value held by this variable reappeared in the Input field as a guess value. (You could enter a different number in the Input field, but the last value should give the Iterative Solver a good start since it cannot be too far from the correct answer.) Watch the screen to observe the quick progression of iteration steps, and * Press [F9] to solve. Success! Expressed as a decimal fraction per month, the interest rate which we should look for is .00981224. This value can be multiplied by 1200 to find the equivalent annual percentage rate. Any input field can be used as an on-screen calculator for this purpose: * Type [End][Down-Arrow][Right-Arrow] to move the cursor to an Input field on a blank row. * Enter rate*1200 The value 11.774686 is displayed in the Input field. The value may be left there, but should probably be blanked out because it will not remain consistent with later solutions: * Type [Spacebar][Enter] CONVERTING UNITS The convenience of the on-screen calculator aside, TK has a better way of handling unit conversions. Every TK variable has two optional attributes, the CALCULATION UNIT and the DISPLAY UNIT. As the names indicate, TK performs all calculations with the values in calculation units, and displays the values in display units. In many TK applications the issue of units may be ignored altogether, and all the input and output values may be treated as dimensionless. However, if the units matter (as in the loan model), they have to be declared and their conversions defined. The calculation unit may be assigned to a variable by entering its name in a blank Unit field. The calculation units must be consistent with the usage of the variables in the equations. For instance, if we have a rule Area=Width*Length , we shouldn't assign calculation units of Area as acres, Width as yards and Length as miles. To declare the calculation units in agreement with our loan formula: * Enter mo (for months) in the Unit field of "term" * Enter df/mo (for decimal fraction per month) in the Unit field of "rate" At this point mo and df/mo are the display units as well, the values of "term" and "rate" are displayed in these units. We may change the display unit of "rate" to %/yr: * Enter %/yr 5 The value of "rate" did not change except for appending a question mark (?). This indicates that the information needed for a conversion from the calculation unit (df/mo) to the newly entered display unit (%/yr) was not availale. Unit conversions in TK are performed based on information in the Unit Sheet, which is empty when the TK program is loaded. Our goal is to make it look like this: ==================== UNIT SHEET ===================================== From----- To------- Multiply By-- Add Offset------------------------- yr mo 12 df/mo %/yr 1200 To bring the Unit Sheet up in the bottom window: * Press [;] * Press [=] * Press [U] Note: The Select command (=) and the Slash command (/) both display option menus. A choice can be made either by pressing the first letter of the desired option, or by moving the cursor over the desired option and pressing [Enter]. First, to define a conversion between annual percentage interest rate and monthly interest rate as a decimal fraction: * Type df/mo in the From field and press [Right-Arrow] * Type %/yr in the To field and press [Right-Arrow] * Type 1200 in the Multiply By field and press [Down-Arrow]. Did you notice that upon entering %/yr the question mark in the Output field of the variable "rate" disappeared, and upon entering 1200 the value got converted to 11.774686 as expected? Next, to define a conversion between years and months, we can go from right to left: * Type 12 in the Multiply By field and press [Left-Arrow] * Type mo in the To field and press [Left-Arrow] * Type yr in the From field and press [Enter] Let's replace the Unit Sheet in the bottom window by a 'copy' of the Variable Sheet, and convert the value of "term" to years: * Press [=] * Press [V] * Enter yr in the Unit field of "term" The unit and value of "term" changed automatically in both windows. 6 Every TK variable has its own Variable Subsheet with fields detailing the characteristics of the variable, including both Display Unit and Calculation Unit fields. The Calculation Unit field in the Variable Subsheet may be used for changing the calculation unit. ACCESSING A VARIABLE SUBSHEET Use the Dive command > to dive from the Variable Sheet to the Variable Subsheet for "rate": * Place the cursor anywhere on the row containing the variable "rate" * Type > The lower window should now look like this: ==================== VARIABLE: rate ================================= Status: First Guess: Input Value: Output Value: 11.7746862535996 Display Unit: %/yr Calculation Unit: df/mo Comment: Note that the value for "rate" is displayed on the Variable Subsheet in the default numeric format with 15 significant digits. (If you cover the value on any sheet or subsheet with the cursor you can read the full internal representation with up to 16 significant digits on the Status Line at the top of the screen.) To observe the interconnection between the Variable Sheet and the Variable Subsheet for "rate": * Enter df/mo in the Display Unit field of the Variable Subsheet for "rate" Note that the value of "rate" in both windows immediately changes from 11.77... to .009812...; to change it back * Enter %/yr (in the same field) The Variable Subsheet may be used for the assignmend of the so-called FIRST GUESS. To assign a first guess value for the variable "rate": * Enter 10 in the First Guess field. This establishes "rate" as a guess variable whenever it is not assigned an input value or cannot be evaluated by the Direct Solver. Having assigned a default guess value in the First Guess field on a Variable Subsheet, we are relieved of the chore of typing a G in the Status field every time we want to solve a new problem. In this model, the value of 10 assigned as the First Guess value for "rate" is a good starting point for any practical situation. 7 Let's try another problem: What interest rate would you have to find in order to pay off the loan at $350 per month in only 3 years? * Press [;] to switch the cursor to the Variable Sheet * Enter 3 in the Input field for "term" * Press [F9] to solve. You would need to find a financial institution offering an interest rate of less than 3.2 percent per year. Good luck. SAVING, RESETTING AND LOADING The current model may be saved to a disk file as follows: * Press [F4] (this function key is a shorthand for the command sequence /SS) * Enter loan1 in response to the prompt for a filename. TK usually should be reset before loading another model, although it is possible to append a new model onto a current model by loading without resetting first. To reset all sheets: * Type /RAY (for Reset, All, and Yes to confirm) Now load in a new model: * Press [F3] (shorthand for /SL) Note that TK remembers the last-used filename and displays it on the Prompt/Error line (second line of the screen). This filename may be selected by simply pressing [Enter]. It may also be edited -- to select LOAN without the "1" at the end, you could press [Down-Arrow] [Backspace] [Enter]). Also, you can type the filename anew or invoke the display of a Disk Index by entering a drive designator and/or a path specification and/or a filename containing wildcards. An empty filename invokes the display of TK model files in the current directory: * Type [Spacebar] [Enter] To select the model LOAN: * Move the cursor to the row containing the filename LOAN (not LOAN1, which was just saved) and press [Enter] The model LOAN is the same as the model just saved except that comments have been added and all variables have units. Comments are very useful for model documentation. The Comment fields in the Variable Sheet are usually used for descriptions of the variables. Note that comments may be placed on the Rule Sheet even though there is no separate field for them. Anything after a double quote mark (") in the Rule field is ignored by solvers, so a comment may follow a rule on the same line or may have a line by itself. 8 WHAT TO DO IF AN ERROR OCCURS An error will occur if you attempt to enter a syntactically incorrect rule or if an entry is for some reason invalid for given field. The error message displayed on the Prompt/Error line will usually provide sufficient cue for correcting the error and going on. Errors may also occur during solution because the model setup or the assigned input values led to contradictions in rules or to infeasible operations, such as division by zero, or evaluation of a function outside its definition domain (e.g. taking square root of a negative argument). In these cases an error mark, i.e. a 'greater than' symbol (>), will appear in the Status fields of affected rules on the Rule Sheet and related variables on the Variable Sheet. When an error mark in the Rule Sheet is covered by the cursor, a message indicating the nature of the error and suggested remedial action is displayed on the first line of the screen, the Status Line. Pressing [F1] while an error message is displayed will bring up a Help screen related to the error condition. If an error occurs on attempted entry, or if you start editing an entry and change your mind, the previous contents of the field can be restored by pressing [F2]. [F2] will also cancel any menu-based command if it has not yet been executed, i.e., if a menu is still on the screen. FURTHER EXPLORATION OF FREETK This tutorial is necessarily brief and has therefore been focused at a step-by-step instruction for using the most important commands, and discussion of some basic principles of model design, problem formulation, and model resolution. The commands used in TK are, in the main, self-explanatory thanks to the option menus displayed when a command is issued. The Help file contains further information on commands, built-in functions, special function keys, syntax, etc. To access the Help file: * Press [F1] * Press [I] to display the Index. Use the [PgUp], [PgDn], [Up-Arrow] and [Down-Arrow] keys to move through the index and highlight a topic of interest, then press [Enter] to display information about the selected topic. Additional useful information may be found in the abridged TK Solver Reference Card in the REFCARD.TXT file provided with FREETK. You also may explore sample models included in the FREETK package: LOAN The simple loan analysis model used in this tutorial. MORTGAGE An expanded loan analysis model to handle mortgages. CARPET Calculating length of carpet or linoleum left on a roll. 9 LADDER Solving the classic problem of finding the width of an alley given the crossing height of two ladders leaning against buildings on opposite sides of the alley. LINEAR4 Solution of 4 equations in 4 unknowns, the maximum possible in FREETK if coefficients are given variable names. LINEAR8 Use of fixed coefficients on the Rule Sheet to solve for 8 equations in 8 unknowns within the FREETK restriction of 16 lines on the Rule Sheet and 32 lines each on the Variable Sheet and Unit Sheet. LINREG Linear regression model. SHAFT Torsion and twist in a cylindrical shaft. CIRCUIT DC circuit analysis. POWFACT Use of complex numbers to calculate power factor correction. GEAR Calculation of various parameters in gear design. When loaded, these models have a Variable Sheet with a typical setup of known and unknown variables awaiting a solution. After examining the whole model to see how it is structured, press [F9] to solve. As was demonstrated in this tutorial, you can then run new solutions after altering the arrangement of known and unknown variables and/or changing values of input variables. The main purpose of FREETK is to give you a taste of rule-based programming applied to numeric computation. TK Solver Plus contains many additional features such as: - lists of values and list solving, - user-defined functions, - procedural language capability, - high resolution graphics, - tabular interface including spreadsheet-like interactive tables, - numeric formatting, and - interface with other programs. A more detailed description of the features of TK Solver Plus is in the FTKINTRO.TXT file in the FREETK package. This file also contains information on the $25.00 "FREETK follow-up package", which includes a diskette with 100 TK models as well as "The TK!Solver Book", and on a special offer of the full TK Solver Plus. If you have any comments or questions, or would like to place an order, call or write us at Universal Technical Systems, Inc. 1220 Rock Street Rockford, Illinois 61101 1-800-435-7887 (toll free) 1-815-963-2220 in Illinois 10