# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# `plot`::`Rootlocus`

Curves of roots of rational expressions

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

## Syntax

```plot::Rootlocus(`p(z, u)`, `u = umin .. umax`, <`a = amin .. amax`>, `options`)
```

## Description

```plot::Rootlocus(p(z, u), u = umin.. umax)``` creates a 2D plot of the curves in the complex plane given by the roots of p(z, u) = 0 (solved for z) as the parameter u varies between `umin` and `umax`.

For any given value of u, `plot::Rootlocus` solves the equation p(z, u) = 0 for z. The solutions define points with coordinates x = (z), y = (z) in the complex plane. As the parameter u varies, the solutions form continuous curves that a depicted by `plot::Rootlocus`.

The roots of the numerator of `p(z, u)` are considered. All complex solutions of this polynomial in z are computed numerically via `numeric::polyroots`.

The polynomial is initially solved for some values u from the range `u = `u_{min}` .. `u_{max}``. The optional argument `Mesh` = n can be used to specify the number n of these initial points (the default value is 51). These points are not equally spaced, but accumulate close to the end of the range.

The routine then tries to pair up the roots for adjacent values of u by choosing those closest to each other.

Finally, the routine tries to trace out the different curves by joining up adjacent points with line segments. If adjacent line segments exhibit angles that are not close to 180 degrees, additional roots are computed for parameter values u between the values of the initial mesh. Up to m such bisectioning steps are possible, where m is specified by the optional argument `AdaptiveMesh` = m (the default value is 4). With `AdaptiveMesh` = 0, this adaptive mechanism may be switched off.

Sometimes, the matching up of the roots to continuous curves can be fooled and the result is a messy plot. In such a case, the user can take the following measures to improve the plot:

• The parameter range `u = `u_{min}` .. `u_{max}`` may be unreasonably large. Reduce this range to a reasonable size!

• Increase the size n of the initial mesh using the option `Mesh` = n. Note that increasing n by some factor may increase the runtime of the plot by the same factor!

• Increase the number m of possible adaptive bisectioning steps using the option `AdaptiveMesh` = m. Note that increasing m by 1 may increase the runtime of the plot by a factor of 2!

• Using the options `LinesVisible = FALSE` in conjunction with `PointsVisible = TRUE`, the roots are displayed as separate points without joining line segments.

Cf. Example 2.

Animations are triggered by specifying a range ```a = `a_{min}` .. `a_{max}```` for a parameter `a` that is different from the variables `z` and `u`. Cf. Example 3.

The curves can be colored by a user defined color scheme. Just pass the option `LineColorFunction` = `mycolor`, where `mycolor` is a user definied procedure that returns an `RGB` color value. The routine `plot::Rootlocus` calls ```mycolor(u, x, y)```, where u is the parameter value and x, y are the real and imaginary parts of the root of p(x + i y, u) = 0. Cf. Example 4.

## Attributes

AttributePurposeDefault Value
`AdaptiveMesh`adaptive sampling`4`
`AffectViewingBox`influence of objects on the `ViewingBox` of a scene`TRUE`
`AntiAliased`antialiased lines and points?`TRUE`
`Frames`the number of frames in an animation`50`
`Legend`makes a legend entry
`LegendText`short explanatory text for legend
`LegendEntry`add this object to the legend?`FALSE`
`LineColor`color of lines`RGB::Blue`
`LineWidth`width of lines`0.35`
`LineStyle`solid, dashed or dotted lines?`Solid`
`LinesVisible`visibility of lines`TRUE`
`LineColorType`line coloring types`Flat`
`LineColorFunction`functional line coloring
`Mesh`number of sample points`51`
`Name`the name of a plot object (for browser and legend)
`ParameterEnd`end value of the animation parameter
`ParameterName`name of the animation parameter
`ParameterBegin`initial value of the animation parameter
`ParameterRange`range of the animation parameter
`PointSize`the size of points`1.0`
`PointStyle`the presentation style of points`FilledCircles`
`PointsVisible`visibility of mesh points`FALSE`
`RationalExpression`rational expression in a rootlocus plot
`TimeEnd`end time of the animation`10.0`
`TimeBegin`start time of the animation`0.0`
`TimeRange`the real time span of an animation`0.0` .. `10.0`
`Title`object title
`TitleFont`font of object titles[`" sans-serif "`, `11`]
`TitlePosition`position of object titles
`TitleAlignment`horizontal alignment of titles w.r.t. their coordinates`Center`
`TitlePositionX`position of object titles, x component
`TitlePositionY`position of object titles, y component
`UMax`final value of parameter “u”
`UMesh`number of sample points for parameter “u”`51`
`UMin`initial value of parameter “u”
`UName`name of parameter “u”
`URange`range of parameter “u”
`Visible`visibility`TRUE`
`VisibleAfter`object visible after this time value
`VisibleBefore`object visible until this time value
`VisibleFromTo`object visible during this time range
`VisibleAfterEnd`object visible after its animation time ended?`TRUE`
`VisibleBeforeBegin`object visible before its animation time starts?`TRUE`

