\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gnuplot.info
@settitle Gnuplot: An Interactive Plotting Program
@setchapternewpage odd
@c %**end of header
@c define the command and options indeces
@defindex cm
@defindex op
@defindex tm
@direntry
* GNUPLOT: (gnuplot). An Interactive Plotting Program
@end direntry
@ifnottex
@node Top, gnuplot, (dir), (dir)
@top Master Menu
@end ifnottex
@example
GNUPLOT
An Interactive Plotting Program
Thomas Williams & Colin Kelley
Version 3.7 organized by: David Denholm
Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
Mailing list for comments: info-gnuplot@@dartmouth.edu
Mailing list for bug reports: bug-gnuplot@@dartmouth.edu
This manual was prepared by Dick Crawford
3 December 1998
Major contributors (alphabetic order):
@end example
@c ^
An Interactive Plotting Program
@c ^
Thomas Williams & Colin Kelley
@c ^
Version 3.7 organized by: David Denholm
@c ^
Major contributors (alphabetic order):
@itemize @bullet
@item
Hans-Bernhard Broeker
@item
John Campbell
@item
Robert Cunningham
@item
David Denholm
@item
Gershon Elber
@item
Roger Fearick
@item
Carsten Grammes
@item
Lucas Hart
@item
Lars Hecking
@item
Thomas Koenig
@item
David Kotz
@item
Ed Kubaitis
@item
Russell Lang
@item
Alexander Lehmann
@item
Alexander Mai
@item
Carsten Steger
@item
Tom Tkacik
@item
Jos Van der Woude
@item
James R. Van Zandt
@item
Alex Woo
@end itemize
@c ^
Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
@c ^ Mailing list for comments: info-gnuplot@@dartmouth.edu
@c ^ Mailing list for bug reports: bug-gnuplot@@dartmouth.edu
@c ^
@c ^
This manual was prepared by Dick Crawford
@c ^
3 December 1998
@c ^
@menu
* gnuplot::
* Commands::
* Graphical_User_Interfaces::
* Bugs::
* Concept_Index::
* Command_Index::
* Options_Index::
* Function_Index::
* Terminal_Index::
@end menu
@node gnuplot, Commands, Top, Top
@chapter gnuplot
@menu
* Copyright::
* Introduction::
* Seeking-assistance::
* What's_New_in_version_3.7::
* bind::
* Batch/Interactive_Operation::
* Command-line-editing::
* Comments::
* Coordinates::
* Environment::
* Expressions::
* Glossary::
* Plotting::
* Start-up::
* Substitution::
* Syntax::
* Time/Date_data::
@end menu
@node Copyright, Introduction, gnuplot, gnuplot
@section Copyright
@cindex copyright
@cindex license
@example
Copyright (C) 1986 - 1993, 1998 Thomas Williams, Colin Kelley
@end example
Permission to use, copy, and distribute this software and its
documentation for any purpose with or without fee is hereby granted,
provided that the above copyright notice appear in all copies and
that both that copyright notice and this permission notice appear
in supporting documentation.
Permission to modify the software is granted, but not the right to
distribute the complete modified source code. Modifications are to
be distributed as patches to the released version. Permission to
distribute binaries produced by compiling modified sources is granted,
provided you
@example
1. distribute the corresponding source modifications from the
released version in the form of a patch file along with the binaries,
2. add special version identification to distinguish your version
in addition to the base release version number,
3. provide your name and address as the primary contact for the
support of your modified version, and
4. retain our contact information in regard to use of the base
software.
@end example
Permission to distribute the released version of the source code along
with corresponding source modifications in the form of a patch file is
granted with same provisions 2 through 4 for binary distributions.
This software is provided "as is" without express or implied warranty
to the extent permitted by applicable law.
@example
AUTHORS
@end example
@example
Original Software:
Thomas Williams, Colin Kelley.
@end example
@example
Gnuplot 2.0 additions:
Russell Lang, Dave Kotz, John Campbell.
@end example
@example
Gnuplot 3.0 additions:
Gershon Elber and many others.
@end example
@node Introduction, Seeking-assistance, Copyright, gnuplot
@section Introduction
@cindex introduction
@c ?
`gnuplot` is a command-driven interactive function and data plotting program.
It is case sensitive (commands and function names written in lowercase are
not the same as those written in CAPS). All command names may be abbreviated
as long as the abbreviation is not ambiguous. Any number of commands may
appear on a line (with the exception that `load` or @ref{call} must be the final
command), separated by semicolons (;). Strings are indicated with quotes.
They may be either single or double quotation marks, e.g.,
@example
load "filename"
cd 'dir'
@end example
although there are some subtle differences (see `syntax` for more details).
Any command-line arguments are assumed to be names of files containing
`gnuplot` commands, with the exception of standard X11 arguments, which are
processed first. Each file is loaded with the `load` command, in the order
specified. `gnuplot` exits after the last file is processed. When no load
files are named, `gnuplot` enters into an interactive mode. The special
filename "-" is used to denote standard input. See "help batch/interactive"
for more details.
Many `gnuplot` commands have multiple options. These options must appear in
the proper order, although unwanted ones may be omitted in most cases. Thus
if the entire command is "command a b c", then "command a c" will probably
work, but "command c a" will fail.
Commands may extend over several input lines by ending each line but the last
with a backslash (\). The backslash must be the _last_ character on each
line. The effect is as if the backslash and newline were not there. That
is, no white space is implied, nor is a comment terminated. Therefore,
commenting out a continued line comments out the entire command (see
`comment`). But note that if an error occurs somewhere on a multi-line
command, the parser may not be able to locate precisely where the error is
and in that case will not necessarily point to the correct line.
In this document, curly braces (@{@}) denote optional arguments and a vertical
bar (|) separates mutually exclusive choices. `gnuplot` keywords or @ref{help}
topics are indicated by backquotes or `boldface` (where available). Angle
brackets () are used to mark replaceable tokens. In many cases, a default
value of the token will be taken for optional arguments if the token is
omitted, but these cases are not always denoted with braces around the angle
brackets.
For on-line help on any topic, type @ref{help} followed by the name of the topic
or just @ref{help} or `?` to get a menu of available topics.
The new `gnuplot` user should begin by reading about `plotting` (if on-line,
type `help plotting`).
@uref{http://www.nas.nasa.gov/~woo/gnuplot/simple/simple.html,Simple Plots Demo }
@node Seeking-assistance, What's_New_in_version_3.7, Introduction, gnuplot
@section Seeking-assistance
@cindex seeking-assistance
There is a mailing list for `gnuplot` users. Note, however, that the
newsgroup
@example
comp.graphics.apps.gnuplot
@end example
is identical to the mailing list (they both carry the same set of messages).
We prefer that you read the messages through the newsgroup rather than
subscribing to the mailing list. Administrative requests should be sent to
@example
majordomo@@dartmouth.edu
@end example
Send a message with the body (not the subject) consisting of the single word
"help" (without the quotes) for more details.
The address for mailing to list members is:
@example
info-gnuplot@@dartmouth.edu
@end example
Bug reports and code contributions should be mailed to:
@example
bug-gnuplot@@dartmouth.edu
@end example
The list of those interested in beta-test versions is:
@example
info-gnuplot-beta@@dartmouth.edu
@end example
There is also a World Wide Web page with up-to-date information, including
known bugs:
@uref{http://www.cs.dartmouth.edu/gnuplot_info.html,http://www.cs.dartmouth.edu/gnuplot_info.html
}
Before seeking help, please check the
@uref{http://www.uni-karlsruhe.de/~ig25/gnuplot-faq.html,FAQ (Frequently Asked Questions) list.
}
If you do not have a copy of the FAQ, you may request a copy by email from
the Majordomo address above, ftp a copy from
@example
ftp://ftp.dartmouth.edu/pub/gnuplot
@end example
or see the WWW `gnuplot` page.
When posting a question, please include full details of the version of
`gnuplot`, the machine, and operating system you are using. A _small_ script
demonstrating the problem may be useful. Function plots are preferable to
datafile plots. If email-ing to info-gnuplot, please state whether or not
you are subscribed to the list, so that users who use news will know to email
a reply to you. There is a form for such postings on the WWW site.
@node What's_New_in_version_3.7, bind, Seeking-assistance, gnuplot
@section What's New in version 3.7
@cindex new-features
Gnuplot version 3.7 contains many new features. This section gives a partial
list and links to the new items in no particular order.
1. `fit f(x) 'file' via` uses the Marquardt-Levenberg method to fit data.
(This is only slightly different from the `gnufit` patch available for 3.5.)
2. Greatly expanded @ref{using} command. See @ref{using}.
3. @ref{timefmt} allows for the use of dates as input and output for time
series plots. See `Time/Date data` and
@uref{http://www.nas.nasa.gov/~woo/gnuplot/timefmt/timefmt.html,timedat.dem.
}
4. Multiline labels and font selection in some drivers.
5. Minor (unlabeled) tics. See @ref{mxtics}.
6. @ref{key} options for moving the key box in the page (and even outside of the
plot), putting a title on it and a box around it, and more. See @ref{key}.
7. Multiplots on a single logical page with @ref{multiplot}.
8. Enhanced `postscript` driver with super/subscripts and font changes.
(This was a separate driver (`enhpost`) that was available as a patch for
3.5.)
9. Second axes: use the top and right axes independently of the bottom and
left, both for plotting and labels. See @ref{plot}.
10. Special datafile names `'-'` and `""`. See @ref{special-filenames}.
11. Additional coordinate systems for labels and arrows. See `coordinates`.
12. @ref{size} can try to plot with a specified aspect ratio.
13. @ref{missing} now treats missing data correctly.
14. The @ref{call} command: `load` with arguments.
15. More flexible `range` commands with `reverse`, `writeback`, and `restore`
keywords.
16. @ref{encoding} for multi-lingual encoding.
17. New `x11` driver with persistent and multiple windows.
18. New plotting styles: @ref{xerrorbars}, @ref{errorlines}, @ref{yerrorlines},
@ref{xerrorlines}, @ref{xyerrorlines}, @ref{histeps}, @ref{financebars} and more.
See @ref{style}.
19. New tic label formats, including `"%l %L"` which uses the mantissa and
exponents to a given base for labels. See `set format`.
20. New drivers, including `cgm` for inclusion into MS-Office applications
and `gif` for serving plots to the WEB.
21. Smoothing and spline-fitting options for @ref{plot}. See @ref{smooth}.
22. @ref{margin} and @ref{origin} give much better control over where a
graph appears on the page.
23. @ref{border} now controls each border individually.
24. The new commands @ref{if} and @ref{reread} allow command loops.
25. Point styles and sizes, line types and widths can be specified on the
@ref{plot} command. Line types and widths can also be specified for grids,
borders, tics and arrows. See @ref{with}. Furthermore these types may be
combined and stored for further use. See `set style line`.
26. Text (labels, tic labels, and the time stamp) can be written vertically
by those terminals capable of doing so.
@node bind, Batch/Interactive_Operation, What's_New_in_version_3.7, gnuplot
@section bind
@c ?commands bind
@cindex bind
The @ref{bind} command allows to (re-)define a sequence of gnuplot commands
which will be executed when a certain key or key sequence is pressed
while the driver's window has the input focus.
Note that @ref{bind} is only available if gnuplot was compiled with mouse
support and it is used by all mouse-capable terminals.
Bindings overwrite the builtin bindings (like in every real editor),
except and 'q' which cannot be rebound.
Mouse Buttons cannot be rebound.
Note that multikey-bindings with modifiers have to be quoted.
Syntax:
@example
bind [] [""]
bind!
@end example
Examples:
- set bindings:
@example
bind a "replot"
bind "ctrl-a" "plot x*x"
bind "ctrl-alt-a" 'print "great"'
bind Home "set view 60,30; replot"
@end example
- show bindings:
@example
bind "ctrl-a" # shows the binding for ctrl-a
bind # shows all bindings
@end example
- remove bindings:
@example
bind "ctrl-alt-a" "" # removes binding for ctrl-alt-a
(note that builtins cannot be removed)
bind! # installs default (builtin) bindings
@end example
- bind a key to toggle something:
@example
v=0
bind "ctrl-r" "v=v+1;if(v%2)set term x11 noraise; else set term x11 raise"
@end example
Modifiers (ctrl / alt) are case insensitive, keys not:
@example
ctrl-alt-a == CtRl-alT-a
ctrl-alt-a != ctrl-alt-A
@end example
List of modifiers (alt == meta):
@example
ctrl, alt
@end example
List of supported special keys:
@example
"BackSpace", "Tab", "Linefeed", "Clear", "Return", "Pause", "Scroll_Lock",
"Sys_Req", "Escape", "Delete", "Home", "Left", "Up", "Right", "Down",
"PageUp", "PageDown", "End", "Begin",
@end example
@example
"KP_Space", "KP_Tab", "KP_Enter", "KP_F1", "KP_F2", "KP_F3", "KP_F4",
"KP_Home", "KP_Left", "KP_Up", "KP_Right", "KP_Down", "KP_PageUp",
"KP_PageDown", "KP_End", "KP_Begin", "KP_Insert", "KP_Delete", "KP_Equal",
"KP_Multiply", "KP_Add", "KP_Separator", "KP_Subtract", "KP_Decimal",
"KP_Divide",
@end example
@example
"KP_1" - "KP_9", "F1" - "F12"
@end example
see also @ref{mouse} and @ref{if}.
@node Batch/Interactive_Operation, Command-line-editing, bind, gnuplot
@section Batch/Interactive Operation
@cindex batch/interactive
`gnuplot` may be executed in either batch or interactive modes, and the two
may even be mixed together on many systems.
Any command-line arguments are assumed to be names of files containing
`gnuplot` commands (with the exception of standard X11 arguments, which are
processed first). Each file is loaded with the `load` command, in the order
specified. `gnuplot` exits after the last file is processed. When no load
files are named, `gnuplot` enters into an interactive mode. The special
filename "-" is used to denote standard input.
Both the @ref{exit} and @ref{quit} commands terminate the current command file and
`load` the next one, until all have been processed.
Examples:
To launch an interactive session:
@example
gnuplot
@end example
To launch a batch session using two command files "input1" and "input2":
@example
gnuplot input1 input2
@end example
To launch an interactive session after an initialization file "header" and
followed by another command file "trailer":
@example
gnuplot header - trailer
@end example
@node Command-line-editing, Comments, Batch/Interactive_Operation, gnuplot
@section Command-line-editing
@cindex line-editing
@cindex editing
@cindex history
@cindex command-line-editing
Command-line editing is supported by the Unix, Atari, VMS, MS-DOS and OS/2
versions of `gnuplot`. Also, a history mechanism allows previous commands to
be edited and re-executed. After the command line has been edited, a newline
or carriage return will enter the entire line without regard to where the
cursor is positioned.
(The readline function in `gnuplot` is not the same as the readline used in
GNU Bash and GNU Emacs. If the GNU version is desired, it may be selected
instead of the `gnuplot` version at compile time.)
The editing commands are as follows:
@example
`Line-editing`:
@end example
@example
^B moves back a single character.
^F moves forward a single character.
^A moves to the beginning of the line.
^E moves to the end of the line.
^H and DEL delete the previous character.
^D deletes the current character.
^K deletes from current position to the end of line.
^L,^R redraws line in case it gets trashed.
^U deletes the entire line.
^W deletes the last word.
@end example
@example
`History`:
@end example
@example
^P moves back through history.
^N moves forward through history.
@end example
On the IBM PC, the use of a TSR program such as DOSEDIT or CED may be desired
for line editing. The default makefile assumes that this is the case; by
default `gnuplot` will be compiled with no line-editing capability. If you
want to use `gnuplot`'s line editing, set READLINE in the makefile and add
readline.obj to the link file. The following arrow keys may be used on the
IBM PC and Atari versions if readline is used:
@example
Left Arrow - same as ^B.
Right Arrow - same as ^F.
Ctrl Left Arrow - same as ^A.
Ctrl Right Arrow - same as ^E.
Up Arrow - same as ^P.
Down Arrow - same as ^N.
@end example
The Atari version of readline defines some additional key aliases:
@example
Undo - same as ^L.
Home - same as ^A.
Ctrl Home - same as ^E.
Esc - same as ^U.
Help - @ref{help} plus return.
Ctrl Help - `help `.
@end example
@node Comments, Coordinates, Command-line-editing, gnuplot
@section Comments
@cindex comments
Comments are supported as follows: a `#` may appear in most places in a line
and `gnuplot` will ignore the rest of the line. It will not have this effect
inside quotes, inside numbers (including complex numbers), inside command
substitutions, etc. In short, it works anywhere it makes sense to work.
@node Coordinates, Environment, Comments, gnuplot
@section Coordinates
@cindex coordinates
The commands @ref{arrow}, @ref{key}, and @ref{label} allow you to draw
something at an arbitrary position on the graph. This position is specified
by the syntax:
@example
@{@} , @{@} @{,@{@} @}
@end example
Each can either be `first`, `second`, `graph` or `screen`.
`first` places the x, y, or z coordinate in the system defined by the left
and bottom axes; `second` places it in the system defined by the second axes
(top and right); `graph` specifies the area within the axes---0,0 is bottom
left and 1,1 is top right (for splot, 0,0,0 is bottom left of plotting area;
use negative z to get to the base---see @ref{ticslevel}); and `screen`
specifies the screen area (the entire area---not just the portion selected by
@ref{size}), with 0,0 at bottom left and 1,1 at top right.
If the coordinate system for x is not specified, `first` is used. If the
system for y is not specified, the one used for x is adopted.
If one (or more) axis is timeseries, the appropriate coordinate should
be given as a quoted time string according to the @ref{timefmt} format string.
See @ref{xdata} and @ref{timefmt}. `gnuplot` will also accept an integer
expression, which will be interpreted as seconds from 1 January 2000.
@node Environment, Expressions, Coordinates, gnuplot
@section Environment
@cindex environment
A number of shell environment variables are understood by `gnuplot`. None of
these are required, but may be useful.
If GNUTERM is defined, it is used as the name of the terminal type to be
used. This overrides any terminal type sensed by `gnuplot` on start-up, but
is itself overridden by the .gnuplot (or equivalent) start-up file (see
`start-up`) and, of course, by later explicit changes.
On Unix, AmigaOS, AtariTOS, MS-DOS and OS/2, GNUHELP may be defined to be the
pathname of the HELP file (gnuplot.gih).
On VMS, the logical name GNUPLOT$HELP should be defined as the name of the
help library for `gnuplot`. The `gnuplot` help can be put inside any system
help library, allowing access to help from both within and outside `gnuplot`
if desired.
On Unix, HOME is used as the name of a directory to search for a .gnuplot
file if none is found in the current directory. On AmigaOS, AtariTOS,
MS-DOS and OS/2, gnuplot is used. On VMS, SYS$LOGIN: is used. See `help
start-up`.
On Unix, PAGER is used as an output filter for help messages.
On Unix, AtariTOS and AmigaOS, SHELL is used for the @ref{shell} command. On
MS-DOS and OS/2, COMSPEC is used for the @ref{shell} command.
On MS-DOS, if the BGI or Watcom interface is used, PCTRM is used to tell
the maximum resolution supported by your monitor by setting it to
S. E.g. if your monitor's maximum resolution is
800x600, then use:
@example
set PCTRM=S800
@end example
If PCTRM is not set, standard VGA is used.
FIT_SCRIPT may be used to specify a `gnuplot` command to be executed when a
fit is interrupted---see `fit`. FIT_LOG specifies the filename of the
logfile maintained by fit.
GNUPLOT_LIB may be used to define additional search directories for data
and command files. The variable may contain a single directory name, or
a list of directories separated by a platform-specific path separator,
eg. ':' on Unix, or ';' on DOS/Windows/OS/2/Amiga platforms. The contents
of GNUPLOT_LIB are appended to the @ref{loadpath} variable, but not saved
with the @ref{save} and `save set` commands.
@node Expressions, Glossary, Environment, gnuplot
@section Expressions
@cindex expressions
In general, any mathematical expression accepted by C, FORTRAN, Pascal, or
BASIC is valid. The precedence of these operators is determined by the
specifications of the C programming language. White space (spaces and tabs)
is ignored inside expressions.
Complex constants are expressed as @{,@}, where and
must be numerical constants. For example, @{3,2@} represents 3 + 2i; @{0,1@}
represents 'i' itself. The curly braces are explicitly required here.
Note that gnuplot uses both "real" and "integer" arithmetic, like FORTRAN and
C. Integers are entered as "1", "-10", etc; reals as "1.0", "-10.0", "1e1",
3.5e-1, etc. The most important difference between the two forms is in
division: division of integers truncates: 5/2 = 2; division of reals does
not: 5.0/2.0 = 2.5. In mixed expressions, integers are "promoted" to reals
before evaluation: 5/2e0 = 2.5. The result of division of a negative integer
by a positive one may vary among compilers. Try a test like "print -5/2" to
determine if your system chooses -2 or -3 as the answer.
The integer expression "1/0" may be used to generate an "undefined" flag,
which causes a point to ignored; the `ternary` operator gives an example.
The real and imaginary parts of complex expressions are always real, whatever
the form in which they are entered: in @{3,2@} the "3" and "2" are reals, not
integers.
@menu
* Functions::
* Operators::
* User-defined::
@end menu
@node Functions, Operators, Expressions, Expressions
@subsection Functions
@c ?expressions functions
@cindex functions
@opindex functions
The functions in `gnuplot` are the same as the corresponding functions in
the Unix math library, except that all functions accept integer, real, and
complex arguments, unless otherwise noted.
For those functions that accept or return angles that may be given in either
degrees or radians (sin(x), cos(x), tan(x), asin(x), acos(x), atan(x),
atan2(x) and arg(z)), the unit may be selected by @ref{angles}, which
defaults to radians.
@menu
* abs::
* acos::
* acosh::
* arg::
* asin::
* asinh::
* atan::
* atan2::
* atanh::
* besj0::
* besj1::
* besy0::
* besy1::
* ceil::
* cos::
* cosh::
* erf::
* erfc::
* exp::
* floor::
* gamma::
* ibeta::
* inverf::
* igamma::
* imag::
* invnorm::
* int::
* lgamma::
* log::
* log10::
* norm::
* rand::
* real::
* sgn::
* sin::
* sinh::
* sqrt::
* tan::
* tanh::
* column::
* tm_hour::
* tm_mday::
* tm_min::
* tm_mon::
* tm_sec::
* tm_wday::
* tm_yday::
* tm_year::
* valid::
@end menu
@node abs, acos, Functions, Functions
@subsubsection abs
@c ?expressions functions abs
@c ?functions abs
@cindex abs
@findex abs
The `abs(x)` function returns the absolute value of its argument. The
returned value is of the same type as the argument.
For complex arguments, abs(x) is defined as the length of x in the complex
plane [i.e., sqrt(real(x)**2 + imag(x)**2) ].
@node acos, acosh, abs, Functions
@subsubsection acos
@c ?expressions functions acos
@c ?functions acos
@cindex acos
@findex acos
The `acos(x)` function returns the arc cosine (inverse cosine) of its
argument. `acos` returns its argument in radians or degrees, as selected by
@ref{angles}.
@node acosh, arg, acos, Functions
@subsubsection acosh
@c ?expressions functions acosh
@c ?functions acosh
@cindex acosh
@findex acosh
The `acosh(x)` function returns the inverse hyperbolic cosine of its argument
in radians.
@node arg, asin, acosh, Functions
@subsubsection arg
@c ?expressions functions arg
@c ?functions arg
@cindex arg
@findex arg
The `arg(x)` function returns the phase of a complex number in radians or
degrees, as selected by @ref{angles}.
@node asin, asinh, arg, Functions
@subsubsection asin
@c ?expressions functions asin
@c ?functions asin
@cindex asin
@findex asin
The `asin(x)` function returns the arc sin (inverse sin) of its argument.
`asin` returns its argument in radians or degrees, as selected by @ref{angles}.
@node asinh, atan, asin, Functions
@subsubsection asinh
@c ?expressions functions asinh
@c ?functions asinh
@cindex asinh
@findex asinh
The `asinh(x)` function returns the inverse hyperbolic sin of its argument in
radians.
@node atan, atan2, asinh, Functions
@subsubsection atan
@c ?expressions functions atan
@c ?functions atan
@cindex atan
@findex atan
The `atan(x)` function returns the arc tangent (inverse tangent) of its
argument. `atan` returns its argument in radians or degrees, as selected by
@ref{angles}.
@node atan2, atanh, atan, Functions
@subsubsection atan2
@c ?expressions functions atan2
@c ?functions atan2
@cindex atan2
@findex atan2
The `atan2(y,x)` function returns the arc tangent (inverse tangent) of the
ratio of the real parts of its arguments. @ref{atan2} returns its argument in
radians or degrees, as selected by @ref{angles}, in the correct quadrant.
@node atanh, besj0, atan2, Functions
@subsubsection atanh
@c ?expressions functions atanh
@c ?functions atanh
@cindex atanh
@findex atanh
The `atanh(x)` function returns the inverse hyperbolic tangent of its
argument in radians.
@node besj0, besj1, atanh, Functions
@subsubsection besj0
@c ?expressions functions besj0
@c ?functions besj0
@cindex besj0
@findex besj0
The `besj0(x)` function returns the j0th Bessel function of its argument.
@ref{besj0} expects its argument to be in radians.
@node besj1, besy0, besj0, Functions
@subsubsection besj1
@c ?expressions functions besj1
@c ?functions besj1
@cindex besj1
@findex besj1
The `besj1(x)` function returns the j1st Bessel function of its argument.
@ref{besj1} expects its argument to be in radians.
@node besy0, besy1, besj1, Functions
@subsubsection besy0
@c ?expressions functions besy0
@c ?functions besy0
@cindex besy0
@findex besy0
The @ref{besy0} function returns the y0th Bessel function of its argument.
@ref{besy0} expects its argument to be in radians.
@node besy1, ceil, besy0, Functions
@subsubsection besy1
@c ?expressions functions besy1
@c ?functions besy1
@cindex besy1
@findex besy1
The `besy1(x)` function returns the y1st Bessel function of its argument.
@ref{besy1} expects its argument to be in radians.
@node ceil, cos, besy1, Functions
@subsubsection ceil
@c ?expressions functions ceil
@c ?functions ceil
@cindex ceil
@findex ceil
The `ceil(x)` function returns the smallest integer that is not less than its
argument. For complex numbers, @ref{ceil} returns the smallest integer not less
than the real part of its argument.
@node cos, cosh, ceil, Functions
@subsubsection cos
@c ?expressions functions cos
@c ?functions cos
@cindex cos
@findex cos
The `cos(x)` function returns the cosine of its argument. `cos` accepts its
argument in radians or degrees, as selected by @ref{angles}.
@node cosh, erf, cos, Functions
@subsubsection cosh
@c ?expressions functions cosh
@c ?functions cosh
@cindex cosh
@findex cosh
The `cosh(x)` function returns the hyperbolic cosine of its argument. @ref{cosh}
expects its argument to be in radians.
@node erf, erfc, cosh, Functions
@subsubsection erf
@c ?expressions functions erf
@c ?functions erf
@cindex erf
@findex erf
The `erf(x)` function returns the error function of the real part of its
argument. If the argument is a complex value, the imaginary component is
ignored.
@node erfc, exp, erf, Functions
@subsubsection erfc
@c ?expressions functions erfc
@c ?functions erfc
@cindex erfc
@findex erfc
The `erfc(x)` function returns 1.0 - the error function of the real part of
its argument. If the argument is a complex value, the imaginary component is
ignored.
@node exp, floor, erfc, Functions
@subsubsection exp
@c ?expressions functions exp
@c ?functions exp
@cindex exp
@findex exp
The `exp(x)` function returns the exponential function of its argument (`e`
raised to the power of its argument). On some implementations (notably
suns), exp(-x) returns undefined for very large x. A user-defined function
like safe(x) = x 0 and x in [0:1]. If the arguments are
complex, the imaginary components are ignored.
@node inverf, igamma, ibeta, Functions
@subsubsection inverf
@c ?expressions functions inverf
@c ?functions inverf
@cindex inverf
@findex inverf
The `inverf(x)` function returns the inverse error function of the real part
of its argument.
@node igamma, imag, inverf, Functions
@subsubsection igamma
@c ?expressions functions igamma
@c ?functions igamma
@cindex igamma
@findex igamma
The `igamma(a,x)` function returns the incomplete gamma function of the real
parts of its arguments. a > 0 and x >= 0. If the arguments are complex,
the imaginary components are ignored.
@node imag, invnorm, igamma, Functions
@subsubsection imag
@c ?expressions functions imag
@c ?functions imag
@cindex imag
@findex imag
The `imag(x)` function returns the imaginary part of its argument as a real
number.
@node invnorm, int, imag, Functions
@subsubsection invnorm
@c ?expressions functions invnorm
@c ?functions invnorm
@cindex invnorm
@findex invnorm
The `invnorm(x)` function returns the inverse normal distribution function of
the real part of its argument.
@node int, lgamma, invnorm, Functions
@subsubsection int
@c ?expressions functions int
@c ?functions int
@cindex int
@findex int
The `int(x)` function returns the integer part of its argument, truncated
toward zero.
@node lgamma, log, int, Functions
@subsubsection lgamma
@c ?expressions functions lgamma
@c ?functions lgamma
@cindex lgamma
@findex lgamma
The `lgamma(x)` function returns the natural logarithm of the gamma function
of the real part of its argument. If the argument is a complex value, the
imaginary component is ignored.
@node log, log10, lgamma, Functions
@subsubsection log
@c ?expressions functions log
@c ?functions log
@cindex log
@findex log
The `log(x)` function returns the natural logarithm (base `e`) of its
argument.
@node log10, norm, log, Functions
@subsubsection log10
@c ?expressions functions log10
@c ?functions log10
@cindex log10
@findex log10
The `log10(x)` function returns the logarithm (base 10) of its argument.
@node norm, rand, log10, Functions
@subsubsection norm
@c ?expressions functions norm
@c ?functions norm
@cindex norm
@findex norm
The `norm(x)` function returns the normal distribution function (or Gaussian)
of the real part of its argument.
@node rand, real, norm, Functions
@subsubsection rand
@c ?expressions functions rand
@c ?functions rand
@cindex rand
@findex rand
The `rand(x)` function returns a pseudo random number in the interval [0:1]
using the real part of its argument as a seed. If seed < 0, the sequence
is (re)initialized. If the argument is a complex value, the imaginary
component is ignored.
@node real, sgn, rand, Functions
@subsubsection real
@c ?expressions functions real
@c ?functions real
@cindex real
@findex real
The `real(x)` function returns the real part of its argument.
@node sgn, sin, real, Functions
@subsubsection sgn
@c ?expressions functions sgn
@c ?functions sgn
@cindex sgn
@findex sgn
The `sgn(x)` function returns 1 if its argument is positive, -1 if its
argument is negative, and 0 if its argument is 0. If the argument is a
complex value, the imaginary component is ignored.
@node sin, sinh, sgn, Functions
@subsubsection sin
@c ?expressions functions sin
@c ?functions sin
@cindex sin
@findex sin
The `sin(x)` function returns the sine of its argument. `sin` expects its
argument to be in radians or degrees, as selected by @ref{angles}.
@node sinh, sqrt, sin, Functions
@subsubsection sinh
@c ?expressions functions sinh
@c ?functions sinh
@cindex sinh
@findex sinh
The `sinh(x)` function returns the hyperbolic sine of its argument. @ref{sinh}
expects its argument to be in radians.
@node sqrt, tan, sinh, Functions
@subsubsection sqrt
@c ?expressions functions sqrt
@c ?functions sqrt
@cindex sqrt
@findex sqrt
The `sqrt(x)` function returns the square root of its argument.
@node tan, tanh, sqrt, Functions
@subsubsection tan
@c ?expressions functions tan
@c ?functions tan
@cindex tan
@findex tan
The `tan(x)` function returns the tangent of its argument. `tan` expects
its argument to be in radians or degrees, as selected by @ref{angles}.
@node tanh, column, tan, Functions
@subsubsection tanh
@c ?expressions functions tanh
@c ?functions tanh
@cindex tanh
@findex tanh
The `tanh(x)` function returns the hyperbolic tangent of its argument. @ref{tanh}
expects its argument to be in radians.
A few additional functions are also available.
@node column, tm_hour, tanh, Functions
@subsubsection column
@c ?expressions functions column
@c ?functions column
@cindex column
@findex column
`column(x)` may be used only in expressions as part of @ref{using} manipulations
to fits or datafile plots. See @ref{using}.
@node tm_hour, tm_mday, column, Functions
@subsubsection tm_hour
@c ?expressions tm_hour
@findex tm_hour
@c ?functions tm_hour
The @ref{tm_hour} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the hour (an integer in the range 0--23) as a real.
@node tm_mday, tm_min, tm_hour, Functions
@subsubsection tm_mday
@c ?expressions tm_mday
@findex tm_mday
@c ?functions tm_mday
The @ref{tm_mday} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the day of the month (an integer in the range 1--31)
as a real.
@node tm_min, tm_mon, tm_mday, Functions
@subsubsection tm_min
@c ?expressions tm_min
@findex tm_min
@c ?functions tm_min
The @ref{tm_min} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the minute (an integer in the range 0--59) as a real.
@node tm_mon, tm_sec, tm_min, Functions
@subsubsection tm_mon
@c ?expressions tm_mon
@findex tm_mon
@c ?functions tm_mon
The @ref{tm_mon} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the month (an integer in the range 0--11) as a real.
@node tm_sec, tm_wday, tm_mon, Functions
@subsubsection tm_sec
@c ?expressions tm_sec
@findex tm_sec
@c ?functions tm_sec
The @ref{tm_sec} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the second (an integer in the range 0--59) as a real.
@node tm_wday, tm_yday, tm_sec, Functions
@subsubsection tm_wday
@c ?expressions tm_wday
@findex tm_wday
@c ?functions tm_wday
The @ref{tm_wday} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the day of the week (an integer in the range 0--6) as
a real.
@node tm_yday, tm_year, tm_wday, Functions
@subsubsection tm_yday
@c ?expressions tm_yday
@findex tm_yday
@c ?functions tm_yday
The @ref{tm_yday} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the day of the year (an integer in the range 1--366)
as a real.
@node tm_year, valid, tm_yday, Functions
@subsubsection tm_year
@c ?expressions tm_year
@findex tm_year
@c ?functions tm_year
The @ref{tm_year} function interprets its argument as a time, in seconds from
1 Jan 2000. It returns the year (an integer) as a real.
@node valid, , tm_year, Functions
@subsubsection valid
@c ?expressions functions valid
@c ?functions valid
@cindex valid
@findex valid
`valid(x)` may be used only in expressions as part of @ref{using} manipulations
to fits or datafile plots. See @ref{using}.
@uref{http://www.nas.nasa.gov/~woo/gnuplot/airfoil/airfoil.html,Use of functions and complex variables for airfoils }
@node Operators, User-defined, Functions, Expressions
@subsection Operators
@c ?expressions operators
@cindex operators
The operators in `gnuplot` are the same as the corresponding operators in the
C programming language, except that all operators accept integer, real, and
complex arguments, unless otherwise noted. The ** operator (exponentiation)
is supported, as in FORTRAN.
Parentheses may be used to change order of evaluation.
@menu
* Unary::
* Binary::
* Ternary::
@end menu
@node Unary, Binary, Operators, Operators
@subsubsection Unary
@c ?expressions operators unary
@c ?operators unary
@cindex unary
The following is a list of all the unary operators and their usages:
@example
Symbol Example Explanation
- -a unary minus
+ +a unary plus (no-operation)
~ ~a * one's complement
! !a * logical negation
! a! * factorial
$ $3 * call arg/column during @ref{using} manipulation
@end example
(*) Starred explanations indicate that the operator requires an integer
argument.
Operator precedence is the same as in Fortran and C. As in those languages,
parentheses may be used to change the order of operation. Thus -2**2 = -4,
but (-2)**2 = 4.
The factorial operator returns a real number to allow a greater range.
@node Binary, Ternary, Unary, Operators
@subsubsection Binary
@c ?expressions operators binary
@c ?operators binary
@cindex binary
The following is a list of all the binary operators and their usages:
@example
Symbol Example Explanation
** a**b exponentiation
* a*b multiplication
/ a/b division
% a%b * modulo
+ a+b addition
- a-b subtraction
== a==b equality
!= a!=b inequality
< a
= a>=b greater than or equal to
& a&b * bitwise AND
^ a^b * bitwise exclusive OR
| a|b * bitwise inclusive OR
&& a&&b * logical AND
|| a||b * logical OR
@end example
(*) Starred explanations indicate that the operator requires integer
arguments.
Logical AND (&&) and OR (||) short-circuit the way they do in C. That is,
the second `&&` operand is not evaluated if the first is false; the second
`||` operand is not evaluated if the first is true.
@node Ternary, , Binary, Operators
@subsubsection Ternary
@c ?expressions operators ternary
@c ?operators ternary
@cindex ternary
There is a single ternary operator:
@example
Symbol Example Explanation
?: a?b:c ternary operation
@end example
The ternary operator behaves as it does in C. The first argument (a), which
must be an integer, is evaluated. If it is true (non-zero), the second
argument (b) is evaluated and returned; otherwise the third argument (c) is
evaluated and returned.
The ternary operator is very useful both in constructing piecewise functions
and in plotting points only when certain conditions are met.
Examples:
Plot a function that is to equal sin(x) for 0 0, the terminal number will be
appended to the window title and the icon will be labeled `gplt `.
The active window may distinguished by a change in cursor (from default
to crosshair.)
Plot windows remain open even when the `gnuplot` driver is changed to a
different device. A plot window can be closed by pressing the letter q
while that window has input focus, or by choosing `close` from a window
manager menu. All plot windows can be closed by specifying @ref{reset}, which
actually terminates the subprocess which maintains the windows (unless
`-persist` was specified).
The option `driver` can be used to specify a driver different from the
default driver `gnuplot_x11`. This options is thought mainly for developers
who are working on new driver features. Note that changing the driver will
shut down the connection to the previous driver. Example:
@example
gnuplot> set term x11 driver "gnuplot_x11_38a"
@end example
Plot windows will automatically be closed at the end of the session
unless the `-persist` option was given.
The options `persist` and `raise` are unset by default, which means that
the defaults (persist == no and raise == yes) or the command line options
-persist / -raise or the Xresources are taken. If [no]persist or
[no]raise are specified, they will override command line options and
Xresources. Setting one of these options takes place immediately, so
the behaviour of an already running driver can be modified.
The size or aspect ratio of a plot may be changed by resizing the `gnuplot`
window.
Linewidths and pointsizes may be changed from within `gnuplot` with
@ref{linestyle}.
For terminal type `x11`, `gnuplot` accepts (when initialized) the standard
X Toolkit options and resources such as geometry, font, and name from the
command line arguments or a configuration file. See the X(1) man page
(or its equivalent) for a description of such options.
A number of other `gnuplot` options are available for the `x11` terminal.
These may be specified either as command-line options when `gnuplot` is
invoked or as resources in the configuration file "/.Xdefaults". They are
set upon initialization and cannot be altered during a `gnuplot` session.
(except `persist` and `raise`)
@noindent --- COMMAND-LINE_OPTIONS ---
@c ?commands set terminal x11 command-line-options
@c ?set terminal x11 command-line-options
@c ?set term x11 command-line-options
@c ?x11 command-line-options
@cindex command-line-options
In addition to the X Toolkit options, the following options may be specified
on the command line when starting `gnuplot` or as resources in your
".Xdefaults" file (note that `raise` and `persist` can be overridden
later by `set term x11 [no]raise [no]persist)`:
@example
`-clear` requests that the window be cleared momentarily before a
new plot is displayed.
`-gray` requests grayscale rendering on grayscale or color displays.
(Grayscale displays receive monochrome rendering by default.)
`-mono` forces monochrome rendering on color displays.
`-persist` plot windows survive after main gnuplot program exits
`-raise` raise plot window after each plot
`-noraise` do not raise plot window after each plot
`-tvtwm` requests that geometry specifications for position of the
window be made relative to the currently displayed portion
of the virtual root.
@end example
The options are shown above in their command-line syntax. When entered as
resources in ".Xdefaults", they require a different syntax.
Example:
@example
gnuplot*gray: on
@end example
`gnuplot` also provides a command line option (`-pointsize `) and a
resource, `gnuplot*pointsize: `, to control the size of points plotted
with the `points` plotting style. The value `v` is a real number (greater
than 0 and less than or equal to ten) used as a scaling factor for point
sizes. For example, `-pointsize 2` uses points twice the default size, and
`-pointsize 0.5` uses points half the normal size.
@noindent --- MONOCHOME_OPTIONS ---
@c ?commands set terminal x11 monochrome_options
@c ?set terminal x11 monochrome_options
@c ?set term x11 monochrome_options
@c ?x11 monochrome_options
@cindex monochrome_options
For monochrome displays, `gnuplot` does not honor foreground or background
colors. The default is black-on-white. `-rv` or `gnuplot*reverseVideo: on`
requests white-on-black.
@noindent --- COLOR_RESOURCES ---
@c ?commands set terminal x11 color_resources
@c ?set terminal x11 color_resources
@c ?set term x11 color_resources
@c ?x11 color_resources
@cindex color_resources
For color displays, `gnuplot` honors the following resources (shown here
with their default values) or the greyscale resources. The values may be
color names as listed in the X11 rgb.txt file on your system, hexadecimal
RGB color specifications (see X11 documentation), or a color name followed
by a comma and an `intensity` value from 0 to 1. For example, `blue, 0.5`
means a half intensity blue.
@example
gnuplot*background: white
gnuplot*textColor: black
gnuplot*borderColor: black
gnuplot*axisColor: black
gnuplot*line1Color: red
gnuplot*line2Color: green
gnuplot*line3Color: blue
gnuplot*line4Color: magenta
gnuplot*line5Color: cyan
gnuplot*line6Color: sienna
gnuplot*line7Color: orange
gnuplot*line8Color: coral
@end example
The command-line syntax for these is, for example,
Example:
@example
gnuplot -background coral
@end example
@noindent --- GRAYSCALE_RESOURCES ---
@c ?commands set terminal x11 grayscale_resources
@c ?set terminal x11 grayscale_resources
@c ?set term x11 grayscale_resources
@c ?x11 grayscale_resources
@cindex grayscale_resources
When `-gray` is selected, `gnuplot` honors the following resources for
grayscale or color displays (shown here with their default values). Note
that the default background is black.
@example
gnuplot*background: black
gnuplot*textGray: white
gnuplot*borderGray: gray50
gnuplot*axisGray: gray50
gnuplot*line1Gray: gray100
gnuplot*line2Gray: gray60
gnuplot*line3Gray: gray80
gnuplot*line4Gray: gray40
gnuplot*line5Gray: gray90
gnuplot*line6Gray: gray50
gnuplot*line7Gray: gray70
gnuplot*line8Gray: gray30
@end example
@noindent --- LINE_RESOURCES ---
@c ?commands set terminal x11 line_resources
@c ?set terminal x11 line_resources
@c ?set term x11 line_resources
@c ?x11 line_resources
@cindex line_resources
`gnuplot` honors the following resources for setting the width (in pixels) of
plot lines (shown here with their default values.) 0 or 1 means a minimal
width line of 1 pixel width. A value of 2 or 3 may improve the appearance of
some plots.
@example
gnuplot*borderWidth: 2
gnuplot*axisWidth: 0
gnuplot*line1Width: 0
gnuplot*line2Width: 0
gnuplot*line3Width: 0
gnuplot*line4Width: 0
gnuplot*line5Width: 0
gnuplot*line6Width: 0
gnuplot*line7Width: 0
gnuplot*line8Width: 0
@end example
`gnuplot` honors the following resources for setting the dash style used for
plotting lines. 0 means a solid line. A two-digit number `jk` (`j` and `k`
are >= 1 and