## `plot::Function2d` -- graphical primitive for a two-dimensional graph of a function

#### Introduction

`plot::Function2d``(f, x = a..b)` represents a plot of the function f(x) with x in [a,b].

#### Creating Elements

`plot::Function2d(f, x = a..b <, option1, option2...>)`
`plot::Function2d(f, x = a..b, y = ymin..ymax <, option1, option2...>)`

#### Parameters

`f` | - | arithmetical expression in `x`
`x, y` | - | identifiers
`a, b, ymin, ymax` | - | arithmetical expressions
`option1, option2, ...` | - | plot option(s) of the form `OptionName = value`

#### Related Domains

`plot::Curve2d`, `plot::Function3d`, `RGB`

#### Related Functions

`plot`, `plot2d`, `plotfunc2d`, `plot::copy`

#### Details

- Objects generated by `plot::Function2d` represent graphical primitives for two-dimensional graphs of functions which can be displayed via `plot(...)`, or used with other graphical primitives of the `plot` library.
- `plot::Function2d``(f, x = a..b, y = ymin..ymax, ...)` clips the graph of `f` to the rectangle with lower left corner (a; ymin) and upper right corner (b, ymax).

  The clipping of the graph to the given rectangle is implemented by `plot::Function2d` as follows: It tries to determine subintervals of [a, b], where f(x) lies in the interval [ymin, ymax]. This process does not work in general, and thus can produce graph plots outside the specified rectangle. It also depends on the value of the option Grid, and increasing the value of calculated grid points can be necessary. This is the case, for example, if `f` strongly oscillates in the interval [a, b]. See example 3.

- `plot::Function2d` automatically attempts to determine the locations of discontinuities before plotting. If `f` has discontinuities that can be determined, then the result of `plot::Function2d` consists of n+1 subgraphs, where n is the number of discontinuities of `f`.

  Use the option Discont to disable the determination of discontinuities.

- Note that `plotfunc2d` is also used to plot two-dimensional graphs of functions. But in contrast to `plot::Function2d`, it does not return the graph in form of a graphical object but displays the graph immediatly after executing the command.

  The main advantage of using `plot::Function2d` is, that you get the representation of the graph as an object. It can be manipulated afterwards or combined easily with other graphical primitives, such as polygons, curves or lists of points, to a common graphical scene.

  See example 2 below.

- An object of `plot::Function2d` has type `"graphprim"`, i.e., if `o` is such an object, then the result of `type(o)` is the string `"graphprim"`.
- Options `option1`, `option2`... are specified by equations `OptionName = value`. The following table gives an overview of the available options:

  `OptionName` | admissible values | default value
  Color | `[Flat]`, `[Flat, [r,g,b]]`, `[Height]`, `[Height, [r,g,b], [R,G,B]]`, `[Function, f]` | `[Flat,[1,0,0]]`
  Discont | `TRUE`, `FALSE` | `TRUE`
  Grid | `[n]` | `[100]`
  LineStyle | SolidLines, DashedLines | SolidLines
  LineWidth | positive integers | `1`
  PointStyle | Circles, FilledCircles, FilledSquares, Squares | FilledSquares
  PointWidth | positive integers | `30`
  RealValuesOnly | `TRUE`, `FALSE` | `TRUE`
  Smoothness | `[n]` | `[0]`
  Style | `[Points]`, `[Lines]`, `[LinesPoints]`, `[Impulses]` | `[Lines]`
  Title | strings |
  TitlePosition | `[x, y]` |

  See `plot2d` for further details on each option, except for Discont and RealValuesOnly, which are described in detail below.

- Scene options for the parameters `option1`, `option2`... are not allowed! One may pass scene options to the function `plot`, or use `plot::Scene` to create an object representing a graphical scene. Cf. example 1.

