EQL+

Equation library for the HP49G/49G+

EQLplus (internally EQL+) arose from the famous 48 equation library. It runs on both, the 49+ and the 49, though less fast on the latter. EQL+ is user expandable as described below. It has two command only, SBox (Standard Box).which is the classical equation browser, and UBox which looks for a global variable 'UsrBox'. Don't worry if UsrBox isn't found, SBox is very rich. It has various sub-browsers each of which has other sub-brouwsers containing hundreds of equations and explaining pictures from various fields in science and engineering. The HP48 AUR (Part 4, Equation references) contains a closer description of most equations. Besides data collection,  you may solve either the equations of the original equation library or your own ones. Load the library EQLplus, best with Conn4x, store it port 1 or 2 and attach as usual with a warmstart. This also adds the choice EQL+ SOLV to the NUM.SLV box on RS [7] as item 7, see below under SOLV. Item 7  is usable independently on equation browsing. Just open NUM.SLV and choose it. EQL+ is tested in ROM 1.23 on the 49+ and in ROM 19-6 on the 49.

Attention. UsrBox has a simplified syntax. Read Section Customization again and update your UsrBox correspondingly. If you had a UsrBox from EQLplus.zip of a version older than 10.2004, load the new one.


What is new?

Version 1.2005. Solver behaviour improved by fixing the header bug affect in ROM 1.23,  see Appendix.

Version 10.2004. User customization in UsrBox radically simplified. No tagging anymore.

Version 9.2004. Step-by-step multiple equation solver assigned to RS_hold [7]. Option quit added to the browser menu.

Version 8.2004. Equation selector menu reorganized. Solver functionality improved. Item 7.EQL+ SOLV appends itself to the  NUM.SLV choose box to support equation solving independently on equation browsing.  

Version 7.2004. Bug in the current divider equation and in the GASES browser fixed. Equation selector menu slightly modified. The spring-mass system animation returned to life. Moreover, the user can make his own animations in UsrBox. 

Version 6.2004. Format of descriptions in UsrBox simplified. No empty screens anymore for small descriptions. Option VIEW for viewing long equations added to the equation selector's menu. 

First Release: May 2004, version number 5.2004. Library number 310. Size of  last version 36.7 kB. 

Abbreviations: RS = RightShift, LS = LeftShift, is the LeftArrow key. Similar symbols denote the other arrow keys.


The two commands may either be assigned to keys (best to dispensable shiftholds) or integrated in the APPS box provided you have Appsman (you should!).The standard equation browser in science and engineering Simply add the command SBox to the reserved variable APAR. If putting it on top, it will appear on top of the APPS box. That's it.You may also add the list { EQL+ 310 MENU } to APAR to set both EQL+ commands. Assume SBox has been pressed. Then appears the Standard Box browser shown in screen-shot where Oscillation has been selected. The arrow keys and are browsing through the items while RS and RS jump to the begin or the end of the screen. Menu option go (or ENTER) sets a selection while go (or CANCEL) returns to the previous browser or leaves it if there is no predecessor. Option quit quits equation browsing from anywhere. In sub-browsers with a many items you may use the ALHA key and the first letter to find an item. For instance, to find Toroid Inductance in the long browser Electricity press T after ALPHA. Don't forget to turn off the ALPHA mode before entering a selection as the browser might think that you are still searching.

After pressing  go on Oscillation let's choose the subsection Mass-Spring system. It has no subsections anymore and jumps directly into a screen at left below which is an example of an equation selector. In our example you see the 1st of 3 equations from spring mechanics. and are leafing through the equations. Some of these may contain units. But to make equation view more feasable only the unit name is displayed - for instance, T instead of UBASE(T) in the Ideal Gas Law - although SOLV below puts the original equations into EQ as long as the UNITS option from the CONST library is active (you see the original equations by pressing SOLV and then CANCEL to abort the editor). Furthermore, a menu appears whose most fascinating option is INFO. In our example it first starts an animation of the base experiment in mass-spring mechanics. The animation is stopped with EXIT and sets the screen at right, called the INFO screen for the mass-spring system. Therein, you may jump down with RS   to get a description of the variables occurring in the equations. The graphic can be stored in PICTURE with option PCT while EXIT or CANCEL return to the equation selector. The left thumb on F1 and the right thumb F6 toggle an equation with its picture. In the equation selector also some hard keys are active. How they operate is explained below the screen-shots. Each of the above environments can temporarily be turned off.