## Examples

### Example 1

The roots of the polynomial z2 - 2 uz + 1 are given by and . We visualise these two curves via a rootlocus plot:

`plot(plot::Rootlocus(z^2 - 2*u*z + 1, u = -1.5..1.5))`

For rational expressions, the roots of the numerator are considered. The following plot displays the roots of the numerator polynomial (z2 - u)2 + u (z - u)3:

`plot(plot::Rootlocus(1 + u * (z - u)^3/(z^2 - u)^2, u = -1..1)):`

Here are various other examples:

`plot(plot::Rootlocus((z^2 - 2*u*z + 1)^2 + u, u = -1..1))`

```plot(plot::Rootlocus((z^2 - u)^6 + u^2, u = -2..2, Color = RGB::Red))```

```plot(plot::Rootlocus((z^5 - 1)^3 + u, u = -1..1, PointsVisible, PointSize = 1.5))```

### Example 2

The following plot is rather messy, since the default mesh size of 51 initial points on each curve is not sufficient to obtain a good resolution:

`plot(plot::Rootlocus((z-u)^3 - u/z^3, u = -10^3 .. 10^3)):`

We obtain a better resolution by decreasing the range of the parameter u to a reasonable size. There are still a few points that are not properly matched up with the curves:

`plot(plot::Rootlocus((z-u)^3 - u/z^3, u = -10 .. 10)):`

We increase the mesh size to cure this problem:

`plot(plot::Rootlocus((z-u)^3 - u/z^3, u = -10 .. 10, Mesh = 251)):`

We plot the roots as separate points without displaying connecting line segments:

```plot(plot::Rootlocus((z-u)^3 - u/z^3, u = -10 .. 10, Mesh = 501, LinesVisible = FALSE, PointsVisible)):```

### Example 3

We animate the expression whose roots are to plotted:

```plot(plot::Rootlocus(z^2 - 2*u*z + a, u = -1..1, a = -0.2 .. 2, Mesh = 10), plot::Text2d(a -> "a = ".stringlib::formatf(a, 2, 5), [1.2, 1.0], a = -0.2 .. 1));```

We animate the parameter range:

`plot(plot::Rootlocus(z^2 - 2*u*z + 0.81, u = -1 .. a, a = -1 .. 1, Mesh = 10))`

### Example 4

We provide a color function: roots for small values of the parameter u are displayed in red, whereas roots for large parameter values are displayed in blue:

```plot(plot::Rootlocus(z^2 - 2*u*z + 0.81, u = -1..1, LineColorFunction = ((u, x, y) -> [(1 - u)/2, 0, (1 + u)/2])))```

## Parameters

 `p(z, u)` An arithmetical expression in two unknowns z and u and, possibly, the animation parameter `a`. It must be a rational expression in z. `p(z, u)` is equivalent to the attribute `RationalExpression`. `z` Name of the unknown: an identifier or an indexed identifier. `u` Name of the curve parameter: an identifier or an indexed identifier. `u` is equivalent to the attribute `UName`. `umin .. umax` The range of the curve parameter: `umin`, `umax` must be numerical real values or expressions of the animation parameter a. `umin` .. `umax` is equivalent to the attributes `URange`, `UMin`, `UMax`. `a` Animation parameter, specified as `a```` = amin..amax```, where `amin` is the initial parameter value, and `amax` is the final parameter value.