Reference section

Basic syntax

There are two categories of keywords recognized by EQC: Keywords in the Latex file, and keywords inside equation statements. The syntax used to describe the keywords is:

keyword [optarg1] [optarg2] ... {argument1} {argument2} ...

Arguments in square brackets are optional.

The following abbreviations for the different types of arguments are used:

exp A mathematical expression like x + sin(y).
equation <- exp = exp An equation created by equating two mathematical expressions.
equation <- exp & = & exp Same as before, but inside an equation array. Other positions of the & are possible as well.
equation <- "label" EQC optionally accepts an equation label in any place where an equation is required. Labels must be enclosed in double quotes. The special equation label "prev' references the last equation that was registered with EQC.
eqlist <- equation OR equation; equation; equation ... Either a single equation or a list of equations separated by colons.
unitlist <- unit; unit; unit ... A list of physical unit names like \mm;\N, separated by colons.
explist <- exp; exp; exp ... A list of expressions like x; y; z^2, separated by colons.
simplifications <- simplification; simplification; simplification ... A list of strings describing simplifications to be performed on an equation.
vector <- start : end : step A vector beginning at start and ending at end, with steps of step. If end - start is not a multiple of step, the last element of the vector will be smaller than end. If you don't care about the size of the step, give a value of 0: EQC will make the vector have the number of elements defined by the option vecautosize (default 20).
matrix <- {element1; element2; ... elementN} OR {{element11; element12; ... element1N}; { ... }; {elementM1; ... elementMN}} A vector or a matrix of arbitrary expressions. The brackets are important, but not the type of bracket. A matrix can be used anywhere an expression is allowed.

Numbers can have the imaginary unit i, which on the other hand means that you cannot use i as a variable name.

Keywords in the Latex file

Keywords for manipulating equations

All these keywords take several optional arguments. The asterisk form suppresses printing the equation. A label may be given to the equation in square brackets. In addition, all the options listed for the keyword eqcoptions can be used and will then apply for this equation only. Note that if only an equation label and no further option is provided the square brackets, the key label = can be omitted, and the label does not need to be quoted ("").

\constant [*] {equation} Registers a constant with EQC. Constants are not erased by \clearequations. This makes it possible to specify general constants only once in the file and reuse them for several different calculations. The value assigned to this constant is automatically used when calculating the value of variables. The asterix form suppresses printing of the constant equation in the Latex output file.
\eq [*] [[label]] {equation} Registers an equation with EQC. Only equations that have been registered are used to calculate the values of variables. The asterix form suppresses printing of the equation in the Latex output file. The equation can be assigned an optional label which may be used to reference it later on in the file. The Latex \ref{} command will also work with this label. Note that here the label may not be surrounded by quotes! For the special case of the equation label starting with lib:, the equation will not be erased by \clearequations. This is useful for building a library of generic equations, as for example in the file substitutions.tex.
\deleq{label} Removes an equation such that it has no influence on future searches for variable values. Note that since LaTeX does not support removing labels, the label itself will be not be re-usable!
\eqadd [*] [[label]] {equation}{expr} Adds an expression to the equation. A label may be assigned to the result. The resulting equation is only registered with the EQC if it has been assigned a label. The reason for this is that the equation is usually redundant in terms of using it for calculating the value of variables. The asterix form suppresses printing of the resulting equation.
\eqdiv [*] [[label]] {equation}{exp} Divides the equation by an expression. The asterix suppresses Latex output, the label enables the equation to be referenced later and causes it to be registered with the EQC.
\eqmul [*] [[label]] {equation}{exp} Multiplies the equation with an expression. The asterix suppresses Latex output, the label enables the equation to be referenced later and causes it to be registered with the EQC.
\eqpow [*] [[label]] {equation}{exp} Raises both sides of the equation to the power of an expression. Beware: This ignores alternative results, as in the case of \eqpow{x^2}{1/2}, which might evaluate to +x or -x. Only use this function if you are sure that you want the first possible result!
\eqfunc [*] [[label]] {equation}{exp} Applies the expression, which must be a valid function name (without parameters), to both sides of the equation.
\eqsub [*] [[label]] {equation}{exp} Subtracts an expression from the equation. The asterix suppresses Latex output, the label enables the equation to be referenced later and causes it to be registered with the EQC.
\eqrev [*] [[label]] {equation} Swaps left hand side and right hand side of the equation. The asterix suppresses Latex output, the label enables the equation to be referenced later and causes it to be registered with the EQC.
\eqsubst [*] [[label]] {equation}{eqlist} Substitutes expressions inside an equation. The eqlist argument is a list of equations separated by ';'. Any occurences of the left hand side of these equations is replaced by the right hand side. The asterix suppresses Latex output, the label enables the equation to be referenced later and causes it to be registered with the EQC.
\eqsimpf [*] [[label]] {equation}{simplifications} Simplifies both sides of the equation according to the simplifications given in a list. Possible values are:

