++ed by:
20 non-PAUSE users
Ed J
and 1 contributors

# NAME

PDL::Ops - Fundamental mathematical operators

# DESCRIPTION

This module provides the functions used by PDL to overload the basic mathematical operators (`+ - / *` etc.) and functions (`sin sqrt` etc.)

It also includes the function `log10`, which should be a perl function so that we can overload it!

Matrix multiplication (the operator `x`) is handled by the module PDL::Primitive.

none

# FUNCTIONS

## plus

``  Signature: (a(); b(); [o]c(); int swap)``

``````   \$c = plus \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x + \$y;           # overloaded call
\$x->inplace->plus(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `+` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

plus processes bad values. The state of the bad-value flag of the output piddles is unknown.

## mult

``  Signature: (a(); b(); [o]c(); int swap)``

multiply two piddles

``````   \$c = mult \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x * \$y;           # overloaded call
\$x->inplace->mult(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `*` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

mult processes bad values. The state of the bad-value flag of the output piddles is unknown.

## minus

``  Signature: (a(); b(); [o]c(); int swap)``

subtract two piddles

``````   \$c = minus \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x - \$y;           # overloaded call
\$x->inplace->minus(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `-` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

minus processes bad values. The state of the bad-value flag of the output piddles is unknown.

## divide

``  Signature: (a(); b(); [o]c(); int swap)``

divide two piddles

``````   \$c = divide \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x / \$y;           # overloaded call
\$x->inplace->divide(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `/` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

divide processes bad values. The state of the bad-value flag of the output piddles is unknown.

## gt

``  Signature: (a(); b(); [o]c(); int swap)``

the binary > (greater than) operation

``````   \$c = gt \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x > \$y;           # overloaded call
\$x->inplace->gt(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `>` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

gt processes bad values. The state of the bad-value flag of the output piddles is unknown.

## lt

``  Signature: (a(); b(); [o]c(); int swap)``

the binary < (less than) operation

``````   \$c = lt \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x < \$y;           # overloaded call
\$x->inplace->lt(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `<` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

lt processes bad values. The state of the bad-value flag of the output piddles is unknown.

## le

``  Signature: (a(); b(); [o]c(); int swap)``

the binary <= (less equal) operation

``````   \$c = le \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x <= \$y;           # overloaded call
\$x->inplace->le(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `<=` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

le processes bad values. The state of the bad-value flag of the output piddles is unknown.

## ge

``  Signature: (a(); b(); [o]c(); int swap)``

the binary >= (greater equal) operation

``````   \$c = ge \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x >= \$y;           # overloaded call
\$x->inplace->ge(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `>=` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

ge processes bad values. The state of the bad-value flag of the output piddles is unknown.

## eq

``  Signature: (a(); b(); [o]c(); int swap)``

binary equal to operation (`==`)

``````   \$c = eq \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x == \$y;           # overloaded call
\$x->inplace->eq(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `==` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

eq processes bad values. The state of the bad-value flag of the output piddles is unknown.

## ne

``  Signature: (a(); b(); [o]c(); int swap)``

binary not equal to operation (`!=`)

``````   \$c = ne \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x != \$y;           # overloaded call
\$x->inplace->ne(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `!=` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

ne processes bad values. The state of the bad-value flag of the output piddles is unknown.

## shiftleft

``  Signature: (a(); b(); [o]c(); int swap)``

leftshift `\$a` by `\$b`

``````   \$c = shiftleft \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x << \$y;           # overloaded call
\$x->inplace->shiftleft(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `<<` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

shiftleft processes bad values. The state of the bad-value flag of the output piddles is unknown.

## shiftright

``  Signature: (a(); b(); [o]c(); int swap)``

rightshift `\$a` by `\$b`

``````   \$c = shiftright \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x >> \$y;           # overloaded call
\$x->inplace->shiftright(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `>>` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

shiftright processes bad values. The state of the bad-value flag of the output piddles is unknown.

## or2

``  Signature: (a(); b(); [o]c(); int swap)``

binary or of two piddles

``````   \$c = or2 \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x | \$y;           # overloaded call
\$x->inplace->or2(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `|` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

or2 processes bad values. The state of the bad-value flag of the output piddles is unknown.

## and2

``  Signature: (a(); b(); [o]c(); int swap)``

binary and of two piddles

``````   \$c = and2 \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x & \$y;           # overloaded call
\$x->inplace->and2(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `&` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

and2 processes bad values. The state of the bad-value flag of the output piddles is unknown.

## xor

``  Signature: (a(); b(); [o]c(); int swap)``

binary exclusive or of two piddles

``````   \$c = xor \$x, \$y, 0;     # explicit call with trailing 0
\$c = \$x ^ \$y;           # overloaded call
\$x->inplace->xor(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `^` operator. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

xor processes bad values. The state of the bad-value flag of the output piddles is unknown.

## bitnot

``  Signature: (a(); [o]b())``

unary bit negation

``````   \$y = ~ \$x;
\$x->inplace->bitnot;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `~` operator/function.

bitnot processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## power

``  Signature: (a(); b(); [o]c(); int swap)``

raise piddle `\$a` to the power `\$b`

``````   \$c = \$x->power(\$y,0); # explicit function call
\$c = \$a ** \$b;    # overloaded use
\$x->inplace->power(\$y,0);     # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `**` function. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

power processes bad values. The state of the bad-value flag of the output piddles is unknown.

## atan2

``  Signature: (a(); b(); [o]c(); int swap)``

elementwise `atan2` of two piddles

``````   \$c = \$x->atan2(\$y,0); # explicit function call
\$c = atan2 \$a, \$b;    # overloaded use
\$x->inplace->atan2(\$y,0);     # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `atan2` function. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

atan2 processes bad values. The state of the bad-value flag of the output piddles is unknown.

## modulo

``  Signature: (a(); b(); [o]c(); int swap)``

elementwise `modulo` operation

``````   \$c = \$x->modulo(\$y,0); # explicit function call
\$c = \$a % \$b;    # overloaded use
\$x->inplace->modulo(\$y,0);     # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `%` function. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

modulo processes bad values. The state of the bad-value flag of the output piddles is unknown.

## spaceship

``  Signature: (a(); b(); [o]c(); int swap)``

elementwise "<=>" operation

``````   \$c = \$x->spaceship(\$y,0); # explicit function call
\$c = \$a <=> \$b;    # overloaded use
\$x->inplace->spaceship(\$y,0);     # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the binary `<=>` function. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

spaceship processes bad values. The state of the bad-value flag of the output piddles is unknown.

## sqrt

``  Signature: (a(); [o]b())``

elementwise square root

``````   \$y = sqrt \$x;
\$x->inplace->sqrt;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `sqrt` operator/function.

sqrt processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## sin

``  Signature: (a(); [o]b())``

the sin function

``````   \$y = sin \$x;
\$x->inplace->sin;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `sin` operator/function.

sin processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## cos

``  Signature: (a(); [o]b())``

the cos function

``````   \$y = cos \$x;
\$x->inplace->cos;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `cos` operator/function.

cos processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## not

``  Signature: (a(); [o]b())``

the elementwise not operation

``````   \$y = ! \$x;
\$x->inplace->not;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `!` operator/function.

not processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## exp

``  Signature: (a(); [o]b())``

the exponential function

``````   \$y = exp \$x;
\$x->inplace->exp;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `exp` operator/function.

exp processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## log

``  Signature: (a(); [o]b())``

the natural logarithm

``````   \$y = log \$x;
\$x->inplace->log;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `log` operator/function.

log processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## log10

``  Signature: (a(); [o]b())``

the base 10 logarithm

``````   \$y = log10 \$x;
\$x->inplace->log10;  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. This function is used to overload the unary `log10` operator/function.

log10 processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## assgn

``  Signature: (a(); [o]b())``

Plain numerical assignment. This is used to implement the ".=" operator

If `a` is a child piddle (e.g., the result of a slice) and bad values are generated in `b`, the bad value flag is set in `b`, but it is NOT automatically propagated back to the parent of `a`. The following idiom ensures that the badflag is propagated back to the parent of `a`:

`````` \$pdl->slice(":,(1)") .= PDL::Bad_aware_func();

This is unnecessary if \$pdl->badflag is known to be 1 before the slice is performed.

## carg

``  Signature: (complexv(); real [o]b())``

Returns the polar angle of a complex number.

carg processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## conj

``  Signature: (complexv();  [o]b())``

complex conjugate.

conj processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## creal

``  Signature: (complexv(); real [o]b())``

Returns the real part of a complex number.

creal processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## cimag

``  Signature: (complexv(); real [o]b())``

Returns the imaginary part of a complex number.

cimag processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## _cabs

``  Signature: (complexv(); real [o]b())``

Returns the absolute (length) of a complex number.

_cabs processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## ci

``  Signature: (cdouble [o]b())``

Returns the complex number 0 + 1i.

WARNING because this is not defined as a constant (with empty prototype), you must use it either as `10*ci` or `ci()*10`. If you use it as `ci*10` this will actually try to use 10 as a glob and pass that to `ci`, which will not do what you want.

ci processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## ipow

``  Signature: (a(); b(); [o] ans())``

raise piddle `\$a` to integer power `\$b`

``````   \$c = \$x->ipow(\$y,0);     # explicit function call
\$c = ipow \$x, \$y;
\$x->inplace->ipow(\$y,0);  # modify \$x inplace``````

It can be made to work inplace with the `\$x->inplace` syntax. Note that when calling this function explicitly you need to supply a third argument that should generally be zero (see first example). This restriction is expected to go away in future releases.

Algorithm from Wikipedia

ipow does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## _rabs

``  Signature: (a(); [o]b())``

Returns the absolute value of a number.

_rabs processes bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

## r2C

``  Signature: (r(); complex [o]c())``

convert real to native complex, with an imaginary part of zero

r2C does not process bad values. It will set the bad-value flag of all output piddles if the flag is set for any of the input piddles.

# AUTHOR

Tuomas J. Lukka (lukka@fas.harvard.edu), Karl Glazebrook (kgb@aaoepp.aao.gov.au), Doug Hunt (dhunt@ucar.edu), Christian Soeller (c.soeller@auckland.ac.nz), Doug Burke (burke@ifa.hawaii.edu), and Craig DeForest (deforest@boulder.swri.edu).