# The &abakus; handbook

## What is abakus?

&abakus; is a calculator designed with computer usability in mind, as opposed to just being a clone of your desktop calculator. Instead of using your powerful computer to put a limited simulation of a calculator on-screen, &abakus; instead allows you to use your computer to its greater potential.

Enough of the metaphysics, how about an example of what I'm talking about? Let's use&kcalc;, the normal &kde; calculator program as an example, trying to calculate 3 multiplied by the sine of 50 degrees. First you would do something like the following:

1. Make sure you're in Degrees mode:

2. Then, click on the 5 and the 0 buttons:

3. You would then search for the Sin button and click it, which would immediately calculate a result:

4. Then, click the X button, and notice that there is no user feedback whatsoever. Even real calculators temporarily blank the display:

5. Then, we click the 3 button and watch as our previous result suddenly disappears. This isn't &kcalc;s fault: It has nowhere else to display the 3:

6. Proceeding boldly forward with the faith that our previous result wasn't lost, we click the = button to perform the multiplication:

Although we did get the result, this is unsatisfactory for several reasons. A computer monitor has plenty of room to display text, there's no reason why you should ever be confused about what step your calculator is about to make, or whether it remembered an intermediate result. Computers are also much more powerful than your $10 desktop calculator, so there's no reason that you should be forced to type your expression in a form suitable for your calculator. Roberto Alsina picked up on this in a rant he published, A Modest Usability Improvement

Now let's try the same thing in &abakus;, which is designed to help you with your calculating, instead of bending you to its will. As with &kcalc;, extraneous portions of the GUI have been hidden.

1. We still need to make sure we're in Degrees mode:

2. Now we can type 3sin 50, just as we'd write it on paper. Sometimes it's better to clarify things, both for reading and to clarify your intentions to &abakus;. So you can also use the parentheses to group operations like you would on paper, and the '*' operator to explicitly multiply, like this: "3 * sin (50)":

And we're all done! We even typed in the same expression two different ways to demonstrate how &abakus; will try very hard to guess what you're trying to calculate. You'll notice that &kcalc; and &abakus; both agree on the answer.

If you're still reading you've probably been sold by Roberto's argument, just as I was when I started writing &abakus;. So read on, if you want to find out all that &abakus; can do for you.

## How to use &abakus;

### Basic usage

The basic synposis is: Type your expression, and hit Enter. &abakus; will calculate the value of what you typed and display it on the screen. You can use many functions from mathematics, and even define your own functions. You can also define and use variables.

You can define your own functions in abakus. To do so, at the expression prompt, you would type something like: `set funcname(var) = expr` and hit Enter. If all went well &abakus; will simply output OK, and you'll see your function appear in the user-defined function list. Now you can use your function as normal. If you'd like to remove your function, you can either right-click on it in the user function list and select Remove Function, or enter `remove funcname()` in the expression prompt and hit Enter. Note that you don't enter the variable name in the parentheses since only the function name is needed. (The reason you still need the parentheses is because your variables can have the same name as a function).