• expand Fully expands all expressions, including function arguments.
• expandf Only expand function definition, not arguments.
• eval Numerically evaluate the equation as far as possible.
• normal Normalize the equation (see description of GiNaC normal() method).
• collect-common Collect common factors (see description of GiNaC collect_common_factors() method).
• unsafe Does unsafe simplifications, for example
  • sqrt{x^2} => x
  • \arctan\tan{x} => x. Note that the opposite \tan\arctan{x} is not an unsafe evaluation and is thus done automatically (by GiNaC).
• diff Evaluates differential function \diff.
• sum Evaluates sum functions \sum.
• gather-sqrt Gathers single square roots under one root symbol.
• integrate Symbolically integrates any integrals in the expression (if possible)

\eqsolve [*] [[label]] {equation}{exp}{exp} Solves the equation for a given variable. The last argument indicates which solution is requested (in case there are several solutions, like for a quadratic equation). The function returns an assignment for the variable.

Keywords for manipulating expressions

\lhs {equation} Returns the left hand side of the equation.
\rhs {equation} Returns the right hand side of the equation.
\val [[int]] [[unitlist]] {exp} EQC replaces this keyword with the value of the specified expression (which usually is, but need not be, a variable). EQC tries to derive the value from the given equations in the form of a physical quantity. If this is not successful, a symbolic expression will be printed instead. Any floating point numbers will be printed with an optional precision. If the quantity should be expressed in other units than those set by \eqcoptions, a list of units can be passed as an optional parameter.
\valwith [[int]] [[unitlist]] {exp} {exp} An additional list of assignments can be given to find the value. All the assignments given are registered as new equations and then the value is searched for. This is the same as doing

 \eq*[eq:temp_1]{assignment_1}%
   ...
  \eq*[eq:temp_n]{assignment_n}%
  \val{exp}
  \deleq{"eq:temp_1";... "eq:temp_n"}%

\quantity [[int]] {exp} Same as val, but an error is printed if the value of the variable is no quantity. Any floating point numbers will be printed with an optional precision.
\numval [[int]] {exp} Same as val, but an error is printed if the value of the variable is no number. Any floating point numbers will be printed with an optional precision.
\units [[int]] {exp} Same as val, but an error is printed if the value of the variable is no unit or a multiplication of several units and/or powers of units. Any floating point numbers will be printed with an optional precision.
\eqeval{equation}{equation} Evaluates the first equation to a matrix of values. The second equation needs to have the form sym = vector. The symbol is treated as the independent variable, and the equation is evaluated for all values of the symbol given in the vector. The result is a 2x2 matrix, with the values of the independant variable in the first column and the evaluation results in the second column. For example: \eqeval{y = x^2}{x = 1:5:1} would become (1;4;9;16;25)
\eqevalp{x-equation}{y-equation}{equation} Evaluate a function given in parameter form to a matrix of values. Example (the evolvent function): \eqevalp{x = R (\cos t + t \sin t)}{y = R(sin t - t \cos t)}{t = 0:90\degree:5\degree}
\numer{exp} Returns the numerator of the expression.
\denom{exp} Returns the denominator of the expression.
\diff{exp;var;num} Creates a differential of the expression with respect to var to the degree of num. It can be evaluated using \eqsimpf{exp}{diff}
\sum{equation;exp;exp} The sum function. The first equation is the lower bound, the second the upper bound, the third the expression to sum up. Example: \sum{n=1;3;n}. Note that the bounds must become integer values when the function is evaluated with \eqsimpf{exp}{sum}.
\tseries{exp}{equation}{exp} Creates a Taylor series for the first expression. The second parameter must have the form sym = number. The series is created for the dependant variable sym around number. The third parameter must be an integer defining the degree of the series expansion.
\ceil{exp}{digits} Return the numeric value of the expression, rounded up to the nearest integer with the given number of digits after the decimal point.
\floor{exp}{digits} Return the numeric value of the expression, rounded down to the nearest integer with the given number of digits after the decimal point.

Keywords for manipulating matrices

\matrix {variable} Define the variable as containing matrices. This is essential because EQC must know that this variable is non-commutative when multiplied with another matrix variable
\transpose{exp} Transpose the matrix
+ (addition) Add matrices or scalars
- (subtraction) Subtract matrices or scalars
*** (multiplication) Multiply matrices or scalars. EQC will take care of the non-commutativity of matrix products if you have declared the variable properly with the \matrix keyword
^ (raising to power) Multiply the matrix with itself as often as indicated by the exponent
\mindex{exp, row, col}** Find the indicated element from the matrix

Keywords for defining new units and functions

