## `Dom::ExpressionField` -- the domains of expressions forming a field

#### Introduction

`Dom::ExpressionField``(Normal, IsZero)` creates a domain of expressions forming a field, where the functions `Normal` and `IsZero` are used to normalize expressions and test for zero.

#### Domain

`Dom::ExpressionField( <Normal <, IsZero>>)`

#### Parameters

`Normal` | - | a function used to normalize the expressions of the domain; default is `id`.
`IsZero` | - | a function used to test the expressions of the domain for zero; default is `iszero @ Normal`.

#### Details

- `Dom::ExpressionField``(Normal, IsZero)` creates a domain which is supposed to be a field, where the field elements are represented as expressions. The function `Normal` is used to normalize the expressions representing the elements, the function `IsZero` is used to test the expressions for zero. It is assumed that the field has characteristic 0.
- The domain cannot decide if the element expressions--given the normalizing function and zero test--actually form a field. It is up to the user to choose correct functions for normalizing and zero test and to enter only valid expressions as domains elements.
- One should view this domain constructor as a pragmatic way to create a field of characteristic 0 in an ad-hoc fashion. Note that the default of using `id` and `iszero` does not yield a field really, but it is often convenient and sensible to use the resulting structure as a field.
- `Normal` must be a function which takes an expression representing a domain element and returns the normalized expression. `Normal` should return `FAIL` if the expression is not valid.
- If `Normal` is not given, then the system function `id` is used, i.e., only the kernel simplifier is used to normalize expressions.
- If a normalizing function other than `id` is given, it is assumed that this functions returns a normal form where the zero element is uniquely represented by the constant `0`.
- `IsZero` must be a function which takes an expression representing a domain element and returns `TRUE` if the expression represents zero and `FALSE` otherwise.
- If `IsZero` is not given, then `iszero @ Normal` is used for zero testing. If `Normal` is equal to `id` this functional expression is simplified to `iszero`.
- If `Normal` is equal to `id` and `IsZero` is equal to `iszero`, a faēcade domain is created, i.e., the domain elements are simply expressions and are not explicitly created by `new`.

  Otherwise the elements of the domain are explicitly created by `new`. Each such element has one operand, which is the expression representing the domain element. The element expressions are normalized after each operation using the function `Normal`.

#### Categories

`Cat::Field`

, `Cat::DifferentialRing`

#### Introduction

`Dom::ExpressionField``(Normal, IsZero)(e)` creates a field element represented by the expression `e`.

#### Creating Elements

``Dom::ExpressionField`(Normal, IsZero)(e)`

#### Parameters

`e` | - | an expression representing a field element.

#### Details

- `Dom::ExpressionField``(Normal, IsZero)(e)` creates a field element represented by the expression `e`. The expression is normalized using the function `Normal`.
- If `Normal` returns `FAIL`, it is assumed that the expression does not represent a valid field element. If this test is not fully implemented the domain cannot decide if the expression represents a valid field element. In this case it is up to the user to enter only valid expressions as field elements.
- If `Normal` is equal to `id` and `IsZero` is equal to `iszero`, the domain is only a faēcade domain. In this case the expression `e` is returned after being simplified by the built-in kernel simplifier.

#### Entries

characteristic

  The characteristic of the fields created by this constructor is assumed to be `0`.

one

  The element represented by the expression `1` is assumed to be a neutral element w.r.t. `"_mult"`.

zero

  The element represented by the expression `0` is assumed to be a neutral element w.r.t. `"_plus"`.

#### Method abs: absolute value

- `abs(dom x)`
- - Returns the absolute value of `x`. Maps `abs` to the expression representing `x`. See `abs` for details.
  - Overloads the function `abs`, thus may be called via `abs(x)`.

#### Method combine: combines terms of the same algebraic structure

- `combine(dom x <, a>)`
- - Combines terms of the same algebraic structure. Maps `combine` to the expression representing `x`. See `combine` for details and optional additional arguments.
  - Overloads the function `combine`, thus may be called via `combine(x,...)`.

#### Method conjugate: complex conjugate

- `conjugate(dom x)`
- - Returns the complex conjugate of `x`. Maps `conjugate` to the expression representing `x`. See `conjugate` for details.
  - Overloads the function `conjugate`, thus may be called via `conjugate(x)`.

#### Method D: differential operator