- A so-called attribute of a graphical primitive is a named entry of the object which can be accessed via the slot operator `::`.

  Each attribute has the property ``read'', i.e., the value of an attribute `attr` of a graphical primitive `o` can be read with `o::attr`. If the attribute also has the ``write'' property, then the value of the attribute can be changed with `o::attr := new_value`. See example 5.

  The following attributes are available for a function primitive:

  attribute | meaning | properties
  `objects` | If `f` has discontinuities and if the value of the option Discont is `TRUE`, then the graph of the function is splitted into a left and a right part around each determined discontinuity. The attribute `objects` is then the list of these parts, where each part is an object of `plot::Function2d`. If `f` has no discontinuities, or if the value of the option Discont is `FALSE`, then this list only consists of one entry, the (whole) graph. Note that if you extract an object of this list and do some changes to this object, then you must set the value of the attribute `refreshPlotdata` to `TRUE` in order to force a rebuild of the plot data of the graph. | read
  `options` | A table of plot options of the function primitive. Note that if you change the value of this attribute, the entries of the assigned table are not checked to be valid plot options for function primitives. Invalid entries lead to runtime errors. The initial value of this attribute is the table stored under the domain entry `"defaultOptions"`, where such options are replaced and added, respectively, which are given with the parameters `option1`, `option2`... of the creating call. | read/write
  `plotdata` | List of the plot data of the function primitive in a `plot2d` conforming syntax (see the method `"getPlotdata"` below). Note that the value of this attribute should only be used if the attribute `refreshPlotdata` has the value `FALSE` (see below). | read
  `range` | The variable of the function and its range in the form `ident = a..b`. The initial value is the parameter `x = a..b`. | read/write
  `refreshPlotdata` | A boolean value which signals whether the plot data of the function primitive must be (re-)build with the method `"getPlotdata"` (see below). If its value is `FALSE`, then the plot data of the function primitive is stored in the attribute `plotdata`. The initial value is `TRUE`. See the help page of `plot::Curve2d` for an example. | read/write
  `term` | The term of the function (an arithmetical expression). The initial value is the parameter `f`. | read/write
  `yrange` | The ``y-range'' of the graph (see above). It is either of the form `ymin..ymax`, or the value `Automatic`. The initial value is the parameter `ymin..ymax`, if the parameter was given in the function call, or the value `Automatic` otherwise. | read/write

#### Option: Discont =

`value`

- This option determines, whether the function `f(x)` is checked for discontinuities. Admissible values are `TRUE` and `FALSE`; the default is Discont = `TRUE`.
  - Discont = `TRUE` enables symbolic checking of discontinuities of `f`. If found, unwanted graphical effects such as spurious lines at the discontinuities are eliminated.
  - Discont = `FALSE` disables the check.
  See example 4.

#### Option: RealValuesOnly =

`value`

- If the function `f(x)` produces a complex value during the evaluation of the plot, then an error occurs. Specifying RealValuesOnly = `TRUE`, such errors are trapped. Only those parts of the function producing real values are plotted. E.g., with this option the function `sqrt(x)` can be plotted over the interval x = -1..1: the plot only displays the real function values for x >=0.

  With RealValuesOnly = `FALSE` no internal check is performed. The renderer produces an error, when it encounters a complex value. The default is RealValuesOnly = `TRUE`.

#### Operands

An object of `plot::Function2d` consists of three operands. The first operand is the term `f` of the function. The second one is the variable `x` of the term and its range in the form `x = a..b`. The third one is the value `Automatic`, or the range `ymin..ymin` if the parameter `y = ymin..ymax` was given.

#### Important Operations

Operands of a function primitive can be accessed either using the system function `op`, the index operator `[ ]`, or using the attributes described above. For example, if `function` is such an object, then the calls `op(function,1)`, `function[1]` and `function::term` return the term `f`.

Via `function[1] := f` or `function::term := f`, the term of a function primitive can be changed.

See the methods `"op"`, `"_index"`, `"set_index"` and `"slot"` below.

Use the slot operator `::` to get or set plot options of such objects afterwards, i.e., when they have been created. For example, if `function` is such an object, then `function::Color := RGB::Red` changes the color of the function primitive `function` to red.

#### Result of Evaluation

Evaluating an object of type `plot::Function2d` returns itself.

#### Function Call

Calling an object of `plot::Function2d` as a function yields the object itself, regardless of the arguments. The arguments are not evaluated.

#### Entries

defaultOptions

  is a table of plot options for function primitives and their default values. Each entry has the form `OptionName = default_value`.

  When an object of the domain `plot::Function2d` is created, then a copy of this table is stored under the attribute `options` (see the table of attributes above), where those options are added and replaced, respectively, which are given by the (optional) parameters `option1`, `option2`... of the creating call (see ``Creating Elements'' above).

  Plot options, which are not contained in the table stored under the attribute `options` will not be included in the plot data of the object created by the method `"getPlotdata"` (see below).

  For those options, the corresponding default value either is set by a graphical scene, if the option also exists as a scene option (such as the option PointWidth), or it is internally set by the function `plot2d` which is used to plot the object. See the table of plot options above, which gives a summary of the available plot options for function primitives and their default values. See example 4.

  To change the default value of some plot options, the option name and its default value may be added to the table `"defaultOptions"`, or replaced by a new value, respectively.