\defunit [*] [latexname] {macro}{exp} Defines a new unit. The macro is the name of the unit, this must begin with a backslash because a Latex macro will be created with this name for referencing the unit later on. The expression defines the unit in terms of units already known to the EQC. If this expression contains data types apart from units, powers of units, numerics, or constants already known to EQC, a warning is issued, but the unit definition is created anyway.
To suppress the generation of the Latex command for this unit, use the asterix form. If you wish the Latex macro to output something other than the expression, supply this as an optional argument. It will be printed in the mathrm font.
\function [[hints]] {name} {explist} Registers a user-defined function with EQC. The function has the arguments given in the explist. Example: \function{f}{x;y}. The function may be used in equations and expressions with or without arguments. The following hints are possible:

• lib This is a library function. It will not be erased by \clearequations.
• trig This is a trigonometric function. It will be printed as sin²x instead of (sin(x))² (for example).
• nobracket This functions needs no brackets when printed (for example, the sqrt() function).
• expand The function will be expanded immediately (provided it has been given a definition). This is useful for example with square() und cubic()

\deffunc [*] {name}{exp} Define an expression which will be used to evaluate the function, for example, \deffunc{f}{ax^2+bx+c}. Without the asterix, this command will produce output like f(x) = ax^2 + bx + c.

Keywords for printing results

\printeq {equation} Prints the equation (this will usually be an equation label)
\printvector{exp} Prints a vector in the format required by pstricks.sty.
\eqwrite\filename{equation}{label} Write an equation to a file. The equation has the label as given. This is useful to create a file of equations, which can then be included into another document and reused there. A typical usage would be

     \printoptions{eqparse}%Turn off pretty-printing of equations
      \newwrite\eqfile%
      \immediate\openout\eqfile filename.tex%
      \eqwrite\eqfile{\printeq{"eq:example"}}{eq:example}%
      \immediate\closeout\eqfile%
      \printoptions{eqnoparse}%

This file could then be reused as follows:

\input filename.tex
Equation \eqcref{"eq:example"} in 'whatever original file it came from' states
\begin{equation}
\printeq{"eq:example"}
\end{equation}

Output formatting

All options are handled by the common keyword \eqcoptions. It takes a list of key-value pairs

label = string Specifies a label for the equation, the label must be enclosed in quotes ("").
precision = integer Specifies what precision is to be used for printing floating point numbers. The precision is the absolute number of digits printed, more digits are rounded away. The precisions is 4 by default.
fixeddigits = true|false Specifies whether floating point numbers should be printed with a fixed number of digits after the decimal marker or with a fixed number of digits in total. The default is fixed_digits.
lowsclimit = exp Defines the low limit beyond which floating point numbers are printed as mantissa * 10^exponent.
highsclimit = exp Defines the high limit beyond which floating point numbers are printed as mantissa * 10^exponent.
units = unitlist Specifies a list of units separated by ';' preferred for printing physical quantities. If no such list is specified, the SI base units are used. This usually makes for ugly output, for example, when printing forces the unit Newton. A useful list of preferred units for mechanical engineering might be {\mm;\N;\Nm;\Nosqmm}. The order in which the preferred 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.
eqchain = true|false Omit the left hand side in chains of equations, in cases where only the rhs changed from one line to the next.
eqraw = true|false Raw formatting of \eq statements means that the equations are printed exactly as you typed them in. This of course only works until you manipulate the equation with \eqadd etc. The other options is to have EQC format your equations.
eqparse = true|false Turns of some pretty-printing features that make the LaTeX output of EQC difficult to re-parse. For example, cos^2(x) is printed as (cos(x))^2.
eqalign = type Change the LaTeX alignment type of an equation. Values for type are 'onlyleft' (alignment will be &=, for ams math), 'both' (&=&, for eqnarray environment), 'none'. If no alignment type is specified, EQC automatically formats depending on the environment.
eqsplit = exp Split the equation after the nth operand. The count starts at the left hand side of the equation. Operands are those parts of the equation that are separated either by addition/subtraction or multiplication symbols. At the given position, \\notag or \\nonumber are printed, depending on the environment
eqsplittext = string The text to interject after the split (in quotes ""). By default, this tries to align the second part of the equation to the right of the equals sign.

Other EQC options

Further key-value pairs to \eqcoptions are:

vecautosize = integer Specifies the size of a vector when no step count is given (i.e., the count is zero, x = 10:20:0. In this case, the vector will have the number of elements as given with this option (default 20).
path = string Set the path for the EQC-specific data files (default "/usr/share/texmf/tex/latex/eqc/" on Unix systems).
lang = "english"|"german" Changes the language which EQC expects the input file to use. At the moment, this only has an effect on parsing floating point numbers, i.e., the decimal separator is set to ',' for "german" and to '.' for "english" or any other language.
debug = integer Changes the level of debug output (default is 0). Set to -1 to suppress everything except error messages, and to values up to 13 to get tons of debugging information
cleancomments = boolean Removes comment lines (lines starting with a percent sign) from the output file if set to true
tan_is_tg = boolean Changes the name of the tangent function to \tg and \arctan to\ arctg if set to true

Miscellaneous

\clearequations Clears the list of equations and variables. Constants are not cleared. Functions are cleared except for those declared in the file mathconstants.tex.
\input filename Includes the specified file. There is no difference to the Latex \include command. All include files are written to one output .eqc file. The extension .tex need not be given.
\dumpeq Write a list of all equations known to the compiler into the output file. The list is sorted by variable name (for assignments) and includes the equation label and number. This list is very useful in larger projects where it is difficult to remember the label of a specific equation and where it was defined. Note: This command requires AMS maths to be loaded and sets allowdisplaybreaks[1]!
\usepackage[language]{eqc} This command must be used in the Latex preamble to include some EQC-specific commands. For the meaning of the language parameter, see \eqlang.

Keywords inside equations

EQC does not parse all of the possible Latex mathematical keywords. The following keywords and tokens are recognized:

Basic mathematics

Apart from the basic addition, subtraction, multiplication and division symbols, EQC interprets the ^ and _ symbols in the same way as Latex does. Note that the * multiplication symbol may be omitted, just as in Latex.

Mathematical functions

The functions listed below are recognized. All of these are defined in the file mathconstants.tex, which needs to be included. Further functions may be defined at runtime with the \function and \deffunc keywords.

• \arccos Arcus cosine.
• \arcosh Hyperbolic arcus cosine.
• \arcsin Arcus sine.
• \arsinh Hyperbolic arcus sine.
• \arctan Arcus tangens
• \artanh Hyperbolic arcus tangens.
• \cos Cosine.
• \cosh Hyperbolic cosine.
• \cot Cotangens
• \coth Hyperbolic cotangens
• \csc Cosecans
• \cubic Cubic function (x^3)
• \exp Exponential function (e^x).
• \ln Natural logarithm.
• \log Decimal logarithm
• \sec Secans
• \sin Sine.
• \sinh Hyperbolic sine.
• \square Square function (x^2)
• \sqrt Square root
• \tan Tangens.
• \tanh Hyperbolic tangens.
• ! Factorial function

Brackets

All the standard Latex brackets are recognized: {, \lbrace, (, [, \lbrack, \lfloor, \lceil, \langle and of course the corresponding right brackets. The brackets may be modified in their size by \left, \bigl, \Bigl, \biggl, \Biggl and \right etc. EQC checks for bracket mismatches and issues a warning. Note that EQC does not preserve your bracket types, but creates its own brackets and bracket sizes in the Latex output.

Division

The Latex keywords \over and \frac are recognized.

Access to equations

Equations may be accessed using the \lhs and \rhs keywords. This will provide the left hand side resp. the left hand side of the equation. An equation label may be given instead of an equation.
Variable evaluation

Variable evaluation with the keywords \val, quantity, \numval and \units can take place inside equations. For details on how this works, see the corresponding keywords in the description above.

Constants

EQC has the following built-in constants:

• \pi = 3.14159...
• \e = 2.71828...
• \Euler = 0.57721...

Numbers

EQC recognizes integers and floating point numbers. The latter may not be in scientific notation as of yet. Whether the decimal separator is a comma or a dot is determined by the \eqlang keyword, or by the language parameter to \usepackage[language}{eqc}.

Vectors

A vector can be created with the syntax begin🔚step. For example, x = 1:3:1 will create a vector with three rows, containing the number 1, 2 and 3.

Integrals

A symbolic integral can be created with the syntax \integral(x=abf(x)) where x is the integration variable, a the lower and b the upper bound, and f a function in the integration variable. Note that if f(x) does not explicitly mention x, then the result will not be what you expected.

Variables

Any letter that is not part of a keyword is assumed to be a variable. Variable names are registered automatically on their first appearance. Any occurence of the same letter is taken to mean the same variable, until a \clearequations command is read. Any Latex macros that are not known to EQC are also interpreted as variable names, e.g., \phi.

Physical units

Physical units are identified by their Latex macro name, e.g., \mm. Any units other than the base SI units need to be defined with \defunit (include the file units.tex to get the most common physical unit definitions).

Percentages

To express percentages in an equation, use the \percent keyword.

Command line arguments

-d --debug LEVEL Produce debugging and informational output at level LEVEL
-p --path PATH Path to EQC specific files (eqc.sty etc.)
-v --verbose Produce verbose output (same as -d1)
-q --quiet Don't produce any output (same as -d-1)
-s --silent Don't produce any output (same as -d-1)
-V --version Print program version
-? --help --usage Produce informational output

Note that as of version 1.4.2, command line arguments are not yet supported on Windows.