Equation selector on Oscillation/Mass-Spring system. INFO sets the right-hand screen. Press RS DownArrow in this screen  to jump to the comments

Active soft and hard keys in the equation selector

INFO display an equation's picture (if there is any) together with a description of the occurring variables. The description can scrolled in with or faster be set with RS . Jump back to the picture with RS or scroll up slowly with .
VIEW A viewer for long equations (longer than a screen width). Equation 1 in Columns & Beams/Excentric Columns is an example. In the VIEW environment, and  are scrolling, and RS / RS jump to the end/begin of the equation. VIEW has no effect if the scanned equation fits into the screen.
RCL  recall the current equation to the stack and exit SBox or UBox.
CONS Set the Constants library in order to choose between SI and ENG unit base (F1 or F2) for equation solving with or without units (toggle F3).  F1, F2, F3 affect the equations. E.g., some equations display UBASE(T) if UNIT is active (square present), and only T otherwise. Remember that the numerical value of a constant depends on the unit base. The Constants library is left with QUIT.
SOLV Store the equations of the subject in EQ. Before storíng, the equations are edited for correction and confirmation. CANCEL simply aborts and returns to the equation selector while ENTER continues with storing in EQ and then runs EQL+ SOLV from NUM.SLV. This item creates all variables from the equations in EQ as globals in the current directory with default value1. Already existing variables are not overwritten. In addition, SOLV creates the reserved variable Mpar and sets the MSOLVR menu with option ALL in it whenever EQ contains more than one equation. If EQ contains a single equation, SOLV sets the different SOLVR menu with option EXPR=. More on equation solving in the Appendix. Numerical solving needs the approx mode, in general.
EXIT or
CANCEL
Leave the equation selector and return to the category the scanned equation belongs to. EXIT  (not CANCEL) also stops a running animation while CANCEL only cancels the delay time.
STO store the original equations of  the current subject in EQ and leave SBox or Ubox without starting the solver.

 +/-

toggle normal/minifont in the equation selector, useful if an equation doesn't fit into the screen. It this does not help use VIEW.

Customization

The command UBox processes a user-made equation structure in a file called UsrBox quite similar to SBox which clearly cannot cover all branches from engineering and science. For instance, an astronomer will certainly like to generate his own equation hierarchy if nothing suitable is found elsewhere. UBox  looks in the path for 'UsrBox'. If it is found and if it evals to a list with the appropriate structure then UBox runs like SBox. There may be different UsrBox files in different directories. In other words, your equation hierarchies may even be context-sensitive. Thus, under this aspect EQL+ is much more powerful than the old 48 equation library. The general format of UsrBox is shown in the left column of the following table:

{ "Main Title"
    { "Title 1"  DAT1 }
                  •
                  •
                  •

    { "Title n"  DATn }
 }
The browser title when pressing UBox. Analog to
title "Standard Box" when pressing SBox.

"Title k" is the title of a set of equations or the name
of a sub-browser, depending on DATk.

The whole is a list of type { "String"  List1 ... Listn }. 

Clearly, the ambitious user wants to have not only equations, but also appropriate pictures and descriptive text, similar as in SBox. This is achieved by  specifying { "Title k"  DATk } by a list as follows, called a base list in the sequel:

{ "Title for equation list"  { grob "Description" }  'eq 1'   'eq 2' ....... 'eq m' }

The maximal size of the grob should be 131×56. If you don't have a grob at hand, keep its place free by the real or zint 0. This tells UBox that no picture is available and "No Picture" is displayed, similar as sometimes in SBox. And if an animation is desired like in the Mass-Spring system instead of a static picture, replace grob by a list containing at least two grobs and a real as its last list element which is the delay time in seconds between two consecutive pictures in the animation. If UBox identifies such a list, it starts its own animator. See the Simple Pendulum example below. "Description" is a string of several lines. Each line should describe a variable similar to the lower part of the INFO screen but you may also write anything else. A line should contain at most 22 characters, otherwise the line is cut off  in FONT8.