optionNames

  is a set of the available option names for plots of two-dimensional graphs of functions.

#### Method _index: indexed access to the operands of a function primitive

- `_index(dom function, positive integer i)`
- - Returns the `i`th operand of `function`.See ``Operands'' above for a description of the operands of `function`. If `i` is greater than 3, then `FAIL` is returned.
  - This method overloads the system function `_index`, i.e., one may use it in the form `function[i]`, or in functional notation `_index(function, i)`.

#### Method dimension: dimension of a function primitive

- `dimension(dom function)`
- - Returns the integer 2.

#### Method getPlotdata: the plot data of a function primitive

- `getPlotdata(dom function)`
- - Returns a list of inner lists, where each inner list is a plot description of a two-dimensional curve in a `plot2d` conforming syntax, i.e., an inner list has the form `[Mode = Curve, [...], ...]`.

    For example, with `s := plot::Function2d::getPlotdata(function)` the call `plot2d(op(s))` gives a plot of `function`.

  - Only those plot options will be included in the plot data of the function, that are contained in the table stored under the attribute `options` (see the table of attributes above). For any other plot option not contained in this table, the corresponding default value set by the function `plot2d` for curves is used when plotting the object.
  - The result is stored as the value of the attribute `plotdata` of `function`.
  - A call of this method sets the value of the attribute `refreshPlotdata` of `function` to `FALSE`.
  - This method is called from `plot::Scene` to build the plot data of the graphical scene.

#### Method nops: number of operands of a function primitive

- `nops(dom function)`
- - Returns the integer 3.
  - This method overloads the system function `nops`, i.e., one may use it in the form `nops(function)`.

#### Method op: extract operands of a function primitive

- `op(dom function, positive integer i)`
- - Returns the `i`th operand of `function`. See ``Operands'' above for a description of the operands of `function`. If `i` is greater than 3, then `FAIL` is returned.
  - This method overloads the system function `op`, i.e., one may use it in the form `op(function, i)`.

#### Method set_index: set operands of a function primitive

- `set_index(dom function, positive integer i, any val)`
- - Replaces the `i`th operand of `function` by the value `val`. See ``Operands'' above for a description of the operands of `function`.
  - If `i` is greater than 3, or if `val` is not an admissible value for the `i`th operand, then a warning message is issued. In this case the call of this method has no effect on the object `function`.
  - A call of this method sets the value of the attribute `refreshPlotdata` of `function` to `TRUE`.

#### Method slot: read and write attributes and plot options

- `slot(dom function, string slotname)`
- - Reads the value of the slot `slotname` of `function`. `slotname` may either be the name of an attribute or the name of a plot option. See the tables of available plot options and attributes above.
  - If `slotname` is the name of a plot option, but the option is not contained in the table stored under the attribute `options`, then `FAIL` is returned.

    If `slotname` is an invalid attribute or option, then an error message is issued.

  - This method overloads the system function `slot`, i.e., one may use it in the form `function::slotname_id` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(function, slotname)`.
- `slot(dom function, string slotname, any val)`
- - Changes the value of the attribute or option with the name `slotname` to the value `val`.
  - If there is no attribute or option with the name `slotname`, or if `val` is not an admissible value for `slotname`, then a warning message is issued. In this case, the value of `slotname` remains unchanged.
  - This method overloads the system function `slot`, i.e., one may use it in the form `function::slotname_id := val` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(function, slotname, val)`.
  - The value of the attribute `refreshPlotdata` of `function` is set to `TRUE`.

#### Method checkOption: check a plot options

- `checkOption(equation OptionName = value)`
- - This method checks whether `OptionName` is a known plot option for function primitives (see the table of available plot options above), and `value` is an admissible for this option.
  - If both is correct, then the list `[TRUE, OptionName, newValue]` is returned. Note that the value of the option could have been converted into an admissible format. Thus, `newValue` must be used as the value of the option `OptionName` instead of `value`.
  - Otherwise, the list `[FALSE, error_msg]` is returned. The string `error_msg` is a description of the located problem, which can be passed, for example, to the system function `error` to raise a user-specified exception.

#### Method copy: create a copy of a function plot

