function module

Utility functions

Functions complex_to_seq() and seq_to_complex() are useful to convert between the matrix representation of complex numbers and Python complex.

The function mean() evaluates the mean of a sequence.

The function implicit() will evaluate the solution to \(fn(x) = 0\)

Module contents

complex_to_seq(z)

Transform a complex number into a 4-element sequence

Parameters:: z – a number

This function produces a sequence of the form [x, -y, y, x] for a complex number z = x + yj.

See also seq_to_complex()

Example:

>>> import numpy
>>> z = 1 + 2j
>>> function.complex_to_seq(z)
(1.0, -2.0, 2.0, 1.0)

>>> m = numpy.array( function.complex_to_seq(z) )
>>> m.shape = (2,2)
>>> print( m )
[[ 1. -2.]
 [ 2.  1.]]

Note

A matrix of the form [[x,-y],[y,x]] can be used to represent z in matrix computations.

Example:

>>> z = 1 + 2j
>>> m1 = numpy.array( function.complex_to_seq(z) )
>>> m1.shape = (2,2)
>>> m2 = numpy.array( function.complex_to_seq( z.conjugate() ) )
>>> m2.shape = (2,2)
>>> print( numpy.matmul(m1,m2) )
[[5. 0.]
 [0.  5.]]

implicit(fn, x_min, x_max, epsilon=1e-13)

Return the solution to \(fn(x) = 0\)

Parameters:

fn – a user-defined function of one argument
x_min (float) – lower limit of search range
x_max (float) – upper limit of search range
epsilon (float) – tolerance for algorithm convergence

x_min and x_max delimit a range containing a single root (ie, the function must cross the x-axis just once inside the range).

Note

A RuntimeError is raised if the search algorithm fails to converge.
An AssertionError is raised if preconditions are not satisfied.

Example:

>>> near_unity = ureal(1,0.05)
>>> fn = lambda x: x**2 - near_unity
>>> function.implicit(fn,0,2)
ureal(1.0,0.025...,inf)

New in version 1.3.4.

mean(seq, *args, **kwargs)

Return the arithmetic mean of data in seq

Parameters:

seq – a sequence, ndarray, or iterable, of numbers or uncertain numbers
args – optional arguments when seq is an ndarray
kwargs – optional keyword arguments when seq is an ndarray

An uncertain number is returned if seq contains uncertain numbers.

Example

>>> seq = [ ureal(1,1), ureal(2,1), ureal(3,1) ]
>>> function.mean(seq)
ureal(2.0,0.5773502691896257,inf)

Note

When seq is an empty ndarray or a ndarray containing any NaN elements NaN is returned.

In other cases, a ZeroDivisionError is raised when there are no elements in seq.

seq_to_complex(seq)

Transform a 4-element sequence into a complex number

Parameters:: seq – a 4-element sequence
Raises:: RuntimeError – if seq is ill-conditioned

The legitimate form of elements in seq is [x, -y, y, x], where x is the real component and y is the imaginary component of a complex number.