Functional._call

Functional._call(x, out=None, **kwargs)

Implementation of the operator evaluation.

This method is the private backend for the evaluation of an operator. It needs to match certain signature conventions, and its implementation type is inferred from its signature.

The following signatures are allowed:

Python 2 and 3:

  • _call(self, x) --> out-of-place evaluation

  • _call(self, vec, out) --> in-place evaluation

  • _call(self, x, out=None) --> both

Python 3 only:

  • _call(self, x, *, out=None) (out as keyword-only argument) --> both

For disambiguation, the instance name (the first argument) must be 'self'.

The name of the out argument must be 'out', the second argument may have any name.

Additional variable **kwargs and keyword-only arguments (Python 3 only) are also allowed.

Parameters:
xdomain element-like

Element to which the operator is applied

outrange element, optional

Element to which the result is written

Returns:
outrange element-like

Result of the evaluation. If out was provided, the returned object is a reference to it.

Notes

Some general advice on how to implement operator evaluation:

  • If you just write a quick implementation or are not too worried about efficiency, it may be easiest to write the evaluation out-of-place.

  • We recommend advanced and performance-aware users to implement the in-place pattern if the wrapped code supports it. In-place evaluation is usually significantly faster since it avoids the allocation of new memory and a copy compared to out-of-place evaluation.

  • If there is a significant performance gain from implementing an out-of-place method separately, use the pattern for both (out optional) and decide according to the given out parameter which one to use.

  • If your evaluation code does not support in-place evaluation, use the out-of-place pattern.

Note that the public call pattern op() using op.__call__ provides a default implementation of the underlying in-place or out-of-place call even if you choose the respective other pattern.

See the operator guide for more info on in-place vs. out-of-place evaluation.