- `D( <list l,> dom x)`
- - Returns the derivative of `x`, where `x` is viewed as functional expression. Maps `D` to the expression representing `x`. See `D` for details and a description of the optional additional argument `l`.
  - Overloads the function `D`, thus may be called via `D(x)` or `D(l, x)`.

#### Method denom: denominator

- `denom(dom x)`
- - Returns the denominator of `x`. Maps `denom` to the expression representing `x`. See `denom` for details.
  - Overloads the function `denom`, thus may be called via `denom(x)`.

#### Method diff: differentiates an element

- `diff(dom x <, v ...>)`
- - Differentiates `x` with respect to the remaining arguments. Maps `diff` to the expression representing `x`. See `diff` for details and optional additional arguments.
  - Overloads the function `diff`, thus may be called via `diff(x,...)`.

#### Method _divide: divides elements

- `_divide(dom x, dom y)`
- - Computes `x/y` by dividing the expressions representing `x` and `y`.
  - Overloads the function `_divide`, thus may be called via `x/y` or `_divide(x, y)`.

#### Method equal: test for mathematical equality

- `equal(dom x, dom y)`
- - Tests if `x` is mathematically equal to `y`. This is implemented by testing if `x-y` is zero.

#### Method expand: expands an element

- `expand(dom x)`
- - Expands `x` by mapping `expand` to the expression representing `x`.
  - Overloads the function `expand`, thus may be called via `expand(x)`.

#### Method factor: factorizes an element

- `factor(dom x)`
- - Returns the factorization of `x` by mapping `factor` to the expression representing `x`.
  - Overloads the function `factor`, thus may be called via `factor(x)`.

#### Method float: floating-point approximation

- `float(dom x)`
- - Returns a floating-point approximation of `x` by mapping `float` to the expression representing `x`.
  - Overloads the function `float`, thus may be called via `float(x)`.

#### Method gcd: greatest common divisor

- `gcd(dom x, ...)`
- - Computes a greatest common divisor of the arguments by mapping the function `gcd` to the expressions representing the arguments.
  - Overloads the function `gcd`, thus may be called via `gcd(x, ...)`.

#### Method Im: imaginary part of an element

- `Im(dom x)`
- - Returns the imaginary part of `x`. Maps `Im` to the expression representing `x`. See `Im` for details.
  - Overloads the function `Im`, thus may be called via `Im(x)`.

#### Method int: definite and indefinite integration

- `int(dom x <, v>)`
- - Computes the definite or indefinite formal integral of `x` by mapping `int` to the expression representing `x`. See `int` for details and additional arguments.
  - Overloads the function `int`, thus may be called via `int(x,...)`.

#### Method intmult: integer mutiple

- `intmult(dom x, DOM_INT n)`
- - Returns the integer multiple `x*n` by multiplying the expression representing `x` by `n`.

#### Method _invert: inverts an element

- `_invert(dom x)`
- - Returns the inverse `1/x` of `x` by computing the inverse of the expression representing `x`.
  - Overloads the function `_invert`, thus may be called via `1/x` or `_invert(x)`.

#### Method iszero: test for zero

- `iszero(dom x)`
- - Tests if `x` is zero by calling `IsZero` with the expression representing `x` as argument.
  - Overloads the function `iszero`, thus may be called via `iszero(x)`.

#### Method lcm: least common multiple

- `lcm(dom x, ...)`
- - Computes a least common multiple of the arguments by mapping the function `lcm` to the expressions representing the arguments.
  - Overloads the function `lcm`, thus may be called via `lcm(x, ...)`.

#### Method _leequal: tests if less or equal

- `_leequal(dom x, dom y)`
- - Tests if `x` is less than or equal to `y` by mapping the function `_leequal` to the arguments.
  - Please note that the function `_leequal` can only test numbers (in a syntactical sense), but not constant expressions like `PI` or `sqrt(2)`.
  - Overloads the function `_leequal`, thus may be called via `x <= y`, `y >= x` or `_leequal(x, y)`.

#### Method _less: tests if element is less

- `_less(dom x, dom y)`
- - Tests if `x` is less than `y` by mapping the function `_less` to the arguments.
  - Please note that the function `_less` can only test numbers (in a syntactical sense), but not constant expressions like `PI` or `sqrt(2)`.
  - Overloads the function `_less`, thus may be called via `x < y`, `y > x` or `_less(x, y)`.

#### Method limit: limit computation

