The EQC Handbook

Jan Rheinländer, 28.01.2010. This handbook describes EQC Version 1.4.0

Introduction

The LaTeX Equation Compiler is a preprocessor for LaTeX files that enables numeric and symbolic calculations. It reads equations specified by special keywords in the LaTeX file and uses them to calculate the numeric value of variables. Symbolic calculation capabilities are also implemented, for example, adding two equations or substituting a variable with a numerical or symbolic value into an equation. EQC makes use of the GiNaC library.

The development of EQC was prompted by a problem which I often encountered doing calculations in my profession as a mechanical engineer. I would first begin writing out the problem on paper, putting together the necessary equations, and then turn to a spreadsheet to do the actual calculations. EQC is meant to integrate this process in a single Latex source file.

Programming language: C++, bison, flex. Implemented on Linux-i386. Cross-compiled to Windows, but not extensively tested there.

EQC makes use of the GiNaC library for numeric and symbolic calculations, and of course needs a Latex installation to be useful. If you wish to use physical units, the SIunits.sty package is required as well.

Changes

All code changes are documented in the source files by three asterixes (***) and the change number.

History of changes

Installation

EQC is hosted at SourceForge.

How to obtain EQC

You can download binary and source packages from the EQC project page.

Requirements

To use EQC, the GiNaC, CLN and GMP libraries are required (not for the Windows binary). Information about these libraries can be found at the GiNaC library homepage and CLN library homepage. Of course, a Latex installation is necessary, and the SIunits.sty package should be present if you wish to use physical units in your equations.

Installation on Linux

Use the binary packages in .deb format

Installation on Windows

Unpack the corresponding zip file and sort the files into your favourite directories:

eqc.exe must go somewhere into your path (e.g. C:\WINDOWS\system32\)
eqc.sty, units.tex, substitutions.tex and mathconstants.tex must go into the appropriate directories of your LaTeX distribution (e.g. ...\tex\latex\eqc\). Don't forget to run texhash afterwards so that the files will be found
HTML documentation is in the docs subdirectory
Usage examples are in the examples subdirectory
Depending on your TeX distribution, you might also have to install the siunits and fp packages. The first is mandatory, the second can be disabled if you comment out the makepspicture macros in eqc.sty.

The search path to eqc.sty is compiled into the eqc binary. To adapt the path to your local installation, you should add a command

