FUNCTION calculate_dot_product_of_two_vectors, vec1, vec2, status, NO_PAR_CHECK = no_par_check
; Description: This function calculates the dot product (or scalar product, or inner product) of
; two input vectors "vec1" and "vec2" of the same length. The dot product of two
; vectors V1 and V2 is a scalar (single number) defined as:
;
; N
; V1.V2 = SUM (V1_i*V2_i)
; i=1
;
; where V1_i and V2_i are the ith elements of the vectors V1 and V2 respectively,
; and N is the number of elements in each vector.
; This function uses the IDL function "matrix_multiply" to obtain the dot product
; rather than calculating the equivalent expression "total(vec1*vec2, /DOUBLE)".
; The reason for this is that the "matrix_multiply" implementation is faster, with
; a speed increase of ~2.14 times for vectors of length 1000 elements, and even
; better for longer vectors. In fact, expressions of the type "total(vec1*vec2, /DOUBLE)"
; should in general be replaced by:
;
; result = calculate_dot_product_of_two_vectors(vec1, vec2, status, /NO_PAR_CHECK)
;
; where possible, and assuming that parameter checks on "vec1" and "vec2" are
; unnecessary.
;
; N.B: (i) I also developed a similar module for calculating the dot product of
; two arrays, using the IDL "reform" function to convert the arrays to
; vectors which in turn allowed me to employ the IDL "matrix_multiply"
; function. However, I found that this slowed down the dot product
; calculation for arrays of dimension two and higher. Hence, DanIDL does
; not supply an equivalent function "calculate_dot_product_of_two_arrays.pro",
; and the user is encouraged to use the expression "total(arr1*arr2, /DOUBLE)"
; for the dot product of two arrays "arr1" and "arr2".
;
; (ii) I have tried implementing C++ code in order to achieve a faster
; execution of this function. However, too few numerical operations
; are performed by this function for C++ code to make a noticeable
; difference to the execution time. Hence I have decided not to
; provide this option.
;
; Input Parameters:
;
; vec1 - INTEGER/LONG/FLOAT/DOUBLE SCALAR/VECTOR - A scalar number or a vector of numbers.
; vec2 - INTEGER/LONG/FLOAT/DOUBLE SCALAR/VECTOR - A scalar number or a vector of numbers.
; This parameter must have the same number
; of elements as "vec1".
; status - ANY - A variable which will be used to contain the output status of the function
; on returning (see output parameters below).
;
; Output Parameters:
;
; status - INTEGER - If the function successfully calculated the dot product, then "status"
; is returned with a value of "1", otherwise it is returned with a value
; of "0".
;
; Return Value:
;
; The return value is a DOUBLE type number representing the dot product of the two vectors
; "vec1" and "vec2".
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the function will not
; perform parameter checking on the input parameters, reducing function overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 26/01/2010 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "vec1" contains numbers of the correct type
;Check that "vec1" is a scalar or vector
;Check that "vec2" contains numbers of the correct type
;Check that "vec2" is a scalar or vector
;Check that "vec1" and "vec2" have the same number of elements
;Calculate the dot product
;Set "status" to "1"
;Return the dot product