A base list corresponds to an equation selector. Thus, all members of a simplest UsrBox except its head are base lists.  But DATk in the table above can also be a sequence of base lists. In such a case "Title k" is the title of a sub-browser. Thus, UsrBox may be nested in the same sense as SBox. Remember that UsrBox need not necessarily be a list. It can be any object which evals to a list of the prescribed syntax. For instance, if this list exists on the SD-card under the name UsrBox then UsrBox in HOME should contain the program  « :3: UsrBox EVAL »For speed reason, there is no syntax checking on UsrBox. It is only verified that it is or evals to a list when existing on the path.

EQLplus.zip contains an example for down-load under the name UsrBox (must be updated with version 10.2004). If UBox is run with this example on the path,.the example browser has two entries (n=2). The 1st is just Projectile Motion from Sbox, realized by a base list. The 2nd is essentially a replica of Oscillations with several sub-browser.. Each of these corresponds to a base list. We recommend a detailled study of the example's syntax: Press UsrBox and edit the list or explode it with OBJ (or better use 3tog from OT49). For instance, the base list for Simple Pendulum look as follows:
{ "Simple Pendulum"

 
  { { grob1  grob2  0.5 }
          "L: length
           T: period
           w: angular freq
           f: frequency"
    } eq1 eq2 eq3
}
That is, VIEW first runs a 2-grob animation with 0.5_s delay, and the equation selector contains 3 equations. Actually, our UsrBox example is a program. The program itself is unknown to
UBox which simply executes the name UsrBox and then processes the large resulting list. The program is small because it extracts suitable hiddens from EQL+.    


Remark 1. Press all keys firmly to avoid an empty screen in the equation selector. If this occurs, interrupt at once with a warmstart to avoid a crash. The 49+ screen has enough room for running EQL+ together with the clock. On the 49 the clock should be turned off before starting SBox or UBox.

Remark 2. Since UsrBox is large in general, you may compress it but it must itself decompress and evalutate to a list. Self-decompressing and self-evalutating tools are available in OT49(+).      

Remark 3 for experts.  The extremely long equation 8 in Bipolar Transistors from Solid State Devices has been splitted into two equations so that there are 9 equations now. Almost all rompointers of EQL+ are compressed data, deflated with a special BZ-related unprotected decompressor which is ROMPTR 136 2. Do not try to decompress the data strings with the BZ-decompressor. The special compressor may be sent to interested programmers on request.

Credits. Modified compression is essentially based on BZ by Mika Heiskanen. We used parts of the equation library porting by James D. Purdi. Thanks to Heiko Arnemann, Carsten Dominik, Luis Morales, Otto Praxl, Stefano Priore and Hugo Rodrigues for hints, help and beta-testing.


Arnaud Amiel  amiel@chez.com       Wolfgang Rautenberg  raut@math.fu-berlin.de


Appendix - Solving equations

Equations can be solved without or with units. Numerical values of units and constants depend on the unit base choosen  with CONS from the equation selector. These modes are controlled by the user flags 60 and 61 which the operating system misuses as system flags. More precisely, flag 60 clr/set =  SI/ENG and flag 61 clr/set = UNITS active/inactive but you need not remember this. If UNITS is inactive then all equations are pre-evaluated, that is, units and occurring constants are already replaced by their numerical values before the equations are stored in EQ. It is often easier to solve equations without units and to insert the right units afterwards. But the pure numerical approach may have also some disadvantages, see below.

