Usage

How to use iMath

The best way to learn how to use iMath is to look at the iMath-tour.odt document corresponding to your version of iMath in this folder.

Some background on numerics

Number types

There are two very different modes of numeric calculation available in iMath. As long as you use only integers and rational numbers, iMath (or rather, the underlying CLN library) will calculate exact results. As soon as you introduce floating point numbers (just writing 2.0 instead of 2 is enough), iMath will swith to approximate calculations with a precision of 17 digits (this is the default of the underlying GiNaC library). Not only the precision, but also the size of floating point numbers is limited. You can have an exponent of maximum 32 bits length.

To see the difference, enter these two expression (turn on auto-formatting): 2.0^{-10^3} 2^{-10^3} If you want to benchmark your CPU, you can increase the exponent of -10 ...

When you use VAL() or ITERATE() everything is converted to floats.

For further details, consult {http://www.ginac.de/tutorial/Numbers.html#Numbers GiNaC] and CLN.

Automatic evaluation of expressions

GiNaC does some automatic simplifications whenever you create an expression. Here are some examples: 1/15 + 3/8 -> 53/120 2^{-10^3} -> 1/1071508607186267320948... a + a -> 2 a You can see these simplifications if you turn on auto-formatting. Only simplifications that are mathematically safe are performed. For details, consult the GiNaC documentation.

Some pitfalls

The expression %e^(-710) creates a floating point overflow error (not underflow as might be expected). This is because CLN calculates it as 1 / %e^710.

There is a difference between VAL(%e)^{-10^18} and VAL(%e^{-10^18}). In the first case, the exponent gets converted to a float before doing the exponentiation, because the basis is already a float. In the second case, the exponent is an integer and stays integer - but only 32-bit integer exponents are allowed. So you get an error. You can write VAL(%e^{-10^18.0}) instead.

iMath Options

The behaviour of iMath can be changed by setting options. There are three ways of doing this

1. Globally for all documents
2. Specifically for one document
3. Specifically for one formula line

Global Options

The global iMath options are accessed through the standard Office dialog Extras-Options. They appear in the section Writer.

Include files

• Include init.imath: This should always be marked unless you know exactly what you are doing. It reads important definitions of built-in iMath functions.
• Include units.imath: This file needs to be included if you intend working with units other than the standard SI units (Newton, Pascal, etc.).
• Include substitutions.imath: This file contains a small library of mainly trigonometric substitutions. See the iMath-tour document for a usage example.
• Include further files: Here you can specify up to three files that contain definitions which you want to have available in all your iMath documents.

Formatting

• Units: Specify a list of units separated by ';' which should be used for printing physical quantities. If no such list is specified, the SI base units are used. A useful list of units for mechanical engineering might be {%mm; %N; %Nm; %Nosqmm}. The order in which the units are specified is important! Simple units should be specified first, more complex ones later on. The reason is that the complex units usually imply the simpler ones, for example, N implies mm because 1 N equals 1 kg m/s^2.
• Precision: Specify what precision should be used for printing floating point numbers. The precision is the number of digits printed, more digits are rounded away. The precisions is 4 by default.
• Fixed point notation: This option influences the interpretation of the precision. If floating point numbers should be printed with a fixed number of digits after the decimal marker, choose this option. Otherwise, a fixed number of significant digits, not counting leading zeros, will be printed (this is the default behaviour).
• Automatic formatting: Specify whether iMath should do automatic formatting of your input equations. By default this option is turned off, meaning that the equations are printed exactly as you typed them in. This of course is only possible for original equations, not for equations obtained by symbolic operations.
• Automatic alignment: Specify whether iMath should automatically align multi-line formulas at the equation symbol. Consecutive formulas must be merged (e.g. using the context menu) for this option to have any effect.
• Automatic chaining: Specify whether iMath should omit the left hand side of an equation in multi-line formulas if it is identical to the previous line's left hand side. Consecutive formulas must be merged (e.g using the context menu) for this option to have any effect.

Miscellaneous

• Automatic recalculation: Specify whether iMath should automatically recalculate the formulas in your document when you change a formula. This is the default behaviour. Turning this option off should only be necessary if you have a very long document with very long recalculation times, or if you have a lot of errors in your formulas...
• Debug level: If you start iMath from a terminal (Linux), then you will see a varying amount of information about the formula compilation process, depending on the value of this unit. In Windows, the output will be sent to a file called stdout.txt in the directory where the Office binary is. Values for this option between zero and three produce a sensible amount of output, more is possible but usually not helpful. A value of -1 turns off practically all output.
• Fix duplicate equation labels: When you copy-paste an iFormula, you will get an error message about a duplicate equation label. You can turn this message off and have iMath assign a numeric label automatically.

Document-specific options

The document-specific options are accessed through document properties File-Properties-User defined properties. Note that because of a bug in Office, a new document does not show any user-defined properties until it has been saved and re-opened once.

All options listed above in the sections "Include files" and "Formatting" are available here, plus the following:

Formatting

• Automatic vector size: When you create a vector using the colon syntax (x = 1:10), this value is the number of elements created.
• Differentials notation: Specify how differentials should be printed: With an apostrophe after the variable name (f'), with a dot on top of the variable name (dot f) or as df/dt.
• Exponent: Specify a default power of 10 for printing large numbers.
• Equation line break point: Not implemented yet.
• Equation line break text: Not implemented yet.

Miscellaneous

• Inhibit underflow exception: By default iMath will suppress floating point underflows and return the value "0". You can turn this off and get an error message instead.
• Master document URL: Specify a master document. The formulas in this document will be compiled before the formulas in the current document. This is useful if you break up a large document using the master document functionality of Office.
• iMath version: The last version which this document was saved under. DONT CHANGE! Required to migrate documents created in older versions.

Formula-specific options

The formula-specific options can be accessed through the context menu (this is the preferred way) or by editing the formula text (see Reference#Options for details). All options listed in the sections for global and document-specific formatting can be set here.