# `Im`

Imaginary part of an arithmetical expression

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

## Syntax

```Im(`z`)
Im(`L`)
```

## Description

`Im(z)` returns the imaginary part of `z`.

The intended use of `Im` is for constant arithmetical expressions. Especially for numbers, of type `DOM_INT`, `DOM_RAT`, `DOM_FLOAT`, or `DOM_COMPLEX`, the imaginary part is computed directly and very efficiently.

`Im` can handle symbolic expressions. Properties of identifiers are taken into account. See `assume`. An identifier without any property is assumed to be complex. See Example 2.

If `Im` cannot extract the whole imaginary part of `z`, then the returned expression contains symbolic `Re` and `Im` calls. In such cases, try using the `rectform` function. See Example 3. Note that using `rectform` is computationally expensive.

The `Im` function is automatically mapped to all entries of container objects such as arrays, lists, matrices, polynomials, sets, and tables.

## Environment Interactions

This function is sensitive to properties of identifiers set via `assume`.

## Examples

### Example 1

The imaginary part of 2 e1 + i is:

`Im(2*exp(1 + I))`
` `

### Example 2

`Im` cannot extract the imaginary part of symbolic expressions containing identifiers without a value. However, in some cases it can still simplify the input expression, as in the following two examples:

`Im(u + v*I)`
` `
`Im(z + 2)`
` `

By default, identifiers without a value are assumed to represent arbitrary complex numbers. You can use `assume` to change this. The following command tells the system that `z` represents only imaginary numbers:

```assume(z, Type::Imaginary): Im(z + 2*I)```
` `
`unassume(z)`

### Example 3

If `Im` cannot extract the imaginary part of a symbolic expression, try using the function `rectform`. It splits a complex expression z into its real and imaginary part and is more powerful than `Im`:

```Im(exp(I*sin(z))); r := rectform(exp(I*sin(z)))```
` `
` `

Then use `Im(r)` to extract the imaginary part of `r`:

`Im(r)`
` `

### Example 4

Symbolic expressions of type `"Im"` always have the property `Type::Real`, even if no identifier of the symbolic expression has a property:

`is(Im(sin(2*x)), Type::Real)`
` `

### Example 5

You can extend the functions `Re` and `Im` to their own special mathematical functions. See the “Algorithms” section. To do so, embed your mathematical function into a function environment`f` and implement the behavior of the functions `Re` and `Im` for this function as the slots `"Re"` and `"Im"` of the function environment.

If a subexpression of the form `f(u,..)` occurs in `z`, then `Re` and `Im` issue the call `f::Re(u,..)` and `f::Im(u,..)`, respectively, to the slot routine to determine the real and the imaginary part of `f(u,..)`, respectively.

For example, extend the function `Im` for the sine function. Of course, the function environment `sin` already has a `"Im"` slot. Call your function environment `Sin` in order not to overwrite the existing system function `sin`:

```Sin := funcenv(Sin): Sin::Im := proc(u) // compute Im(Sin(u)) local r, s; begin r := Re(u); if r = u then return(0) elif not has(r, {hold(Im), hold(Re)}) then s := Im(u); if not has(s, {hold(Im), hold(Re)}) then return(cos(r)*sinh(s)) end_if end_if; return(FAIL) end:```
`Im(Sin(2)), Im(Sin(3*I)), Im(Sin(2 + 3*I))`
` `

The return value `FAIL` tells the function `Im` that `Sin::Im` was unable to determine the imaginary part of the input expression. The result is then a symbolic `Im` call:

`Im(2 + Sin(f(z)))`
` `

## Parameters

 `z` `L` A container object: an array, an hfarray, a list, a matrix, a polynomial, a set, or a table.

## Return Values

arithmetical expression or a container object containing such expressions

`z`

## Algorithms

If a subexpression of the form `f(u,...)` occurs in `z` and `f` is a function environment, then `Im` attempts to call the slot `"Im"` of `f` to determine the imaginary part of `f(u,...)`. In this way, you can extend the functionality of `Im` to your own special mathematical functions.

The slot `"Im"` is called with the arguments `u`,... of `f`. If the slot routine `f::Im` is not able to determine the imaginary part of `f(u,...)`, then it must return `FAIL`.

If `f` does not have a slot `"Im"`, or if the slot routine `f::Im` returns `FAIL`, then `f(u,...)` is replaced by the symbolic call `Im(f(u,...))` in the returned expression. See Example 5.

Similarly, if an element `d` of a library domain`T` occurs as a subexpression of `z`, then `Im` attempts to call the slot `"Im"` of that domain with `d` as argument to compute the imaginary part of `d`.

If the slot routine `T::Im` is not able to determine the imaginary part of `d`, then it must return `FAIL`.

If `T` does not have a slot `"Im"`, or if the slot routine `T::Im` returns `FAIL`, then `d` is replaced by the symbolic call `Im(d)` in the returned expression.