Passing Arguments¶

There are three types of parameters associated with routines in the PyIMSL Numeric Library: the return parameter, required (positional) parameters, and keyword parameters. The return parameter is output only, but others may be input, output or both input and output. The data types which can be used are described below.

Return Parameter¶

The value returned from a routine will be a scalar (usually int or double), NumPy ndarray object, or ctypes structure instance, depending on the return type of the IMSL C Library function. (Lists or tuples are never returned.) Some functions return None instead of returning a value.

NumPy ndarray objects can be indexed with [] notation. For example you can access the first 10 elements of a 1D ndarray with var[0:10]. You can access a single element of a 2 dimensional array with var[2,3]. You can grab an entire column of an array with var[:, 2]. More array operations are documented in a tip sheet at:

http://pages.physics.cornell.edu/~myers/teaching/ComputationalMethods/python/arrays.html

If a structure instance is returned, it will generally be returned as an array of structure elements, regardless of whether a single structure or multiple structures are being returned. To access the elements of the returned structure, use <variable name>[0].<element name>. For example, the structure returned by mlffNetworkInit has an element named “n_layers”. To access this element, you would use:

ffnet = mlffNetworkInit (4, 1)
print ("Number of layers: ", ffnet[0].n_layers)

Required (Positional) Parameters¶

These parameters are passed in order. They must appear first before any keyword parameters.

Scalar Input Parameter¶

In the documentation a scalar input parameter might be documented like this:

int nIntervals   (Input)

and used like this:

nIntervals = 3
result = imslRoutineName(nIntervals)

Complex Numbers¶

Complex scalars and arrays can be used like any other scalar value or used in arrays. For example, to create a scalar or list containing complex values:

x = 2+5j          # scalar
x = [2+5j, 4+6j]  # list array

Array Input Parameter¶

If an array is required for input, the parameter can be passed as a list, a tuple, or a NumPy ndarray. For example in the documentation the following describes 1D and 2D input arrays:

int x[]   (Input)
float y[[]] (Input)

Any one of the following could be used to create the arrays for input:

x = [1, 2, 4]         # a 1D list
x = (1, 2, 4)         # a 1D tuple
x = array([1, 2, 4])  # a 1D ndarray
y = [[1.0,2.0], [3.0,4.0]]         # a 2D list
y = ((1.0,2.0), (3.0,4.0))         # a 2D tuple
y = array([[1.0,2.0], [3.0,4.0]])  # a 2D ndarray
result = imslRoutineName(x, y)

Output and Input/Output Parameters¶

If a parameter is output, an empty list or ndarray must be passed (they are mutable in Python which allows their values/dimensions to be changed by the function). Generally an empty list or ndarray can be created, unless the parameter is used for both input and output. Use this notation:

outparam = []       # Empty list
outparam  = empty() # Empty ndarray

If the parameter is used for both input and output, it should be passed in a single-element list.

Keyword Parameters¶

Keyword parameters are passed with “name=value”, where “name” is the keyword name.

Boolean Input Keywords¶

If a keyword parameter is boolean (i.e., it has no arguments other than the keyword name), it should be passed with “keyword=True” or “keyword=False”. For example, to use the backward keyword from fftReal, the documentation for the keyword is:

backward
    Compute the backward transform.

And the function call would look like:

fftReal (p, backward=True, ...)

Scalar Input Keywords¶

Scalars are handled the same way for both keywords and positional parameters. For example, a keyword documented as a scalar would look like this:

nIntervals, int (Input)

And would be used like this:

result = imslRoutineName(nIntervals=5)

Array Input Keywords¶

Array input keywords are documented with [], as in this example for a 1D array:

frequencies, float[] (Input)

They are passed just as with arrays in positional parameters, using a list, tuple, or ndarray.

Output and Input/Output Parameters¶

As with positional parameters, if a parameter is output, an empty list or NumPy ndarray must be passed. For output scalars, a list must be used. For example a parameter documented like this:

permutation (Output)

Would be called like this:

perm = []
result = imslRoutineName(permutation=perm)

Multiple Argument Keywords¶

If a keyword parameter has multiple input or output arguments, the arguments are passed via a dictionary. The dictionary keys are described in the documentation as pairs of types and dictionary keys following the keyword name. For example, an input keyword would be documented like this:

bounds, float xlo, float xhi, float ylo, float yhi   (Input)

And would be used like this:

result = imslRoutineName(bounds ={'xlo':25, 'xhi':50, 'ylo':10, 'yhi':99})

An output keyword documented like this:

nValues, values, table   (Output)

Would be used like this:

nvals = {}  # pass in an empty disctionary
result = imslRoutineName(nValues=nvals)
print (nvals['values'])
print (nvals['table'])

Some keywords might have a mix of input/output parameters. For example, the factorAnalysis function has a keyword parameter directOblimRotation that takes 5 arguments, two of which are input, and three of which are output. This is documented as follows (with details on which are input and which output described further in the documentation):

directObliminRotation,  float w , int norm,  float b, float t,
float factorCorrelations (Input/Output)

To use this keyword in Python, pass the input parameters in a dictionary. The output parameters will be returned via the same dictionary:

w = -1.0
norm = 1
oblim = {'w':w, 'norm':norm}
result = factorAnalysis (...,directOblimRotation = oblim, ...)
print ('b: ', oblim['b'])
print ('t: ', oblim['t'])
print ('factor correlations: ', oblim['factorCorrelations'])