1@c Copyright (C) 1996-2019 John W. Eaton
2@c
3@c This file is part of Octave.
4@c
5@c Octave is free software: you can redistribute it and/or modify it
6@c under the terms of the GNU General Public License as published by
7@c the Free Software Foundation, either version 3 of the License, or
8@c (at your option) any later version.
9@c
10@c Octave is distributed in the hope that it will be useful, but
11@c WITHOUT ANY WARRANTY; without even the implied warranty of
12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13@c GNU General Public License for more details.
14@c
15@c You should have received a copy of the GNU General Public License
16@c along with Octave; see the file COPYING.  If not, see
17@c <https://www.gnu.org/licenses/>.
18
19@node Arithmetic
20@chapter Arithmetic
21
22Unless otherwise noted, all of the functions described in this chapter
23will work for real and complex scalar, vector, or matrix arguments.  Functions
24described as @dfn{mapping functions} apply the given operation individually to
25each element when given a matrix argument.  For example:
26
27@example
28@group
29sin ([1, 2; 3, 4])
30     @result{}  0.84147   0.90930
31         0.14112  -0.75680
32@end group
33@end example
34
35@menu
36* Exponents and Logarithms::
37* Complex Arithmetic::
38* Trigonometry::
39* Sums and Products::
40* Utility Functions::
41* Special Functions::
42* Rational Approximations::
43* Coordinate Transformations::
44* Mathematical Constants::
45@end menu
46
47@node Exponents and Logarithms
48@section Exponents and Logarithms
49
50@DOCSTRING(exp)
51
52@DOCSTRING(expm1)
53
54@DOCSTRING(log)
55
56@DOCSTRING(reallog)
57
58@DOCSTRING(log1p)
59
60@DOCSTRING(log10)
61
62@DOCSTRING(log2)
63
64@DOCSTRING(pow2)
65
66@DOCSTRING(nextpow2)
67
68@DOCSTRING(realpow)
69
70@DOCSTRING(sqrt)
71
72@DOCSTRING(realsqrt)
73
74@DOCSTRING(cbrt)
75
76@DOCSTRING(nthroot)
77
78@node Complex Arithmetic
79@section Complex Arithmetic
80
81In the descriptions of the following functions,
82@tex
83$z$ is the complex number $x + iy$, where $i$ is defined as
84$\sqrt{-1}$.
85@end tex
86@ifnottex
87@var{z} is the complex number @var{x} + @var{i}@var{y}, where @var{i} is
88defined as @code{sqrt (-1)}.
89@end ifnottex
90
91@DOCSTRING(abs)
92
93@DOCSTRING(arg)
94
95@DOCSTRING(conj)
96
97@DOCSTRING(cplxpair)
98
99@DOCSTRING(imag)
100
101@DOCSTRING(real)
102
103@node Trigonometry
104@section Trigonometry
105
106Octave provides the following trigonometric functions where angles are
107specified in radians.  To convert from degrees to radians multiply by
108@tex
109$\pi/180$
110@end tex
111@ifnottex
112@code{pi/180}
113@end ifnottex
114or use the @code{deg2rad} function.  For example, @code{sin (30 * pi/180)}
115returns the sine of 30 degrees.  As an alternative, Octave provides a number of
116trigonometric functions which work directly on an argument specified in
117degrees.  These functions are named after the base trigonometric function with
118a @samp{d} suffix.  As an example, @code{sin} expects an angle in radians while
119@code{sind} expects an angle in degrees.
120
121Octave uses the C library trigonometric functions.  It is expected that these
122functions are defined by the ISO/IEC 9899 Standard.  This Standard is available
123at: @url{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf}.
124Section F.9.1 deals with the trigonometric functions.  The behavior of most of
125the functions is relatively straightforward.  However, there are some
126exceptions to the standard behavior.  Many of the exceptions involve the
127behavior for -0.  The most complex case is atan2.  Octave exactly implements
128the behavior given in the Standard.  Including
129@tex
130$atan2(\pm0, -0)$ returns $\pm \pi$.
131@end tex
132@ifnottex
133@code{atan2(+- 0, 0)} returns @code{+- pi}.
134@end ifnottex
135
136It should be noted that @sc{matlab} uses different definitions which apparently
137do not distinguish -0.
138
139@DOCSTRING(deg2rad)
140@DOCSTRING(rad2deg)
141
142@DOCSTRING(sin)
143@DOCSTRING(cos)
144@DOCSTRING(tan)
145@DOCSTRING(sec)
146@DOCSTRING(csc)
147@DOCSTRING(cot)
148
149@DOCSTRING(asin)
150@DOCSTRING(acos)
151@DOCSTRING(atan)
152@DOCSTRING(asec)
153@DOCSTRING(acsc)
154@DOCSTRING(acot)
155
156@DOCSTRING(sinh)
157@DOCSTRING(cosh)
158@DOCSTRING(tanh)
159@DOCSTRING(sech)
160@DOCSTRING(csch)
161@DOCSTRING(coth)
162
163@DOCSTRING(asinh)
164@DOCSTRING(acosh)
165@DOCSTRING(atanh)
166@DOCSTRING(asech)
167@DOCSTRING(acsch)
168@DOCSTRING(acoth)
169
170@DOCSTRING(atan2)
171
172Octave provides the following trigonometric functions where angles are
173specified in degrees.  These functions produce true zeros at the appropriate
174intervals rather than the small round-off error that occurs when using
175radians.  For example:
176
177@example
178@group
179cosd (90)
180     @result{} 0
181cos (pi/2)
182     @result{} 6.1230e-17
183@end group
184@end example
185
186@DOCSTRING(sind)
187@DOCSTRING(cosd)
188@DOCSTRING(tand)
189@DOCSTRING(secd)
190@DOCSTRING(cscd)
191@DOCSTRING(cotd)
192
193@DOCSTRING(asind)
194@DOCSTRING(acosd)
195@DOCSTRING(atand)
196@DOCSTRING(atan2d)
197@DOCSTRING(asecd)
198@DOCSTRING(acscd)
199@DOCSTRING(acotd)
200
201@node Sums and Products
202@section Sums and Products
203
204@DOCSTRING(sum)
205
206@DOCSTRING(prod)
207
208@DOCSTRING(cumsum)
209
210@DOCSTRING(cumprod)
211
212@DOCSTRING(sumsq)
213
214@node Utility Functions
215@section Utility Functions
216
217@DOCSTRING(ceil)
218
219@DOCSTRING(fix)
220
221@DOCSTRING(floor)
222
223@DOCSTRING(round)
224
225@DOCSTRING(roundb)
226
227@DOCSTRING(max)
228
229@DOCSTRING(min)
230
231@DOCSTRING(cummax)
232
233@DOCSTRING(cummin)
234
235@DOCSTRING(hypot)
236
237@DOCSTRING(gradient)
238
239@DOCSTRING(dot)
240
241@DOCSTRING(cross)
242
243@DOCSTRING(divergence)
244
245@DOCSTRING(curl)
246
247@DOCSTRING(del2)
248
249@DOCSTRING(factorial)
250
251@DOCSTRING(factor)
252
253@DOCSTRING(gcd)
254
255@DOCSTRING(lcm)
256
257@DOCSTRING(rem)
258
259@DOCSTRING(mod)
260
261@DOCSTRING(primes)
262
263@DOCSTRING(list_primes)
264
265@DOCSTRING(sign)
266
267@DOCSTRING(signbit)
268
269@node Special Functions
270@section Special Functions
271
272@DOCSTRING(airy)
273
274@DOCSTRING(besselj)
275
276@DOCSTRING(bessely)
277
278@DOCSTRING(besseli)
279
280@DOCSTRING(besselk)
281
282@DOCSTRING(besselh)
283
284@DOCSTRING(beta)
285
286@DOCSTRING(betainc)
287
288@DOCSTRING(betaincinv)
289
290@DOCSTRING(betaln)
291
292@DOCSTRING(bincoeff)
293
294@DOCSTRING(commutation_matrix)
295
296@DOCSTRING(cosint)
297
298@DOCSTRING(duplication_matrix)
299
300@DOCSTRING(dawson)
301
302@DOCSTRING(ellipj)
303
304@DOCSTRING(ellipke)
305
306@DOCSTRING(erf)
307
308@DOCSTRING(erfc)
309
310@DOCSTRING(erfcx)
311
312@DOCSTRING(erfi)
313
314@DOCSTRING(erfinv)
315
316@DOCSTRING(erfcinv)
317
318@DOCSTRING(expint)
319
320@DOCSTRING(gamma)
321
322@DOCSTRING(gammainc)
323
324@DOCSTRING(gammaincinv)
325
326@DOCSTRING(legendre)
327
328@anchor{XREFgammaln}
329@DOCSTRING(lgamma)
330
331@DOCSTRING(psi)
332
333@DOCSTRING(sinint)
334
335@node Rational Approximations
336@section Rational Approximations
337
338@DOCSTRING(rat)
339
340@DOCSTRING(rats)
341
342@node Coordinate Transformations
343@section Coordinate Transformations
344
345@DOCSTRING(cart2pol)
346
347@DOCSTRING(pol2cart)
348
349@DOCSTRING(cart2sph)
350
351@DOCSTRING(sph2cart)
352
353@node Mathematical Constants
354@section Mathematical Constants
355
356@DOCSTRING(e)
357
358@DOCSTRING(pi)
359
360@DOCSTRING(I)
361
362@DOCSTRING(Inf)
363
364@DOCSTRING(NaN)
365
366@DOCSTRING(eps)
367
368@DOCSTRING(realmax)
369
370@DOCSTRING(realmin)
371