- `copy(dom function)`
- - Returns a copy of the object `function`.
  - This method is called from the function `plot::copy`. See its help page for details.

#### Method modify: modify a copy of a function plot

- `modify(dom function, equation(s) Name1 = value1...)`
- - Creates a copy of the object `function` and changes the slots `Name1`... of this copy to the new values `value1`...
  - The identifiers `Name1`... must be names of attributes or plot options of the domain `plot::Function2d`. Otherwise a warning message is issued, and the slot remains unchanged. Also, if one of the values `value1`... is not an admissible value for the corresponding attribute or plot option, respectively, the change of the slot is ignored.

    See the tables of available options and attributes above.

  - A call of this method sets the value of the attribute `refreshPlotdata` of the copy of `function` to `TRUE`.
  - This method is called from the function `plot::modify`.

#### Method print: print a function primitive

- `print(dom function)`
- - This method returns an unevaluated expression of the form `plot::Function2d(f, x = a..b)`. It is used to print objects of `plot::Function2d` to the screen.
  - See the system function `print` for details.

#### Example 1

The following call returns an object representing the graph of the sine function in the interval [0, 2*PI]:

    >> f := plot::Function2d(sin(x), x = 0..2*PI)

                       plot::Function2d(sin(x), x = 0..2 PI)

To plot the graph in a graphical scene, call `plot`:

    >> plot(f)

To restrict the y-range of the graph, for example, to the interval [0,1], specify a second range in the call of `plot::Function2d`:

    >> f2 := plot::Function2d(sin(x), x = 0..2*PI, y = 0..1):
       plot(f)

The variable of the second range can be any identifier, that, of course, differs from the variable of the function term (here: x).

Plot options of the curve can be given as additional parameters in the creating call, such as plotting the graph in green color and changing its style so that it is drawn as impulses:

    >> f3 := plot::Function2d(sin(x), x = 0..2*PI,
         Color = RGB::Green, Style = [Impulses]
       )

                       plot::Function2d(sin(x), x = 0..2 PI)

    >> plot(f3)

To change default values of some scene options, pass the scene options to the call of `plot` as additional arguments. For example, to draw grid lines in the background of the plot, call:

    >> plot(f, GridLines = Automatic)

See the help page of `plot::Scene` for available scene options.

#### Example 2

We want to plot a graph of the sequence n -> sin(n)/n in the interval [1, 50], enclosed by the graphs of the functions x -> 1/x and x -> -1/x. We start by creating the three different graphical primitives as follows:

    >> f1 := plot::Function2d(1/x, x = 1..50);
       f2 := plot::Function2d(-1/x, x = 1..50);
       a  := plot::Pointlist([n, sin(n)/n] $ n = 1..50, Color = RGB::Blue)

                                         / 1            \
                         plot::Function2d| -, x = 1..50 |
                                         \ x            /

                                        /   1            \
                        plot::Function2d| - -, x = 1..50 |
                                        \   x            /

                                 plot::Pointlist()

To plot the scene of these objects, pass them as parameters to the function `plot`:

    >> plot(f1, f2, a)

#### Example 3

The process of the clipping the graph of a function plot can fail and produce plots outside the specified rectangle. This is the case, for example, if the function strongly oscillates in the given interval.

Consider the function sin(exp(x)) for x in [-5, 5]. We are interested only in the positive part of the graph, and thus enter:

    >> f := plot::Function2d(sin(exp(x)), x = -5..5, y = 0..1):
       plot(f)

The clipping of the graph fails in this example (see the note in the ``Details'' above). It can be helpful in such cases to increase the value of the option Grid:

    >> f::Grid:= [500]: plot(f)

#### Example 4

If a function primitive is created, values of some plot options of the created object can be read, or replaced by new values.

To illustrate this, we create the following function:

    >> f1 := plot::Function2d(1/x^2, x = -5..5, Color = RGB::Blue)

                                         / 1             \
                         plot::Function2d| --, x = -5..5 |
                                         |  2            |
                                         \ x             /

We create a copy of the graph, change some plot options of the copied object, and plot both objects in a graphical scene:

    >> f2 := plot::copy(f1):
       f2::Style := [Impulses]: f2::Grid := [20]:
       f2::Color := RGB::Red:
       plot(f1, f2)

Plot options, which are explicitely set for a function primitive, are stored under the attribute `options` and can be read with the slot operator `::`. The plot options for the first created object are:

    >> f1::options

                         table(
                           RealValuesOnly = TRUE,
                           Discont = TRUE,
                           Grid = [100],
                           Color = [Flat, [0.0, 0.0, 1.0]]
                         )

