The functions described here operate on symbolic formulas in the Calculator.

__Function:__ **calc-prepare-selection** *num*

Prepare a stack entry for selection operations. If `num` is
omitted, the stack entry containing the cursor is used; otherwise,
it is the number of the stack entry to use. This function stores
useful information about the current stack entry into a set of
variables. `calc-selection-cache-num`

contains the number of
the stack entry involved (equal to `num` if you specified it);
`calc-selection-cache-entry`

contains the stack entry as a
list (such as `calc-top-list`

would return with `entry`

as the selection mode); and `calc-selection-cache-comp`

contains
a special "tagged" composition (see section I/O and Formatting Functions)
which allows Calc to relate cursor positions in the buffer with
their corresponding sub-formulas.

A slight complication arises in the selection mechanism because
formulas may contain small integers. For example, in the vector
``[1, 2, 1]'` the first and last elements are `eq`

to each
other; selections are recorded as the actual Lisp object that
appears somewhere in the tree of the whole formula, but storing
`1`

would falsely select both `1`

's in the vector. So
`calc-prepare-selection`

also checks the stack entry and
replaces any plain integers with "complex number" lists of the form
``(cplx n 0)'`. This list will be displayed the same as a
plain

`eq`

to each other. Next time the stack entry
is involved in a computation, `calc-normalize`

will replace
these lists with plain numbers again, again invisibly to the user.
__Function:__ **calc-encase-atoms** *x*

This modifies the formula `x` to ensure that each part of the
formula is a unique atom, using the ``(cplx n 0)'` trick
described above. This function may use

`setcar`

to modify
the formula in-place.
__Function:__ **calc-find-selected-part**

Find the smallest sub-formula of the current formula that contains
the cursor. This assumes `calc-prepare-selection`

has been
called already. If the cursor is not actually on any part of the
formula, this returns `nil`

.

__Function:__ **calc-change-current-selection** *selection*

Change the currently prepared stack element's selection to
`selection`, which should be `eq`

to some sub-formula
of the stack element, or `nil`

to unselect the formula.
The stack element's appearance in the Calc buffer is adjusted
to reflect the new selection.

__Function:__ **calc-find-nth-part** *expr n*

Return the `n`th sub-formula of `expr`. This function is used
by the selection commands, and (unless `j b` has been used) treats
sums and products as flat many-element formulas. Thus if `expr`
is ``((a + b) - c) + d'`, calling `calc-find-nth-part`

with
`n` equal to four will return ``d'`.

__Function:__ **calc-find-parent-formula** *expr part*

Return the sub-formula of `expr` which immediately contains
`part`. If `expr` is ``a*b + (c+1)*d'` and `part`
is `eq`

to the ``c+1'` term of `expr`, then this function
will return ``(c+1)*d'`. If `part` turns out not to be a
sub-formula of `expr`, the function returns `nil`

. If
`part` is `eq`

to `expr`, the function returns `t`

.
This function does not take associativity into account.

__Function:__ **calc-find-assoc-parent-formula** *expr part*

This is the same as `calc-find-parent-formula`

, except that
(unless `j b` has been used) it continues widening the selection
to contain a complete level of the formula. Given ``a'` from
``((a + b) - c) + d'`, `calc-find-parent-formula`

will
return ``a + b'` but `calc-find-assoc-parent-formula`

will
return the whole expression.

__Function:__ **calc-grow-assoc-formula** *expr part*

This expands sub-formula `part` of `expr` to encompass a
complete level of the formula. If `part` and its immediate
parent are not compatible associative operators, or if `j b`
has been used, this simply returns `part`.

__Function:__ **calc-find-sub-formula** *expr part*

This finds the immediate sub-formula of `expr` which contains
`part`. It returns an index `n` such that
``(calc-find-nth-part expr n)'` would return

`nil`

.
If `eq`

to `t`

. This
function does not take associativity into account.
__Function:__ **calc-replace-sub-formula** *expr old new*

This function returns a copy of formula `expr`, with the
sub-formula that is `eq`

to `old` replaced by `new`.

__Function:__ **simplify** *expr*