- `limit(dom x <, v, ...>)`
- - Computes the limit of `x` by mapping the function `limit` to the expression representing `x`. See `limit` for details and additional arguments.
  - Overloads the function `limit`, thus may be called via `limit(x,...)`.

#### Method max: maximum of arguments

- `max(dom x, ...)`
- - Computes the maximum of the arguments by mapping the function `max` to the expressions representing the arguments.
  - Overloads the function `max`, thus may be called via `max(x,...)`.

#### Method min: minimum of arguments

- `min(dom x, ...)`
- - Computes the minimum of the arguments by mapping the function `min` to the expressions representing the arguments.
  - Overloads the function `min`, thus may be called via `min(x,...)`.

#### Method _mult: multiplies elements

- `_mult(dom x, ...)`
- - Returns the product of the arguments.
  - If all arguments are of this domain or can be coerced to this domain (using the method `coerce`), the product of the expressions representing the arguments is calculated using the function `_mult`.

    If one of the arguments cannot be coerced, the arguments up to the offending one are multiplied and then the method `"_mult"` of the domain of the offending argument is called to multiply the remaining arguments.

  - Overloads the function `_mult`, thus may be called via `x*...` or `_mult(x,...)`.

#### Method _negate: negates an element

- `_negate(dom x)`
- - Returns the negative `-x` of `x` by computing the negative of the expression representing `x`.
  - Overloads the function `_negate`, thus may be called via `-x` or `_negate(x)`.

#### Method norm: norm of an element

- `norm(dom x)`
- - Computes the norm of `x` as the absolute value of the expression representing `x`. See the function `abs` for details.
  - Overloads the function `norm`, thus may be called via `norm(x)`.
  - Please note that the system function `norm`, applied to an expression, computes the norm of that expression interpreted as a polynomial expression and not the absolute value of the expression. This may be regarded as an inconsistency.

#### Method normal: normal form

- `normal(dom x)`
- - Computes the normal form of `x` by applying the function `Normal` to the expression representing `x`.
  - Overloads the function `normal`, thus may be called via `normal(x)`.

#### Method numer: numerator

- `numer(dom x)`
- - Returns the numerator of `x`. Maps `numer` to the expression representing `x`. See `numer` for details.
  - Overloads the function `numer`, thus may be called via `numer(x)`.

#### Method _plus: adds elements

- `_plus(`"dom" x, ...)
- - Returns the sum of the arguments.
  - If all arguments are of this domain or can be coerced to this domain (using the method `coerce`) the sum of the expressions representing the arguments is calculated using the function `_plus`.

    If one of the arguments cannot be coerced the arguments up to the offending one are added and then the method `"_plus"` of the domain of the offending argument is called to add the remaining arguments.

  - Overloads the function `_plus`, thus may be called via `x+...` or `_plus(x,...)`.

#### Method _power: exponentiates arguments

- `_power(dom x, any y)`
- `_power(any x, dom y)`
- - Returns `x` to the power of `y`.
  - If both arguments are of this domain the power is calculated by mapping the function `_power` to the expressions representing the arguments.

    If one of the arguments is not of this domain it is coerced to this domain, then the power is computed. If the coercion fails an error is raised.

    Note that it is assumed that at least one of the arguments is of this domain.

  - Overloads the function `_power`, thus may be called via `x^y` or `_power(x, y)`.

#### Method radsimp: simplifies radicals

- `radsimp(dom x)`
- - Simplifies radicals in `x`. Maps the function `radsimp` to the expression representing `x`. See `radsimp` for details.
  - Overloads the function `radsimp`, thus may be called via `radsimp(x)`.

#### Method random: creates a random element

- `random()`
- - Creates a random element of this domain by creating a univariate random polynomial expression which is then normalized using the function `Normal`.
  - See `polylib::randpoly` for details about creating random polynomials.

#### Method Re: real part of an element

- `Re(dom x)`
- - Returns the real part of `x`. Maps `Re` to the expression representing `x`. See `Re` for details.
  - Overloads the function `Re`, thus may be called via `Re(x)`.

#### Method sign: sign of an element

- `sign(dom x)`
- - Computes the sign of `x` by mapping the function `sign` to the expression representing `x`. See `sign` for details.
  - Overloads the function `sign`, thus may be called via `sign(x)`.

#### Method simplify: general simplification of an element

