Only if you're interested -- here you find some notes on Hypatia's internal workings.
On this page: Processing Input Lines, Rounding, Writing to the Clipboard, Loops, Normal Distributed Random Numbers
You do not need to know any of this to use Hypatia, but it may help to understand why certain things work the way they do.
When Hypatia processes an input line, the following lines are taken care of immediately:
Blank lines, Comment lines, the RESET command, the REPEAT command, the Q/QUIT/EXIT command.
For other lines, Hypatia takes the following steps, in this order (details regarding scripts, loops and if/then conditions are omitted here). Actual calculations are performed in steps 7 and 8.
1. Names of insert files are replaced with the contents of the files. If an error occurs, end.
2. UDEs are resolved, except for arguments of the commands del, del@, show, show@, save, save@, run, and edit. In an assign command, the first word (UDE name) is preserved. Unresolved UDE names remain in input line.
3. The input line is split into its words -- this is the stack.
4. The first word determines if it is a command or a calculation line (for exception see step 6).
5. If it is a command, it gets executed. Done.
6. If the second word is = and the first word is a UDE name, the text following = is assigned to the UDE, and the file hyin gets updated. Done. If the second word is = and the first word is a variable, this is a command that assigns a calculation result to a variable. A flag is set, and the first two words ($variable =) are removed from the stack before step 7.
7. All variables, constants and pseudo constants are replaced with their values. Control symbols at the end of the line (for accumulation, silent, and debug modes) are read and removed. From that point on, the stack contains only numbers and operators.
8. The calculation is now performed, each operator replacing 1, 2 or all numbers to its left, and itself, with the result of the calculation that it stands for (except for the pseudo operator WHISK, which only removes two numbers, and the pseudo operators A and B, which only replace themselves).
9. If the assign flag was set (step 6), the result is assigned to the variable. Step 10 is omitted.
10. If no error has occurred, the result is displayed, $ and $$ are updated, and (unless silent mode is set or in a script) the file hy is updated.
11. The file hyin gets updated even when an error has occurred, unless the line has started with an unrecognized operator, in which case it is assumed to have been a mis-spelled command.
Along with the variables (including $ and $$) and the constants PI, E and PHI, also DUP, RAND, I and ISLOOP are replaced by numbers in step 7, before calculation begins. In Hypatia's terminology, these are pseudo constants.
A and B, though, along with WHISK, make it to step 8. From the user's perspective, A and B look like variables, or maybe pseudo constants, but to Hypatia everything in step 7 is either a number or an operator. A and B are zero-argument operators, replacing themselves with the values stored by WHISK, which, unlike variables, constants and pseudo constants, are not yet known nor can be determined in step 7.
The rule says that values >= ...5, including ...5, are to be rounded up. Because of tiny inaccuracies that are unavoidable with a limited number of digits and a binary number system, it is possible that a value that should end with ...5, and is shown as ending with ...5, actually ends with ...49999999 etc., and would get rounded down. (This is somewhat related to, but independent of the "integer or not integer" issue, see page "Integer Bias".)
Hypatia's own rounding function deals with this issue by adding 1 at the 18th digit of the number that is to be rounded (except when rounding to more than 15 significant digits, in which case the position at which 1 is added is moved further back).
I see currently no reason not to use this mechanism (its general effect on results is negligible), but you can use an (otherwise) undocumented command to switch to the programming language's (that is, Phix's) built-in rounding routine:
USE STDROUND -- use standard rounding function
USE HYROUND -- use Hypatia's rounding function (default)
To illustrate the effect (texts in parentheses are notes):
? USE STDROUND (standard rounding function)
? 42.875 CBRT (cubic root of 42.875 is exactly 3.5)
= 3.5 (but the actually computed value is some 4e-19 less than 3.5)
? 0 ROUND (rounding to integer)
= 3 (rounded off, while 3.5 should be rounded up)
? USE HYROUND (Hypatia's rounding function)
? 42.875 CBRT
= 3.5
? 0 ROUND (rounding to integer)
= 4 (Hypatia's rounding function rounds up as expected, not down)
Rounding not only takes place when you use a rounding operator (ROUND or ROUNDS), but also when numbers are shown that (rightly or wrongly) have more digits than the output format permits (a maximum of 15 for non-integer values). FDEC and FDEC n use Hypatia's rounding (unless you have used the USE STDROUND command), FSCI always uses standard (that is, Phix's) rounding.
? FDEC 0 (output format is decimal with 0 digits after decimal point)
? 42.875 CBRT
= 4 (result 3.5 is rounded up, as expected)
? USE STDROUND (standard rounding function)
? = (display last result)
= 3
The actual value is still the same (unlike with the above rounding examples), approximately 3.5, but the rounding function determines how it is shown. With default FDEC format (up to 15 digits), though, the rounding method will rarely make a difference, and if, then only at the 15th digit.
Hypatia calls the Windows utility clip.exe to copy the contents of the files hy or hyin to the clipboard. This dates back to an old problem, in the days of Euphoria 3.1 -- there was a routine to write to the clipboard, and it worked fine, but after calling it repeatedly it tended to cause the program to malfunction. This was difficult to test and even more difficult to fix, and I dealt with it by warning users to use COPY only sparsely. With Phix now, the copy to clipboard routine is part of a deprecated library -- letting the operating system copy the file is clearly the safest solution, even if it looks a bit clumsy.
This is the reason, though, why not the actual result of a calculation (the value of $) but only the formatted result can be copied to the clipboard.
Some things can only be explained historically. The ability of the input editor to scroll back to earlier input lines came rather late -- before that, I added REPEAT to allow repeating a calculation or a script, and, as a rather clumsy way to edit the input, you could edit hyin before using REPEAT. Once the REPEAT command existed, the possibility suggested itself to enhance it with a loop function. That you had to perform a calculation or execute a script before repeat-looping it looked like a feature -- this way, you always made sure that it worked correctly. When your script is already well tested, it seemed needlessly cumbersome, though -- so, I added the one-line loop statement DO -- and, with REPEAT loops already in place, the simplest way to implement it was to graft it to the REPEAT command: split the input line at the :: separator, write the second part to hyin, in the first part replace DO with REPEAT, then feed it to the code that processes REPEAT, together with a flag that says it's a DO loop. Not elegant, but didn't take much effort and avoided introducing additional complexity, and it works.
Hypatia uses the Marsaglia polar method to deliver normal distributed random numbers. It produces a pair of random numbers -- to further randomize the result, one of them is chosen randomly.
To avoid extremely unlikely values of normal distributed random numbers, those that deviate from the mean value by more than 6 sigma are rejected (the probability of which is about one in a billion).
Home, Up: Appendix, Prev: Command Line Mode, Next: Release Notes