PRO define_polyterms, ndim, degree, polyterms, nterms, status, MAX_EXPONENT = max_exponent, ORGANISE_BY_TOTAL_DEGREE = organise_by_total_degree
; Description: This module defines the polynomial terms "polyterms" for a polynomial function of
; "ndim" dimensions of degree "degree". The module also returns the number of
; polynomial terms via the parameter "nterms". Note that a polynomial of degree zero
; is taken to have only one constant term.
; The following are a few examples of sets of polynomial terms P for polynomial
; functions of N dimensions of degree D:
;
; (i) N = 3, D = 0, P = { C }
; (ii) N = 1, D = 1, P = { C, x }
; (iii) N = 3, D = 1, P = { C, x, y, z}
; (iv) N = 1, D = 2, P = { C, x, x^2 }
; (v) N = 2, D = 2, P = { C, x, x^2, y, xy, y^2}
; (vi) N = 3, D = 3, P = { C, x, x^2, x^3, y, xy, yx^2, y^2, xy^2, y^3, z, xz, zx^2
; yz, xyz, zy^2, z^2, xz^2, yz^2, z^3}
;
; By setting the keyword MAX_EXPONENT, then the module will interpret "degree" as
; the maximum exponent for each variable in any term of the polynomial. In this case
; "degree" may also be supplied as a vector of maximum exponents of length "ndim",
; where each element represents the maximum exponent for the corresponding variable
; in any term of the polynomial.
; The following are a few examples of sets of polynomial terms P for polynomial
; functions of N dimensions with maximum exponent D for each variable:
;
; (i) N = 3, D = 0, P = { C }
; (ii) N = 1, D = 1, P = { C, x }
; (iii) N = 3, D = 1, P = { C, x, y, xy, z, xz, yz, xyz }
; (iv) N = 2, D = 2, P = { C, x, x^2, y, xy, yx^2, y^2, xy^2, (x^2)(y^2) }
; (v) N = 2, D = 3, P = { C, x, x^2, x^3, y, xy, yx^2, yx^3, y^2, xy^2, (x^2)(y^2)
; (x^3)(y^2), y^3, xy^3, (x^2)(y^3), (x^3)(y^3) }
;
; The following are a few examples of sets of polynomial terms P for polynomial
; functions of N dimensions with maximum exponents D_1, D_2,..., D_N for each
; variable:
;
; (i) N = 3, D_1 = 0, D_2 = 0, D_3 = 1, P = { C, z }
; (ii) N = 1, D_1 = 1, P = { C, x }
; (iii) N = 3, D_1 = 1, D_2 = 1, D_3 = 0, P = { C, x, y, xy }
; (iv) N = 2, D_1 = 2, D_2 = 1, P = { C, x, x^2, y, xy, yx^2 }
; (v) N = 2, D_1 = 3, D_2 = 2, P = { C, x, x^2, x^3, y, xy, yx^2, yx^3, y^2, xy^2
; (x^2)(y^2), (x^3)(y^2) }
;
; The default ordering of the polynomial terms is by increasing degree in each
; dimension, starting with the last dimension and working to the first dimension.
; This may be seen in the above examples.
; By setting the keyword ORGANISE_BY_TOTAL_DEGREE, the module will order the
; polynomial terms first in ascending order of total degree, and then by
; increasing degree in each dimension, starting with the last dimension and
; working towards the first dimension. This may be desirable if an ordering
; equivalent to that of "Pascal's Triangle" is required. For instance, to
; generate Pascal's Triangle in two dimensions up to a degree of 3, set "ndim" to
; "2", "degree" to "3", and set the keyword ORGANISE_BY_TOTAL_DEGREE. This will
; generate the following set of polynomial terms:
;
; P = { C, x, y, x^2, xy, y^2, x^3, yx^2, xy^2, y^3 }
;
; Input Parameters:
;
; ndim - INTEGER/LONG - The number of dimensions, with corresponding variables, of which the
; polynomial expression is a function. This parameter must be positive.
; degree - INTEGER/LONG SCALAR/VECTOR - The degree of the polynomial function. This parameter
; must be a non-negative scalar value, unless the
; keyword MAX_EXPONENT is set, in which case "degree"
; may be a non-negative scalar value or a one-dimensional
; vector of length "ndim" with non-negative values. If
; the keyword MAX_EXPONENT is set and "degree" is a
; scalar value, then "degree" represents the maximum
; exponent for each variable in any term of the
; polynomial. If the keyword MAX_EXPONENT is set and
; "degree" is a vector, then the elements of "degree"
; represent the maximum exponent for the corresponding
; variable in any term of the polynomial.
;
; Output Parameters:
;
; polyterms - LONG ARRAY - An "ndim" by "nterms" array of LONG values where each set of "ndim"
; numbers represents the exponents of the corresponding variables in
; each polynomial term.
; nterms - LONG - The number of terms in the polynomial function.
; status - INTEGER - If the module successfully defined the polynomial terms "polyterms", then
; "status" is returned with a value of "1", otherwise it is returned with a
; value of "0".
;
; Keywords:
;
; If the keyword MAX_EXPONENT is set (as "/MAX_EXPONENT"), then the module will interpret
; "degree" as the maximum exponent for each variable in any term of the polynomial. In this
; case "degree" may also be supplied as a vector of maximum exponents of length "ndim", where
; each element represents the maximum exponent for the corresponding variable in any term of
; the polynomial.
;
; If the keyword ORGANISE_BY_TOTAL_DEGREE is set (as "/ORGANISE_BY_TOTAL_DEGREE"), then the
; module will order the polynomial terms first in ascending order of total degree, and then
; by increasing degree in each dimension, starting with the last dimension and working
; towards the first dimension. This may be desirable if an ordering equivalent to that of
; "Pascal's Triangle" is required.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 21/03/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "ndim" is a positive number of the correct type
;If the keyword MAX_EXPONENT is set
;Check that "degree" is a scalar or vector of the correct number type, with the correct number
;of elements, and with value(s) that are non-negative
;Determine an upper limit to the number of polynomial terms that can be generated
;If the keyword MAX_EXPONENT is not set
;Check that "degree" is a non-negative scalar number of the correct type
;Determine an upper limit to the number of polynomial terms that can be generated
;Set up the array to hold the definition of the polynomial terms
;Determine the set of polynomial terms that are a function of the last dimension only
;If the polynomial function is a function of one dimension only, then set "status" to "1"
;Recursively iterate the generation of the rest of the polynomial terms, considering each variable
;in reverse order
;Create a copy of the current set of polynomial terms
;If the keyword MAX_EXPONENT is set, then define the maximum exponent for the current variable
;For each polynomial term that has been generated so far
;Generate a new set of polynomial terms and insert these terms into the array holding the
;definition of the polynomial terms
;Update the number of polynomial terms that have been generated so far
;If the keyword MAX_EXPONENT has not been set
;Calculate the degree of each polynomial term that has been generated so far
;Remove the polynomial terms that have a degree greater than the requested polynomial degree
;If the keyword MAX_EXPONENT has not been set, then trim the unused entries in the array holding
;the definition of the polynomial terms
;If the keyword ORGANISE_BY_TOTAL_DEGREE has been set, then organise the polynomial terms first
;in ascending order of total degree, and then by increasing degree in each dimension, starting
;with the last dimension and working towards the first dimension
;Set "status" to "1"