- `simplify(dom x <, a>)`
- - Tries to simplify `x` by mapping the function `simplify` to the expression representing `x`. See `simplify` for details and optional additional arguments.
  - Overloads the function `simplify`, thus may be called via `simplify(x,...)`.

#### Method solve: solves an equation

- `solve(dom x <, a, ...>)`
- - Tries to solve the equation `x = 0` using the standard solver function `solve`. Maps `solve` to the expression representing `x` and the additional arguments and directly returns the result of `solve`.
  - Note that this method will never return an element of this domain. See `solve` for details about results and optional additional arguments.
  - Overloads the function `solve`, thus may be called via `solve(x,...)`.

#### Method sqrfree: square-free factorization

- `sqrfree(dom x)`
- - Returns the square-free factorization of `x` by mapping `polylib::sqrfree` to the expression representing `x`.
  - Overloads the function `polylib::sqrfree`, thus may be called via `polylib::sqrfree(x)`.

#### Method _subtract: subtracts elements

- `_subtract(dom x, dom y)`
- - Computes `x-y` by subtracting the expressions representing `x` and `y`.
  - Overloads the function `_subtract`, thus may be called via `x-y` or `_subtract(x, y)`.

#### Method convert: convert to this domain

- `convert(any x)`
- - Tries to convert `x` to an element of this domain:
    - If `x` is from a domain defined by `Dom::ExpressionField` the expression representing `x` is used as the expression representing the new element of this domain.
    - Otherwise `x` is converted to an expression using the function `expr` and the resulting expression is used to represent the new element.
    Returns `FAIL` if the conversion fails.

#### Method convert_to: convert to other domain

- `convert_to(dom x, DOM_DOMAIN T)`
- - Tries to convert `x` to an element of the domain `T`:
    - If `T` is defined by `Dom::ExpressionField` the expression representing `x` is used as the expression representing the new element of `T`.
    - Otherwise the method `"convert"` of `T` is called with the expression representing `x` as argument.
    Returns `FAIL` if the conversion fails.

#### Method expr: convert to basic type

- `expr(dom x)`
- - Converts `x` to an expression containing only elements of basic types. Maps `expr` to the expression representing `x`.
  - This method is called by the function `expr` if a subexpression of the argument is an element of this domain.

#### Method new: creating an element

- `new(any x)`
- - Tries to create an element of this domain given `x`: First the method `"convert"` of this domain and then, if this fails, the method `"convert_to"` of the domain of `x` is called. If both methods fail an error is raised.
  - Overloads the function call operator for this domain, thus may be called via `F(x)` where `F` is this domain.

#### Method nops: number of operands

- `nops(dom x)`
- - Returns the number of operands of the expression representing `x`. See `nops` for details.
  - Overloads the function `nops`, thus may be called via `nops(x)`.

#### Method op: get operands

- `op(dom x)`
- - Returns an expression sequence with the operands of the expression representing `x`. The operands are converted to elements of this domain.

- `op(dom x, NonNegInt i)`
- - Returns the operand with index `i` of the expression representing `x`. If `i` is `0` then the operator of the expression is returned, which usually is not an element of this domain. The other operands are converted to elements of this domain.
  - This method is called by the function `op` when an element of this domain is contained, as a subexpression, in the first argument of `op`. Operand ranges and paths are handled by `op` and need not be handled by this method. See `op` for details.

#### Method subs: substitute subexpressions

- `subs(dom x, equation e, ...)`
- - Substitutes complete subexpressions in the expression representing `x` as specified by the substitution equations `e...`. The equations must be of the form `o = n`, where `o` is the original subexpression to replace and `n` is the new value that is inserted instead.
  - Maps `subs` to the expression representing `x`. The resulting expression is converted to an element of this domain.
  - This method is called by the function `subs` when an element of this domain is contained, as a subexpression, in the first argument of `subs`. See `subs` for details.

#### Method subsex: extended substitution

- `subsex(dom x, equation e, ...)`
- - Substitutes partial subexpressions in the expression representing `x` as specified by the substitution equations `e...`. The equations must be of the form `o = n`, where `o` is the original partial subexpression to replace and `n` is the new value that is inserted instead.
  - Maps `subsex` to the expression representing `x`. The resulting expression is converted to an element of this domain.
  - This method is called by the function `subsex` when an element of this domain is contained, as a subexpression, in the first argument of `subsex`. See `subsex` for details.