Simplify the expression `expr` by applying various algebraic rules.
This is what the `a s` (`calc-simplify`

) command uses. This
always returns a copy of the expression; the structure `expr` points
to remains unchanged in memory.

More precisely, here is what `simplify`

does: The expression is
first normalized and evaluated by calling `normalize`

. If any
`AlgSimpRules`

have been defined, they are then applied. Then
the expression is traversed in a depth-first, bottom-up fashion; at
each level, any simplifications that can be made are made until no
further changes are possible. Once the entire formula has been
traversed in this way, it is compared with the original formula (from
before the call to `normalize`

) and, if it has changed,
the entire procedure is repeated (starting with `normalize`

)
until no further changes occur. Usually only two iterations are
needed: one to simplify the formula, and another to verify that no
further simplifications were possible.

__Function:__ **simplify-extended** *expr*

Simplify the expression `expr`, with additional rules enabled that
help do a more thorough job, while not being entirely "safe" in all
circumstances. (For example, this mode will simplify ``sqrt(x^2)'`
to ``x'`, which is only valid when `x` is positive.) This is
implemented by temporarily binding the variable `math-living-dangerously`

to `t`

(using a `let`

form) and calling `simplify`

.
Dangerous simplification rules are written to check this variable
before taking any action.

__Function:__ **simplify-units** *expr*

Simplify the expression `expr`, treating variable names as units
whenever possible. This works by binding the variable
`math-simplifying-units`

to `t`

while calling `simplify`

.

__Macro:__ **math-defsimplify** *funcs body*

Register a new simplification rule; this is normally called as a top-level
form, like `defun`

or `defmath`

. If `funcs` is a symbol
(like `+`

or `calcFunc-sqrt`

), this simplification rule is
applied to the formulas which are calls to the specified function. Or,
`funcs` can be a list of such symbols; the rule applies to all
functions on the list. The `body` is written like the body of a
function with a single argument called `expr`

. The body will be
executed with `expr`

bound to a formula which is a call to one of
the functions `funcs`. If the function body returns `nil`

, or
if it returns a result `equal`

to the original `expr`

, it is
ignored and Calc goes on to try the next simplification rule that applies.
If the function body returns something different, that new formula is
substituted for `expr` in the original formula.

At each point in the formula, rules are tried in the order of the
original calls to `math-defsimplify`

; the search stops after the
first rule that makes a change. Thus later rules for that same
function will not have a chance to trigger until the next iteration
of the main `simplify`

loop.

Note that, since `defmath`

is not being used here, `body` must
be written in true Lisp code without the conveniences that `defmath`

provides. If you prefer, you can have `body` simply call another
function (defined with `defmath`

) which does the real work.

The arguments of a function call will already have been simplified before any rules for the call itself are invoked. Since a new argument list is consed up when this happens, this means that the rule's body is allowed to rearrange the function's arguments destructively if that is convenient. Here is a typical example of a simplification rule:

(math-defsimplify calcFunc-arcsinh (or (and (math-looks-negp (nth 1 expr)) (math-neg (list 'calcFunc-arcsinh (math-neg (nth 1 expr))))) (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) (or math-living-dangerously (math-known-realp (nth 1 (nth 1 expr)))) (nth 1 (nth 1 expr)))))

This is really a pair of rules written with one `math-defsimplify`

for convenience; the first replaces ``arcsinh(-x)'` with
``-arcsinh(x)'`, and the second, which is safe only for real ``x'`,
replaces ``arcsinh(sinh(x))'` with ``x'`.

__Function:__ **common-constant-factor** *expr*

Check `expr` to see if it is a sum of terms all multiplied by the
same rational value. If so, return this value. If not, return `nil`

.
For example, if called on ``6x + 9y + 12z'`, it would return 3, since
3 is a common factor of all the terms.

__Function:__ **cancel-common-factor** *expr factor*

Assuming `expr` is a sum with `factor` as a common factor,
divide each term of the sum by `factor`. This is done by
destructively modifying parts of `expr`, on the assumption that
it is being used by a simplification rule (where such things are
allowed; see above). For example, consider this built-in rule for
square roots:

(math-defsimplify calcFunc-sqrt (let ((fac (math-common-constant-factor (nth 1 expr)))) (and fac (not (eq fac 1)) (math-mul (math-normalize (list 'calcFunc-sqrt fac)) (math-normalize (list 'calcFunc-sqrt (math-cancel-common-factor (nth 1 expr) fac)))))))

__Function:__ **frac-gcd** *a b*

Compute a "rational GCD" of `a` and `b`, which must both be
rational numbers. This is the fraction composed of the GCD of the
numerators of `a` and `b`, over the GCD of the denominators.
It is used by `common-constant-factor`

. Note that the standard
`gcd`

function uses the LCM to combine the denominators.

__Function:__ **map-tree** *func expr many*

Try applying Lisp function `func` to various sub-expressions of
`expr`. Initially, call `func` with `expr` itself as an
argument. If this returns an expression which is not `equal`

to
`expr`, apply `func` again until eventually it does return
`expr` with no changes. Then, if `expr` is a function call,
recursively apply `func` to each of the arguments. This keeps going
until no changes occur anywhere in the expression; this final expression
is returned by `map-tree`

. Note that, unlike simplification rules,
`func` functions may *not* make destructive changes to
`expr`. If a third argument `many` is provided, it is an
integer which says how many times `func` may be applied; the
default, as described above, is infinitely many times.

__Function:__ **compile-rewrites** *rules*

Compile the rewrite rule set specified by `rules`, which should
be a formula that is either a vector or a variable name. If the latter,
the compiled rules are saved so that later `compile-rules`

calls
for that same variable can return immediately. If there are problems
with the rules, this function calls `error`

with a suitable
message.

__Function:__ **apply-rewrites** *expr crules heads*

Apply the compiled rewrite rule set `crules` to the expression
`expr`. This will make only one rewrite and only checks at the
top level of the expression. The result `nil`

if no rules
matched, or if the only rules that matched did not actually change
the expression. The `heads` argument is optional; if is given,
it should be a list of all function names that (may) appear in
`expr`. The rewrite compiler tags each rule with the
rarest-looking function name in the rule; if you specify `heads`,
`apply-rewrites`

can use this information to narrow its search
down to just a few rules in the rule set.

__Function:__ **rewrite-heads** *expr*

Compute a `heads` list for `expr` suitable for use with
`apply-rewrites`

, as discussed above.

__Function:__ **rewrite** *expr rules many*

This is an all-in-one rewrite function. It compiles the rule set
specified by `rules`, then uses `map-tree`

to apply the
rules throughout `expr` up to `many` (default infinity)
times.

__Function:__ **match-patterns** *pat vec not-flag*

Given a Calc vector `vec` and an uncompiled pattern set or
pattern set variable `pat`, this function returns a new vector
of all elements of `vec` which do (or don't, if `not-flag` is
non-`nil`

) match any of the patterns in `pat`.

__Function:__ **deriv** *expr var value symb*

Compute the derivative of `expr` with respect to variable `var`
(which may actually be any sub-expression). If `value` is specified,
the derivative is evaluated at the value of `var`; otherwise, the
derivative is left in terms of `var`. If the expression contains
functions for which no derivative formula is known, new derivative
functions are invented by adding primes to the names; see section Calculus.
However, if `symb` is non-`nil`

, the presence of undifferentiable
functions in `expr` instead cancels the whole differentiation, and
`deriv`

returns `nil`

instead.

Derivatives of an `n`-argument function can be defined by
adding a `math-derivative-`

property to the property list
of the symbol for the function's derivative, which will be the
function name followed by an apostrophe. The value of the property
should be a Lisp function; it is called with the same arguments as the
original function call that is being differentiated. It should return
a formula for the derivative. For example, the derivative of `n``ln`

is defined by

(put 'calcFunc-ln\' 'math-derivative-1 (function (lambda (u) (math-div 1 u))))

The two-argument `log`

function has two derivatives,

(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx (function (lambda (x b) ... ))) (put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db (function (lambda (x b) ... )))

__Function:__ **tderiv** *expr var value symb*

Compute the total derivative of `expr`. This is the same as
`deriv`

, except that variables other than `var` are not
assumed to be constant with respect to `var`.

__Function:__ **integ** *expr var low high*

Compute the integral of `expr` with respect to `var`.
See section Calculus, for further details.

__Macro:__ **math-defintegral** *funcs body*

Define a rule for integrating a function or functions of one argument;
this macro is very similar in format to `math-defsimplify`

.
The main difference is that here `body` is the body of a function
with a single argument `u`

which is bound to the argument to the
function being integrated, not the function call itself. Also, the
variable of integration is available as `math-integ-var`

. If
evaluation of the integral requires doing further integrals, the body
should call ``(math-integral x)'` to find the integral of

`math-integ-var`

; this function returns
`nil`

if the integral could not be done. Some examples:
(math-defintegral calcFunc-conj (let ((int (math-integral u))) (and int (list 'calcFunc-conj int)))) (math-defintegral calcFunc-cos (and (equal u math-integ-var) (math-from-radians-2 (list 'calcFunc-sin u))))

In the `cos`

example, we define only the integral of ``cos(x) dx'`,
relying on the general integration-by-substitution facility to handle
cosines of more complicated arguments. An integration rule should return
`nil`

if it can't do the integral; if several rules are defined for
the same function, they are tried in order until one returns a non-`nil`

result.

__Macro:__ **math-defintegral-2** *funcs body*

Define a rule for integrating a function or functions of two arguments.
This is exactly analogous to `math-defintegral`

, except that `body`
is written as the body of a function with two arguments, `u` and
`v`.

__Function:__ **solve-for** *lhs rhs var full*

Attempt to solve the equation `` lhs = rhs'` by isolating
the variable

`nil`

if the equation cannot be solved. The variable
`solve`

and `finv`

functions,
which return a rearranged equation or a functional inverse, respectively.
If `nil`

, a full solution including dummy signs
and dummy integers will be produced. User-defined inverses are provided
as properties in a manner similar to derivatives:
(put 'calcFunc-ln 'math-inverse (function (lambda (x) (list 'calcFunc-exp x))))

This function can call ``(math-solve-get-sign x)'` to create
a new arbitrary sign variable, returning

__Function:__ **solve-eqn** *expr var full*

This version of `solve-for`

takes an expression which will
typically be an equation or inequality. (If it is not, it will be
interpreted as the equation `` expr = 0'`.) It returns an
equation or inequality, or

`nil`

if no solution could be found.
__Function:__ **solve-system** *exprs vars full*

This function solves a system of equations. Generally, `exprs`
and `vars` will be vectors of equal length.
See section Solving Systems of Equations, for other options.

__Function:__ **expr-contains** *expr var*

Returns a non-`nil`

value if `var` occurs as a subexpression
of `expr`.

This function might seem at first to be identical to
`calc-find-sub-formula`

. The key difference is that
`expr-contains`

uses `equal`

to test for matches, whereas
`calc-find-sub-formula`

uses `eq`

. In the formula
``f(a, a)'`, the two ``a'`s will be `equal`

but not
`eq`

to each other.

__Function:__ **expr-contains-count** *expr var*

Returns the number of occurrences of `var` as a subexpression
of `expr`, or `nil`

if there are no occurrences.

__Function:__ **expr-depends** *expr var*

Returns true if `expr` refers to any variable the occurs in `var`.
In other words, it checks if `expr` and `var` have any variables
in common.

__Function:__ **expr-contains-vars** *expr*

Return true if `expr` contains any variables, or `nil`

if `expr`
contains only constants and functions with constant arguments.

__Function:__ **expr-subst** *expr old new*

Returns a copy of `expr`, with all occurrences of `old` replaced
by `new`. This treats `lambda`

forms specially with respect
to the dummy argument variables, so that the effect is always to return
`expr` evaluated at `old` = `new`.

__Function:__ **multi-subst** *expr old new*

This is like `expr-subst`

, except that `old` and `new`
are lists of expressions to be substituted simultaneously. If one
list is shorter than the other, trailing elements of the longer list
are ignored.

__Function:__ **expr-weight** *expr*

Returns the "weight" of `expr`, basically a count of the total
number of objects and function calls that appear in `expr`. For
"primitive" objects, this will be one.

__Function:__ **expr-height** *expr*

Returns the "height" of `expr`, which is the deepest level to
which function calls are nested. (Note that `` a + b'`
counts as a function call.) For primitive objects, this returns zero.

__Function:__ **polynomial-p** *expr var*

Check if `expr` is a polynomial in variable (or sub-expression)
`var`. If so, return the degree of the polynomial, that is, the
highest power of `var` that appears in `expr`. For example,
for ``(x^2 + 3)^3 + 4'` this would return 6. This function returns
`nil`

unless `expr`, when expanded out by `a x`
(`calc-expand`

), would consist of a sum of terms in which `var`
appears only raised to nonnegative integer powers. Note that if
`var` does not occur in `expr`, then `expr` is considered
a polynomial of degree 0.

__Function:__ **is-polynomial** *expr var degree loose*

Check if `expr` is a polynomial in variable or sub-expression
`var`, and, if so, return a list representation of the polynomial
where the elements of the list are coefficients of successive powers of
`var`: `` a + b x + c x^3'` would produce the
list

`nil`

if `nil`

, then a looser definition of a polynomial
is used in which coefficients are no longer required not to depend on
`nil`

in loose mode, since any
expression can be interpreted as a "constant" loose polynomial.
__Function:__ **polynomial-base** *expr pred*

Check if `expr` is a polynomial in any variable that occurs in it;
if so, return that variable. (If `expr` is a multivariate polynomial,
this chooses one variable arbitrarily.) If `pred` is specified, it should
be a Lisp function which is called as ``( pred subexpr)'`,
and which should return true if

`mpb-top-expr`

(a global name for
the original
__Function:__ **poly-simplify** *poly*

Simplify polynomial coefficient list `poly` by (destructively)
clipping off trailing zeros.

__Function:__ **poly-mix** *a ac b bc*

Mix two polynomial lists `a` and `b` (in the form returned by
`is-polynomial`

) in a linear combination with coefficient expressions
`ac` and `bc`. The result is a (not necessarily simplified)
polynomial list representing `` ac a + bc b'`.

__Function:__ **poly-mul** *a b*

Multiply two polynomial coefficient lists `a` and `b`. The
result will be in simplified form if the inputs were simplified.

__Function:__ **build-polynomial-expr** *poly var*

Construct a Calc formula which represents the polynomial coefficient
list `poly` applied to variable `var`. The `a c`
(`calc-collect`

) command uses `is-polynomial`

to turn an
expression into a coefficient list, then `build-polynomial-expr`

to turn the list back into an expression in regular form.

__Function:__ **check-unit-name** *var*

Check if `var` is a variable which can be interpreted as a unit
name. If so, return the units table entry for that unit. This
will be a list whose first element is the unit name (not counting
prefix characters) as a symbol and whose second element is the
Calc expression which defines the unit. (Refer to the Calc sources
for details on the remaining elements of this list.) If `var`
is not a variable or is not a unit name, return `nil`

.

__Function:__ **units-in-expr-p** *expr sub-exprs*

Return true if `expr` contains any variables which can be
interpreted as units. If `sub-exprs` is `t`

, the entire
expression is searched. If `sub-exprs` is `nil`

, this
checks whether `expr` is directly a units expression.

__Function:__ **single-units-in-expr-p** *expr*

Check whether `expr` contains exactly one units variable. If so,
return the units table entry for the variable. If `expr` does
not contain any units, return `nil`

. If `expr` contains
two or more units, return the symbol `wrong`

.

__Function:__ **to-standard-units** *expr which*

Convert units expression `expr` to base units. If `which`
is `nil`

, use Calc's native base units. Otherwise, `which`
can specify a units system, which is a list of two-element lists,
where the first element is a Calc base symbol name and the second
is an expression to substitute for it.

__Function:__ **remove-units** *expr*

Return a copy of `expr` with all units variables replaced by ones.
This expression is generally normalized before use.

__Function:__ **extract-units** *expr*

Return a copy of `expr` with everything but units variables replaced
by ones.

Go to the first, previous, next, last section, table of contents.