\eqcoptions{path="\path\to\where\you\put\eqc.sty\"}

before the first EQC commands.

If you want to look at the docs and examples on Windows, you might have to change the pathnames of the \input statements to fit your directory structure.

In a normal document, you should always include the following EQC files:

% in the preamble
\usepackage{eqc}
%
% soon after \begin{document}
\input  mathconstants.tex
\input  units.tex

These files are essential for EQC to function properly. Only very special cases would warrant not including these files.

Using EQC with xemacs auctex mode

In xemacs, choose Options-Advanced (Customize)-Group from the menu, and enter the group name auctex. Open the Command group, and under List:, add the following entry:

   [INS] [DEL] Name: EQC
               Command: eqc %t; %l "%(mode)\input{%s.eqc}"
               How: [Value Menu] TeX-run-LaTeX
               Create a process for NAME using COMMAND to format FILE with TeX.
   Create a process for NAME using COMMAND to process FILE. *
               Return the new process.
               Prompt: [Toggle]  off (nil)
               Modes: [Value Menu] Set:
               * Plain TeX
               * LaTeX
               * DocTeX
               * ConTeXt
               * Texinfo
               * AmSTeX
               Menu elements:
               [INS] [DEL] Lisp expression: :help
               [INS] [DEL] Lisp expression: "Run EQC, then LaTeX"
               [INS]

Choose save from the top of the buffer. To run EQC, followed by LaTeX, hit Ctrl-C twice in the buffer, and when asked for the command to run, say eqc (just typing "e" usually is sufficient)

Compilation and installation

Refer to the Detailed compilation instructions.

Bugs

Known bugs

These are not really bugs, but they might seem so
- The former unit \l was removed because it collides with a letter in the Polish alphabet. Use \litre instead. This can lead to weird errors if you don't change it!
- If your \makepspicture graphics fail because the equations do not resolve to numerics, add a second \val statement to them. This became necessary with the introduction of symbols that represent matrices.

The option eqsplit must be the last one in a list, for example: \eq[eqsplit=2; eqraw=true]{a + b = c} will not work correctly, but \eq[eqraw=true; eqsplit=2]{a + b = c} will. The reason for this is that eqsplit takes an expression as an argument, and the definition of an expression allows for a list separated by semicolons. Therefore, an ambiguity occurs.
The number 0.012345 is not rounded correctly to 4 digits (precision type fixed_digits), rather the result ist 0.1234. This appears to be a bug in the cln::round1() function because 1234.5d0 is rounded to 1234, but 1234.56d0 is rounded to 1235! Actually, it is not a bug, but a feature. The CLN documentation says (!) round(x): The integer nearest to x. If x is exactly halfway between two integers, choose the even one.

Reporting bugs

Please report all bugs to the author's email. You should include the following information:

Version of eqc, how you obtained it (RPM, CVS, binary or source).
The input file that produces the errors.
The output produced by eqc (on screen and in the file inputname.eqc).
Try setting DEBUG to larger values to get more debugging output by adding \eqcoptions{debug=4} at the beginning of your file. For Linux, you can also call eqc with -d<number>. Larger values than 4 are possible, but might give too much detail.

Usage

General Usage

EQC reads LaTeX files from the command line and writes its output to corresponding .eqc files. One output file is generated for each file given on the command line. Note that files included with \input directives are directly included in the output file. EQC keywords contained in the input files are processed, everything else is written out unchanged. The resulting .eqc files can then be processed like any regular LaTeX file (don't forget to give the .eqc file extension to latex).

An auxiliary package needs to be included with \usepackage{eqc}. It takes an optional argument english or german which defines how numbers are read (whether a comma or a point is expected as the decimal marker). English is the default.

Inside the Latex file, equations can now be defined and registered. EQC will read the equation, produce Latex output, and store it for later manipulation or evalution. For example:

   \documentclass{article}
   \usepackage{eqc}
   \begin{document}
   \input mathconstants.tex
   $$\eq[eq:myequation]{x = a \sin(b)}$$
   $$\eq{a = 3}$$
   $$\eq{b = 3.141/2}$$
   $$\printeq{"eq:myequation"} = \val{x}$$
   \end{document}

This would produce the following Latex output (without the preamble created by including mathconstants.tex):

   $$x = a sin(b)$$
   $$a = 3$$
   $$b = 1.57$$
   $$x = a sin(b) = 3$$

In order to determine the value of the variable x, EQC automatically uses the three equations that were registered with the keyword \eq. Note that only equations that have in this way been explicitly registered with EQC will be used! Any other equations present in the file are ignored. To see what else is possible in EQC have a look at the example and the reference section.

Physical units

Because EQC was developed to tackle mechanical engineering problems, it supports physical units. The Latex side is handled by SIunits.sty, which needs to be present on your system (it is included, for example, in the tetex distribution). Units inside equations are designated by their Latex macro names, e.g., \mm. Variable values can take on four different forms:

A numerical value, like 4 or 3.141.
A unit, like \mm
A physical quantity, that is, a united and a number, like 4 \mm. This form of course includes the first two ones.
Any other kind of mathematical expression, like x + 4 \mm. This of course includes the other three forms.

The \val keyword used in the example above prints the fourth kind of variable value. If we had wished to ensure that a numerical value is printed, we would have used \numval. EQC will then print a warning if the value of the variable does not have this form.

Library of substitutions

The file substitutions.tex contains a growing library of equations that are useful for working with symbolic equations, for example, \sin(\alpha + \beta) = \sin\alpha \cos\beta + \cos\alpha \sin\beta or \sin(\pi - \alpha) = \sin\alpha. By substitution, they can be adapted to special cases:

   $$\eq{\cos\phi = \sin(\phi + \psi)}$$
   $$\eqsubst{"prev"}{"lib:trig:sina+b"}$$

which would produce the following output:

   $$\cos\phi = \sin(\phi + \psi)$$
   $$\cos\phi = \sin\phi \cos\psi + \cos\phi \sin\psi$$

Formatting of floating point numbers

There are several options available to control how floating point numbers are printed. The precision can be set to a specific number of digits with \eqcoptions{precision = 'num'}.Two different concepts of precision are implemented, these can be selected by \eqcoptions{precision_type = fixed_marker} or \eqcoptions{precision_type = fixed_digits}.

Fixed marker: All numbers are printed with a fixed number of digits after the decimal marker. For example, let the precision be three digits. Then 1.2345 will be printed as 1.235, and 1234.5678 will be printed as 1234.568.
Fixed digits: All numbers are printed with a fixed number of digits precision. For example, let the precision be three digits. Then 1.2345 will be printed as 1.23, and 1234.5678 will be printed as 1230.

Very large and very small numbers should be printed in scientific format (mantissa * 10^exponent) for the sake of readability. The limits which determine what a "very large" or "very small" number is can be set with \eqcoptions{scientific_limit_low = 'num'} and \eqcoptions{scientific_limit_high = 'num'}.

Formatting of equations

Using the command \eqcoptions{eqraw = true/false} in you Latex input file makes it possible to choose whether \eq statements should be formatted the way you typed them or whether EQC should use it's own output function to format them. Note that any equations obtained by \eqadd etc. will always have the EQC formatting, as EQC can hardly foresee what you would have typed if you had written this equation yourself.

EQC formats equations inside certain environments (eqnarray, align etc.) automatically, that is, the correct number of ampersands (&) is added before/after the equal sign. You can override the formatting by setting the eqalign option manually.

Reference

Refer to the Reference section.

Examples

The EQC tour gives an overview of EQC functionality. It was created with the following commands on the source file eqc-tour.tex:

   eqc eqc-tour.tex
   latex eqc-tour.eqc

If you do not have a DVI viewer installed, try the eqc-tour.pdf produced with pdflatex. In case you are curious what your Latex source looks like after EQC has had a go at it, have a look at the intermediate file eqc-tour.eqc

Questions and Answers

Why are my files full of errors after an upgrade of EQC?

The former unit \l was removed because it collides with a letter in the Polish alphabet. Use \litre instead. This can lead to weird errors if you don't change it!

In the code below, why doesn't the value of P_comb get substituted when I say \val{P}?

 \eq[eq:Plive]{P_L = \unit{1500}{\kN}}
 \eq[eq:sello]{H = \unit{2}{\m}}
 \eq[eq:Pcomb]{P_{comb} = H L^2}
 \eq[eq:Ptot]{P = P_L + P_{comb}}
 P_{comb} & = & \val{P_{comb}}\\
 P & = &\val{P}

P_comb ist not substituted by \val because it has no numerical value. You need to tell EQC more exactly what it should do, e.g.:

 \eqsubst*{"eq:Ptot"}{P_{comb} = \val{P_{comb}}}
 \eq[eq:Ptot_]{P = \val{\rhs{"prev"}}}

My \makepspicture graphics fail because the equations do not resolve to numerics

Add a second \val statement to them. This became necessary with the introduction of symbols that represent matrices.

Why is the spacing between numbers and units ugly?

For input equations, this happens when you use \eqcoptions{eqraw = true}. EQC then tries to preserve your original formatting as much as possible (because automatic formatting is not always as beautiful as it should be). You can set eqraw = false either globally or locally

\eq[eqraw = false]{a=100\mm}

or provide the formatting yourself

 \eq{a=\unit{100}{\mm}}

For calculated results, you can control your spacing by passing options to the SIunits package. EQC simply uses the \unit macro to display physical quantities.

Why is the spacing between units ugly?: See above
How do I calculate something like 2+2 in EQC without definition of corresponding variables?: Just use \val{2+2}. You can put anything you like into a \val command, and EQC will try to reduce it to a numeric value.
EQC writes a lot of messages to the system console, which slows down compilation.: This can be changed by setting the debug level: For example, \eqcoptions{debug=-1} will silence EQC almost completely. Higher values up to 13 will make it more verbose. For Unix platforms, you can also use the command line argument -d or --debug=. However, that when something goes wrong, reading the console output is very useful to find problems.
Why doesn't substitution of x^2 = y work in 1/x^2?: This is a problem with GiNaC's canonical format of expressions. Your equation will be represented as x^(-2), so you need to substitute x^(-2) = 1/y. This is perhaps more of a bug than a feature, but difficult to solve without manipulating GiNaC's internals.
How do I get EQC to accept a variable name like \varphi'?: This is not possible at the moment, but you can circumvent the problem by defining a new macro, e.g. \newcommand{\varphis}{\varphi'}.
EQC complains about a wrong number of arguments for a self-defined function: Probably you did something like:

\function{x}{y; z} 
$\eq{a = x b + c}$.

Because functions have precedence over multiplication, EQC parsed this as a = x(b; and then complained about the missing second argument. EQC does not require function arguments to be enclosed in brackets, so you can write \cos\alpha instead of \cos{\alpha}. There are several ways to solve your problem:

Provide a multiplication symbol: x \cdot b
Use brackets: {x} b
Provide function arguments x(y;z) b

EQC does not use my library functions for finding variable values: This is not a bug, but a feature: Library functions are assumed to be generic and must be adapted to the special purpose you have in mind. For details, see the HTML documentation. Basically, you need to 'activate' the equation with either \eq{"lib:myeq"} or something like \eqsubst{"lib:myeq"}{x = x_1; y = y_1}.
How do I use bibtex with EQC?: Just run bibtex on the original TeX file, not on the .eqc file.
Why do my equations look ugly?: EQC's formatting algorithm is far from perfect. In fact, it will never become perfect because different people have different ideas about what a properly formatted equation should look like. You can alleviate this problem by using the \raw statement. This means that the contents of your \eq statements retain the original formatting. Of course, this option does not work with equations obtained by \eqadd etc. as there is no original formatting. After all, EQC is designed to save you the work of typing all these equations yourself!
AMS math complains about multiple labels: AMS math puts out an error message like Error: Multiple \label's: label '...' will be lost. This error occurs (for example, inside an align environment) if you use \notag with an equation that has a label, e.g.: \eqadd[eq:1]{x = 3}{4}\notag. EQC will automatically add a \label{eq:1} when it processes the equation, and AMS math now complains that the equation has a label but should not be tagged at the same time! You can use \tag*{} to circumvent the problem. Note that the standard eqnarray environment does not produce this error.
When I try to build the package, the command ccache is not found: I use ccache because my machine is so slow... Edit eqc/Makefile.am and remove it.
The intermediate .eqc file generated from a LateX source contains a lot of empty and/or commented lines: You can use \eqcoptions{cleancomments=true} to remove comment lines (that is, lines beginning with a percent character). Other comments are not removed because sometimes they are necessary for LaTeX to process the file correctly.
Is there a 64 bit version of EQC for Windows?: No, because the underlying GiNaC and CLN libraries will not compile for that platform yet. A 64 bit version for Unix platforms should be possible to compile from source, though.

Copyright

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Main Page

Contents