#### Method subsop: substitute operand

- `subsop(dom x, equation e)`
- - Substitutes in the expression representing `x` the operand given by the substitution equation `e`. The equation must be of the form `i = v`, where `i` is the index of the operand and `v` is its new value.

    Maps `subsop` to the expression representing `x`. The resulting expression is converted to an element of this domain.

  - This method is called by the function `subsop` when an element of this domain is contained, as a subexpression, in the first argument of `subsop`. Operand ranges and pathes are handled by `subsop` and need not be handled by this method. See `subsop` for details.

#### Method indets: the identifiers of an element

- `indets(dom x <, option optionName>)`
- - Returns a set of the identifiers contained in `x`. An identifier is an object of the domain `DOM_IDENT`. See `indets` for details and available options.
  - Overloads the function `indets`, thus may be called via `indets(x)` and `indets(x, optionName)`, respectively.

#### Method length: size of an element

- `length(dom x)`
- - Returns the size of `x`. Maps `length` to the expression representing `x`. See `length` for details.
  - Overloads the function `length`, thus may be called via `length(x)`.

#### Method map: applies function to operands

- `map(dom x, function f <, a, ...>)`
- - Applies the function `f` to the operands of the expression representing `x`. Additional arguments `a, ...` may be handled to the function. See `map` for details.
  - Overloads the function `map`, thus may be called via `map(x, f,...)`.

#### Method rationalize: approximate floating point numbers by rationals

- `rationalize(dom x <, a, ...>)`
- - Replaces all floating point numbers in the expression representing `x` by rational numbers. Maps the function `numeric::rationalize` to the expression representing `x`. See `numeric::rationalize` for details and additional optional arguments.
  - Note that this method does not overload the function `rationalize` from the standard library package, but the function `numeric::rationalize` from the `numeric` package instead. Thus the method may be called via `numeric::rationalize(x,...)`.

#### Method pivotSize: pivot size

- `pivotSize(dom x)`
- - Returns the pivot size used during Gaussian elemination, which is computed as `length` of the expression representing `x`.

#### Super-Domain

if `Normal` = `id` and `IsZero` = `iszero` then
`Dom::ArithmeticalExpression`
else
`Dom::BaseDomain`

#### Axioms

if `Normal` = `id` then
`Ax::efficientOperation``("_divide")`, `Ax::efficientOperation``("_mult")`, `Ax::efficientOperation``("_invert")`,
if `IsZero` = `iszero` then
`Ax::systemRep`
else
`Ax::normalRep`

#### Example 1

`Dom::ExpressionField(normal)` creates a field of rational expressions over the rationals. The expressions representing the field elements are allways normalized by `normal`:

    >> Fn := Dom::ExpressionField(normal):
       a := Fn((x^2 - 1)/(x - 1))

                                       x + 1

The field elements are explicit elements of the domain:

    >> domtype(a)

                    Dom::ExpressionField(normal, iszero@normal)

#### Example 2

In the domain `Dom::ExpressionField(id, iszero@normal)` the expressions representing the elements are normalized by the kernel simplifier only:

    >> Fi := Dom::ExpressionField(id, iszero@normal):
       a := Fi((x^2 - 1)/(x - 1))

                                       2
                                      x  - 1
                                      ------
                                      x - 1

The elements of this domain are not normalized (when viewed as rational expressions over the rationals), thus the domain does not have the axiom `Ax::normalRep`:

    >> b := a/Fi(x + 1) - Fi(1)

                                     2
                                    x  - 1
                                --------------- - 1
                                (x - 1) (x + 1)

But nevertheless this domain also represents the field of rational expressions over the rationals, because zero is detected correctly by the function `iszero @ normal`:

    >> iszero(b)

                                       TRUE

#### Changes

- New methods `"sign"`, `"convert_to"`, `"_less"`, `"_leequal"`, `"rationalize"`, `"solve"`, `"int"` and `"limit"` were implemented.
- The method `"Factor"` disappeared. The methods `"factor"` and `"sqrfree"` now return objects of the domain type `Factored`.
- The method `"equal"` can return `UNKNOWN`.
- If `Normal = id`, then `Dom::ExpressionField` has the axiom `Ax::efficientOperation` for division, multiplication and inversion of elements.
- The domain `Dom::ExpressionField(id,iszero)` is printed as `Dom::ExpressionField()`.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000