useunits (boolean or list): Indicates presence of units in input or specifies units to be used.

The plot and plot3d commands allow input arguments that involve units. Units may appear in the expression or procedure to be plotted or in the range arguments. These units are then included in the axis labels.

This help page describes the use of units in the parameters of plot and plot3d. For general information about the calling sequences of these commands, see plot and plot3d.

If f is an expression containing a unit, then the plot is computed using the quantity, without the unit, and the unit is included as part of the dependent axis label (that is, the y-axis label for 2-D plots and the z-axis label for 3-D plots).

If f is a procedure that evaluates to a numeric value with a unit, then the unit is ignored during computation. (See the Notes section below for more information.)

The range arguments r1 and r2 can be in the form of a simple range, a..b, or an equation with a variable name as the left-hand side, var=a..b. If the range a..b contains a unit, then that unit is included in the label for that axis. The unit must then be given for both a and b. If a and b contain different units, then the plotting command attempts to convert them to a common unit and issues an error if this is not possible.

If the range argument r1 and/or r2 has a unit and f is an expression, then the corresponding variable(s) var will be substituted with an appropriate unit attached. If r1 and/or r2 has a unit and f is a procedure, then the corresponding argument(s) will have an appropriate unit attached.

The third and fourth calling sequences create parametric plots. The ranges have their end points a and b converted to a common unit if necessary, like in the first two calling sequences. However, these units do not correspond to the units on the axes. Instead, the units on the axes are taken from the x, y, and (if applicable) z arguments.

The useunits option may be used for two purposes:

useunits=true (or simply useunits) tells the plotting command that the input procedure involves computation with units.  This is necessary if there is no other indication through the ranges of the presence of units.

useunits=[unit1, unit2] or [unit1, unit2, unit3] can be used to specify the units for each axis. What this means depends on whether this is a dependent or independent axis, and whether units would be used if no useunits option were given, and if so, which units. For each of the cases below, suppose the unit unitA is given through the useunits option. The unit unitB is defined as follows:

For a parametric plot, for the x-axis, unitB is the unit of the quantity to which x evaluates. If x evaluates to a unitless quantity, then unitB is equal to 1. For the y- and z-axes, unitB similarly depends on y and z, respectively.

For an independent axis in a nonparametric plot (the x-axis for 2D plots, and the x- and y-axes for 3D plots), unitB is the unit in which the range for this axis is given. If no unit is given, then unitB is equal to 1.

For a dependent axis in a nonparametric plot (the y-axis for 2D plots, and the z-axis for 3D plots), unitB is the unit of the quantity to which f evaluates. If f evaluates to a unitless quantity, then unitB is equal to 1.

If the labels option is provided, then that value is used for the axes labels, overriding any default labels computed from the function and range arguments or the useunits option.

All other plot options normally available with the plot and plot3d commands can be provided, but units in these option values are not generally understood or processed.

For the sake of efficient computation, if f or x or y or z is a procedure, values computed from it are assumed to be unit-free unless there is an indication that units are present.  For this reason, you must explicitly specify the units desired, either through the ranges or through the useunits option.  If the useunits=true option is not provided with a procedure that produces values containing units, an empty plot might result.

Plotting commands generally try to use the faster evalhf mode of computation whenever possible. (For more information about the evalhf mode, see the plot/computation help page.) However, evalhf does not work with procedures that return values with units. If you want to plot a procedure that involves extremely intensive computation, it is recommended you do not perform computations with units within the procedure.

For axis labels, any unit information provided in the ranges overrides units provided in the plotting function. Additionally, the value of the useunits option, if given, overrides all other unit information given in the other arguments. However, if the labels option is provided, then that is used by the plotting command to generate axis labels and units information is ignored.

$\mathrm{plot}\left(x^2\mathrm{Unit}\left(m\right)\,x=-5..5\right)$

$\mathrm{plot}\left(\sin \left(x\right)\,x=-2\mathrm{\pi }\mathrm{Unit}\left(\mathrm{radians}\right)..2\mathrm{\pi }\mathrm{Unit}\left(\mathrm{radians}\right)\,\mathrm{axis}\left[1\right]=\left[\mathrm{tickmarks}=\left[\mathrm{spacing}\left(\mathrm{\pi }\right)\right]\right]\,\mathrm{color}=''Indigo''\right)$

$\mathrm{plot}\left(\left[x^2\,0.5x^2\right]\,x=150\mathrm{Unit}\left(\mathrm{cm}\right)..5\mathrm{Unit}\left(m\right)\,\mathrm{axes}=\mathrm{boxed}\right)$

$\mathrm{plot}\left(x\mapsto x^2\cdot \mathrm{Unit}\left(m\right)\,-5..5\,\mathrm{useunits}\,\mathrm{thickness}=2\,\mathrm{color}=''DarkGreen''\right)$

$\mathrm{plot}\left(x\mapsto \cos \left(x\right)\,0..2\mathrm{\pi }\mathrm{Unit}\left(\mathrm{radians}\right)\,-2\mathrm{Unit}\left(m\right)..2\mathrm{Unit}\left(m\right)\,\mathrm{axis}\left[1\right]=\left[\mathrm{tickmarks}=\left[\mathrm{spacing}\left(\frac{\mathrm{\pi }}{2}\right)\right]\right]\right)$

$\mathrm{speed}≔10\mathrm{Unit}\left(\frac{\mathrm{ft}}{s}\right)$

$\mathrm{speed}≔10⟦\frac{\mathrm{ft}}{s}⟧$

$\mathrm{frequency}≔4\mathrm{Unit}\left(\mathrm{Hz}\right)$

$\mathrm{frequency}≔4⟦\mathrm{Hz}⟧$

$\mathrm{plot}\left(\left[x^2\,\sin \left(\frac{x\mathrm{frequency}}{\mathrm{speed}}\right)\,x=-5\mathrm{Unit}\left(m\right)..5\mathrm{Unit}\left(m\right)\right]\right)$

$\mathrm{lookup}≔\mathrm{Interpolation}:-\mathrm{Interpolate}\left(\left[\mathrm{seq}\left(1..10\right)\right]\,\left[2\,5\,1\,2\,6\,3\,-4\,2\,4\,5\right]\,\mathrm{method}=\mathrm{nearest}\right)$

$\mathrm{lookup}≔\left[\begin{array}{c}\text{a nearest interpolation object}\\ \text{with 10 points in 1-D}\end{array}\right]$

$\mathrm{plot}\left(\mathrm{lookup}\,1..10\,\mathrm{useunits}=\left[\mathrm{Unit}\left(s\right)\,\mathrm{Unit}\left(m\right)\right]\right)$

$\mathrm{plot}\left(\mathrm{lookup}\,1..10\,\mathrm{labels}=\left[\mathrm{Unit}\left(s\right)\,\mathrm{Unit}\left(m\right)\right]\right)$

$\mathrm{plot3d}\left(x^2+2y\,x=-\mathrm{Unit}\left(m\right)..2\mathrm{Unit}\left(m\right)\,y=0..4\mathrm{Unit}\left(m^2\right)\,\mathrm{useunits}=\left[\mathrm{Unit}\left(\mathrm{ft}\right)\,\mathrm{Unit}\left({\mathrm{ft}}^2\right)\,\mathrm{Unit}\left({\mathrm{ft}}^2\right)\right]\right)$

The Plots with Units command was updated in Maple 2022.