These are default values of some plot options of two-dimensional function primitives, defined by the entry `"defaultOptions"` of the domain `plot::Function2d`:

    >> plot::Function2d::defaultOptions

                         table(
                           RealValuesOnly = TRUE,
                           Discont = TRUE,
                           Grid = [100],
                           Color = [Flat, [1.0, 0.0, 0.0]]
                         )

When the plot data of a function primitive is created (calling the method `"getPlotdata"`), only those plot options are used that are contained in the table stored under the attribute `options` (here this is the table `f1::options`):

    >> plot::Function2d::getPlotdata(f1)

          -- --               --    1  --
          |  |  Mode = Curve, |  x, --  |, x = [-5.0, -0.1413648217],
          |  |                |      2  |
          -- --               --    x  --

                                                           --
             Grid = [100], Color = [Flat, [0.0, 0.0, 1.0]]  |,
                                                            |
                                                           --

             --               --    1  --
             |  Mode = Curve, |  x, --  |, x = [0.1413648217, 5.0],
             |                |      2  |
             --               --    x  --

                                                                       --
             Title = "", Grid = [100], Color = [Flat, [0.0, 0.0, 1.0]]  |
                                                                        |
                                                                       --

             --
              |
              |
             --

This means that for any other available plot option not contained in the table `f1::options`, the default value is either set by `plot::Scene`, if the option also exists as a scene option, or it is internally set by the function `plot2d` when plotting the object.

This example also illustrates that `plot::Function2d` automatically determines discontinuities and splits the graph into two subgraphs around each discontinuity (these subgraphs are stored in the attribute `objects`, see above).

Here, the graph of 1/x^2 was splitted around 0 into two subgraphs. Thus, the plot structure in a `plot2d` conforming syntax consists of two objects of the mode `Curve`.

The determination of discontinuities can be controlled with the option Discont. If we set this option to `FALSE`, discontinuities are not determined. The plot structure of the function primitive then only consists of one object:

    >> f1::Discont:= FALSE: plot::Function2d::getPlotdata(f1)

          -- --               --    1  --
          |  |  Mode = Curve, |  x, --  |, x = [-5.0, 5.0],
          |  |                |      2  |
          -- --               --    x  --

                                                           -- --
             Grid = [100], Color = [Flat, [0.0, 0.0, 1.0]]  |  |
                                                            |  |
                                                           -- --

Computation problems during the evaluation of the plot is the consequence here:

    >> plot(f1)

The function primitive `f2` contains the following options:

    >> f2::options

                         table(
                           Style = [Impulses],
                           RealValuesOnly = TRUE,
                           Discont = TRUE,
                           Grid = [20],
                           Color = [Flat, [1.0, 0.0, 0.0]]
                         )

As you see, the option Style was added to this table, and the default value of the option Grid was replaced by the new value `[20]`. Use `delete` to remove plot options set for a curve primitive:

    >> delete f2::options[Style]: f2::options

                         table(
                           RealValuesOnly = TRUE,
                           Discont = TRUE,
                           Grid = [20],
                           Color = [Flat, [1.0, 0.0, 0.0]]
                         )

You might wonder why the options RealValuesOnly and Discont are not contained in the plot structure returned by the method `"getPlotdata"`. They are special options for objects of the domain `plot::Function2d`, used to determine the plot data of such an object. They are not accepted as valid options for curves plotted directly with `plot2d`.

#### Example 5

This example illustrates how to read and write attributes of function primitives (see the table of available attributes in ``Details'' above).

In the last example, we already used the attribute `options`, which stores plot options defined individually for a function primitive to override the corresponding default values set by MuPAD.

The attribute `yrange` holds the ``y-range'' of the function graph. Its value is either a range of the form `y = ymin..ymax`, or the identifier `Automatic`.

For example, if `function` is an object of `plot::Function2d` such as:

    >> f := plot::Function2d(ln(x), x = 0..10)

                        plot::Function2d(ln(x), x = 0..10)

then `f::yrange` returns the default value of this attribute:

    >> f::yrange

                                     Automatic

We plot this curve:

    >> plot(f)

Because the attribute `yrange` has the ``write'' property, you can change the value of this attribute as follows:

    >> f::yrange := 0..1: plot(f)

#### Changes

- new function

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