You can also define your own variables. &abakus; comes with the basic mathematical constants pi (π) and e (Euler's Constant) defined by default. To define your own variable, at the expression prompt you would type: ``name` = `value``, or `set `name` = `value``. You will then see your variable in the list of variables. To remove your variable, either right-click on it in the list and select Remove Variable, or enter `remove varname` in the expression prompt. Notice that there are no parentheses this time. ;-)

#### Placeholder Variables

You may have noticed that when you type in expressions, &abakus; will show a value beginning with $ (such as $0) after the result. This is a placeholder variable. What happens is that the most recent result is always $0. The result directly before is $1, and so on. You may use the placeholder values in your expression to avoid having to re-type it or use the drag-and-drop. Note that there is a special variable defined called ans, which is the same as $0. In other words, whenever you want to reference the last expression's result, you can use $0 or ans.

#### Decimal Precision

&abakus; supports high-precision arithmetic using Ariya Hidayat's hmath code from his excellent calculator SpeedCrunch. You can change the displayed precision by using the View Menu, where you can select between Automatic precision, or some pre-defined precision levels. You can also select Custom precision to select your own precision (between 0-75 digits).

#### Operators

&abakus; supports all the standard operators like -, +, *, and /. It also supports both the ^ and ** symbols to mean exponentiation. Exponentiation is right-associative in &abakus;, meaning that 2^3^2 will return 512 instead of 64. (2^(3^2)). Operator precedence is performed as in mathematics as well (e.g. 2 + 3 * 2 and 3 * 2 + 2 both return the same answer). &abakus; also supports parentheses to group expressions for when the default operator precedence is invalid.

#### Functions

&abakus; has quite a few functions built-in:

- sin, cos, tan: Trigonometric functions. Supports Degrees and Radians mode.

- asin, acos, atan: Inverse trigonometric functions. Supports Degrees and Radians mode.

- abs: The absolute value of a number.

- sqrt: Square root of a number.

- ln / log: Logarithms. ln uses the "natural base", e, which log uses base 10.

- exp: Exponential. Returns e to the given power. exp(x) is equivalent to e^x.

- round, ceil, floor, int: Converts an answer to an integer. ceil rounds to the next highest integer, while floor rounds to the next lower. int simply drops the fractional part. round rounds to the nearest integer.

- frac: Returns the fractional part of a number.

- sinh, cosh, tanh: Hyperbolic trigonometric functions.

- deriv: Returns the numerical derivative of the given expression. The graphical interpretation of a derivative is the slope of the given function, at the given point. It is used like this: deriv(exp, pt). Note that since deriv takes two arguments that the parentheses are required to avoid ambiguity. For most functions, the value that deriv returns will be exact (at least within the bounds allowed by the underlying decimal representation).

## Advanced Features

&abakus; supports some features not typically seen in computer calculators.

### RPN Mode

RPN Mode is a different input method for &abakus;, designed to emulate the input style of various old calculators which are still popular. If you do not already know what RPN Mode is, &abakus; is not the best way to find out. However, I will give a brief description of it.

In RPN Mode, the calculator operates from what is called the stack. Number are always added to the end of the stack, and operators always work from the end of the stack. One nice thing about RPN (and the reason it was developed in the first place) is that RPN expressions don't require parentheses, since the order of operations is completely unambiguous.

So the way things work is that in RPN mode, you type in numbers and operators separated by spaces. For each number you type, &abakus; will add to the end of the stack. Every time &abakus; encounters an operator, &abakus; will remove the appropriate number of values from the end of the stack, apply the operator, and then place the result back on the end of the stack. &abakus; continues in this fashion until it reaches the end of your expression, and then returns whatever value is left at the top of the stack as its result.

Let's see how this works with an example:

`2 3 4 * + 2 /` would return `7`

The way that this works is that first `2`, and then `3` are added to the end of the stack. `4` is read and is also added to the end. So at this point there are 3 numbers on the stack. When &abakus; reads the operator `*`, it removes 3 and 4 from the end of the stack and multiplies them, resulting in 12. 12 is then added to the end of the stack, and the stack has 2 numbers (2 and 12).

&abakus; then reads the `+` and performs the same process, adding 12 and 2, and replacing them in the stack with 14. `2` is then added to the end, and then &abakus; performs the division of 14 by 2, leaving 7 on the stack, which becomes the final result.

You can also use functions in place of operators. For example, `pi 2 / sin` would calculate the value of sin(pi / 2).

If the stack has more than one element by the end of the expression, &abakus; will only remove the value at the end. The values left in the stack will be retained for later calculations. You can see how many values are on the stack using the special variable stackCount which appears in the Variable List while in RPN mode.

&abakus; supports a few special commands while in RPN mode, that affect the stack as follows:

- `pop`, which removes the value on the end of the stack.

- `clear`, which clears the stack completely.

The `set` and `remove` commands are currently unsupported in RPN Mode.

### Drag and Drop

You can drag and drop results to other applications. When doing so, &abakus; will construct an image for the mouse cursor which includes the text you are dragging so that you always can tell exactly what you're about to drop into an application.

Demonstration of &abakus; drag and drop Demonstration of &abakus; drag and drop

## Command Reference

Here is a brief description of the commands in the &abakus; interface.

### Menu Commands

&Ctrl;Q File Quit

- Quit &abakus;

&Alt;&Shift;H View Show History List

- If checked, &abakus; will show the list of previous results.

&Alt;&Shift;V View Show Variable List

- If checked, &abakus; will show the list of variables.

&Alt;&Shift;F View Show Function List

- If checked, &abakus; will show the list of functions.

View Automatic Precision

- If checked, &abakus; will select a precision automatically.

View 3 Decimal Digits

- If checked, &abakus; will 8 decimal digits of precision (e.g. 1 / 3 = 0.333).

View 8 Decimal Digits

- If checked, &abakus; will show 8 decimal digits of precision (e.g. 1 / 3 = 0.33333333).

View 15 Decimal Digits

- If checked, &abakus; will show 15 decimal digits of precision.

View 50 Decimal Digits

- If checked, &abakus; will show 50 decimal digits of precision.

View Custom Precision...

- This command will bring open a dialog allowing you to enter a custom precision level. &abakus; supports precision levels from 0 to 75 decimal digits.

&Alt;&Shift;C View Activate Compact Mode

- This command is a shortcut to disable the Result, Function, and Variable views, so that &abakus; shows just the input line. In this mode, the answer is given in the input line instead of the Result list.

&Alt;&Shift;L View Clear History

- This command clears the Result view.

&Alt;&Shift;D Mode Degrees

- This command causes &abakus; to treat values for the trigonometric functions as angles measured in degrees (360 degrees make up a full circle).

  The `deriv()` function will not return correct results for trigonometric functions in this mode.

&Alt;&Shift;R Mode Radians

- This command causes &abakus; to treat values for the trigonometric functions as angles measured in radians (2 * π radians make up a full circle).

  The `deriv()` function only returns correct results for trigonometric functions when in this mode.

&Alt;&Shift;P Mode Use RPN Mode

- This command enables RPN Mode.

## Limitations

There are many cool things yet to add to &abakus;. Here's a partial list of things that &abakus; doesn't support:

- Complex numbers.

- User-defined functions of more than one variable.

- Unit analysis (for example: 3 A / 1.5 ohm -> 1.5 V)

- Advanced input as in SpeedCrunch.

- Numerical integration (finding the area under a given curve).

- Graphing (? - I'll admit I'm not sure if this would be a great fit for &abakus;)

- Matrices

- Functions on lists (e.g. sin {0, pi / 2} -> {0, 1})

- Session export/import (the session is still saved/loaded automatically).

- More functions. Although many functions that aren't built-in can be simulated. For instance, to take the logarithm of x to a different base (b), you could do (ln x / ln b). And the xth root of a number is just that number raised to the (1 / x) power.

## Credits and License

&abakus;

Program copyright 2005 Michael Pyne

Original documentation copyright 2005 Michael Pyne

Docbook conversion by &J.Hall; &J.Hall.mail;

&underFDL;