Usage: Difference between revisions

From iMath
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 3: Line 3:
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  [http://sourceforge.net/projects/ooo-imath/files folder].
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  [http://sourceforge.net/projects/ooo-imath/files folder].


== iMath Options ==
Usage with Impress is very similar to usage with Writer. The main difference is that Math objects in an Impress document cannot be anchored in any specific order. Therefore, the recalculation order of the iMath formulas inside each Impress page is defined by the object names. The object names can be set in the context menu (Properties) or in the Navigator. The user is responsible to name the Math objects in such a way that calculation will happen in the desired order.


The behaviour of iMath can be changed by setting options. There are three ways of doing this
== Some background on numerics ==
# Globally for all documents
# Specifically for one document
# Specifically for one formula line


=== Global Options ===
=== Number types ===


The global iMath options are accessed through the standard Office dialog Extras-Options. They appear in the section Writer.
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 switch 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.


==== Include files ====
To see the difference, enter these two expression (turn on auto-formatting):
* 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.
  2.0^{-10^3}
* Include units.imath: This file needs to be included if you intend working with units other than the standard SI units (Newton, Pascal, etc.).
  2^{-10^3}
* Include substitutions.imath: This file contains a small library of mainly trigonometric substitutions. See the iMath-tour document for a usage example.
If you want to benchmark your CPU, you can increase the exponent of -10 ...
* 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 ====
When you use VAL() or ITERATE() everything is converted to floats.
* 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 <code>{%mm; %N; %Nm; %Nosqmm}</code>. 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, <code>N</code> implies <code>mm</code> because <code>1 N</code> equals <code>1 kg m/s^2</code>.
* 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 ====
For further details, consult [http://www.ginac.de/tutorial/Numbers.html#Numbers GiNaC] and [http://www.ginac.de/CLN/cln.html#Ordinary-number-types CLN].


* 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...
=== Automatic evaluation of expressions ===
* 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 ===
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 [http://www.ginac.de/tutorial/Automatic-evaluation.html#Automatic-evaluation GiNaC documentation].


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.
=== Some pitfalls ===


All options listed above in the sections "Include files" and "Formatting" are available here, plus the following:
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.  
==== Formatting ====
* Automatic vector size: When you create a vector using the colon syntax (<code>x = 1:10</code>), 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 (<code>dot f</code>) or as <code>df/dt</code>.
* 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 ===
There is a difference between VAL(%e)^{-10^18} and VAL(%e^{-10^18}). In the first case, the exponent is 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.


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.
== iMath Options ==
 
The behaviour of iMath can be changed by setting options. There are three ways of doing this
# Globally for all documents from the Tools - Options - LibreOffice Writer - iMath global defaults dialog
# Specifically for one document from the [[Document settings|iMath - Settings]]
# Specifically for one formula line with the keyword [[OPTIONS]]

Latest revision as of 19:11, 15 November 2020

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.

Usage with Impress is very similar to usage with Writer. The main difference is that Math objects in an Impress document cannot be anchored in any specific order. Therefore, the recalculation order of the iMath formulas inside each Impress page is defined by the object names. The object names can be set in the context menu (Properties) or in the Navigator. The user is responsible to name the Math objects in such a way that calculation will happen in the desired order.

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 switch 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 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 is 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 from the Tools - Options - LibreOffice Writer - iMath global defaults dialog
  2. Specifically for one document from the iMath - Settings
  3. Specifically for one formula line with the keyword OPTIONS
Retrieved from "http://ooo-imath.sourceforge.net/wiki/index.php?title=Usage&oldid=808"