Equation solving starts only after one or serveral equations are already in EQ. It is the easiest to discuss this in examples. Let us first consider solving a single equation  Press SOLV in the Equation selector of the Law of Gravitation The equation solver SOLVR on the Law of Gravitation which stores this equation in EQ and sets a menu with the variables F, G, m1, m2, r in white fields, called the SOLVR menu (see also the HP48 manual chapter 18). You see the menu in the screen-shot at left. Leave the menu temporarily with VAR to see that also the current directory contains these variables now, all with default value 1. Return to the SOLVR menu with LS_hold NXT. We want to solve the equation with units for 2 small asteroids which meet in a distance of r=10_km, to see how big is the gravitation force which they exert on each-other. Gravitation force is mostly mesured in N (Newtons, 1_N equals 1_kg·m/s^2). Let's assume m1=m2=10^6 tons (not UK tons which is something else). Put 1000000_t on the stack and press the white menu field m1. Do the same for m2 and finally press the white field r on 10_km in the stack. The 3 variables m1, m2,  r are the knowns, i.e. those variables in the equation which are defined by the user and get values from him, The unknowns are the others, in this case only F because G is the name of the gravitation constant and not really a variable in this context. It will not be used in a solving process and is superflue. However, also the unknown F will be a unit and must therefore be declared as a unit, as a force unit in our case, with any dummy value for its numerical value. For instance, put 1_N on the stack and press the white F field.

Now, all necessary declarations are made for getting F. Just press LS F. This starts the solver and puts the solution on the stack, tagged with F as shown in the above screen-shot. Get rid of tag by executing OBJ or go to the VAR menu to see that the gravitation force is only 0.667259_N, perhaps less as expected. But remember that gravitation is inversely proportional to the quare of distance. Thus, if r is fed with 1_km, the force is already 1000 times bigger, namely 66.7259_N.

Not only F, but any of the occurring variables can be the unknown. Assume that on the 1st asteroid the gravitation of the 2nd asteroid is just 1_N. How big is it? Just put 1_N into F and leave the values of the other variables unchanged (r=10_km, m1=10^6_t). Now press LS m2. This results in the answer m2=1498668.4331_t. Note that is was not necessary to redefine the unit type of the occurring variables.

Important. If the solver menu is lost by some manipulation and is reset with EQL+ SOLV from NUM.SLV, the existing variables occurring in EQ are not overwritten. This also holds for multiple equation solving described below and is of great advantage for repeated solving. But this may cause troubles if solving another system and the old variables were not purged, because these may have a completely different meaning in another system.

Option EXPR= only puts the left and right side of the equation on the stack, perhaps needed in some other calculation.

We could have simplified our approach by solving the Law of Gravitation without units or constants. To do this press CONS in the equation selector before running SOLV and deactivate UNITS. If now running SOLV,  the equation

F = 6.67259E-11 · m1· m2/r^2   

is in the editor, i.e., the gravitation constant is replaced by its numercial value before it will be stored in EQ, or the gravitation law is pre-evalued as we agreed to say. Now we proceed as above, but this time pressing the white r, m1, m2 simply on the reals 10, 10^6,.10^6, respectively, leaving the dummi real 1 in F. This is obviously faster. Then LS F yields the tagged result 0.67259, i.e., essentially the same as above but with no units involved. The only problem is that we have to remember that 0.67259 is the the gravitation force in Newton and not in dyn or kips, and that it is the value in SI units, not in ENG. And finally, that the mass of the asteroids were given in SI tons, not in kg or UK tons. A single wrong key press on ENG instead of SI in CONS would have lead to the wrong result F = .332208. You see from this example how many troubles can be caused by using different unit systems.  

We now discuss a multiple equation solving example with units which is more difficult. Let's take the Mass-Spring system and solve its equations with given values for the spring constant k and mass m  A glance at the equations shows that solution for ω, T, f should exist: ω is calculated by the first equation. Then T and f are computed by the 2nd and 3rd equation. Actually, the internal solving procedure follows exactly this line, but much faster as we could do it manually. Since we want to solve the system with units, UNIT in the Constant lib should be active. The constant π is known to the system. Note that the spring constant k is not an absolut constant but depends on the spring material. It is normally given in Newton/Meter (SI unit base). As above, we first start SOLV in the equation selector to create all occurring variables with the dummy value 1. Pressing ENTER on the equations in the command line results in the screen-shot at left (from version 1.2005 on with subject title) and a 2-page menu whose first page contains all occurring variables in white menu fields together with the option ALL. To start the solving process 3 things have to be done as follows:

1. Declaring knowns and unknowns. Since we started SOLV in units, both the knowns and the unknowns must be units which fit the equations. Suppose our spring constant k is 7_N/m. Put this on the stack and press F1. This stores 7_N/m in k and menu field k becomes black. In the same way we store 0.5_kg in m by pressing the white menu key m. These two are our knowns. But also the solver must know which are the knowns and which the unknowns. For providing this information put the list { k m }on the stack and press menu option MUSER from page 2. This declares that k and m are the knowns. The unknowns are still in white fields. Our aim is the last screen below which shows the result for the unknowns ω, T, f after solving the system EQ for the above values for k and m. To get this result screen we have to procede as follows. T should be a time unit, hence put the dummy 1_s  in the stack and press T which than becomes black. As seen from equation 3,  f  must then necessarily be a frequency unit. Hence, put 1_Hz on the stack and press f. In the same way, ω as angular frequency (as seen on the INFO screen) gets the dummy 1_r/s. Now all variables are black. It still remains to tell the system that T, ω, f are really the unknowns. This is done by pressing MCALC from page 2 on  the list { T ω f }. Without any unit declaration for the unknowns or a declaration that doesn't fit the knowns and constants occurring in the equation system MCALC would error.

2. Starting the solving routine. Simply press LS ALL. A lot of messages are displayed but processing on the 49+ is so fast that these can scarcely be followed. This ends up with a modified menu in which all variables which participated in the solving process are marked with a little square. There may be other variables in the equations which were not involved in the solving procedure and don't have a square. But this is not so in our example.

3. Reading the complete solution. Simply press RS ALL. This results in the screen-shot at left.The result screen after solving the mass-spring equations with EQL+. The displayed values of the unknowns are now also their actual values in the directory. Instead of RS ALL you could also press RS . This displays the values of all variables. The screen and its menu show how comfortable equation solving can be. You may even immediately print out the solutions. It should be mentioned that the right subject title in the screen appears only from version 1.2005 on (which fixex the affect of the header bug). If the solver is started on an equation system in UBox you would see the default title "EQ".  But you can change the default into the proper subject title. Just put "Subject Title" on level 2 and the list of variables in the equations on level 1 and execute the command MITM from menu 116 (not on the keyboard). The order of variables in the list argument determines also their order in the solver menu. This all, along with the new title, is stored in Mpar.

If no solutions were found and the processing is interrupted with an error message, try again by first resetting the variables to default values by pressing ALL. This makes again white fields from the variables but the unit declarations are still present. The solver routine with its displays and menus are living in library 228. Those who want to know in detail what Mpar contains may use the error protected rompointer XLIB 228 18.

Various difficulties may occur when using the multiple equation solver. For instance, consider the equation system
x1 = v0 + a·t1
x2 = v0 + a·t2
for computing the initial velocity v0 and the acceleration a from the observed values x1, x2, measured at time t1, t2, resp. Here the knowns are x1, x2, t1, t2, and the unknowns are v0 and a. Although solutions are granted for our system, SOLV would fail because the system does not contain an equation from which at least one of the unknowns can directly be isolated. But if we add the equation x1 - x2 = a·(t1 - t2)  to the above two (it results from subtracting the 2nd from the 1st equation) then the expanded system becomes suddenly solvable with SOLV. Thus, one may say, the multiple equation solver is fast but not particularly intelligent. More on possible failures can be found
in Chapter 25 of the HP48 manual.

Multiple equation solving step by step. The single equation solver can also be used if EQ contains more than one equation for solving the equations step by step. The SOLVR menu expands by the option NXEQ when pressing RS_hold [7] provided you are in USR mode. Actually, this is realized by a key-assignment tacidly made by SOLV. Only the variables of the current equation appear in the menu when stepping through the equations with NXEQ. Unfortunately, on the 49+, NXEQ only flashes the next equation in the 49+ instead of keeping it displayed - another ugly bug in the 49+ operating system. A work-around is pressing NXT and then LS_hold NXT. This sets the menu also as the last menu.

Note that there are still the builit-in options Solve equation.. and MSLV options in NUM.SLV for single or muliple equation solving, described to some extend in the 49(+) documentation. 

End of the document