Function Notes
Most of Eigen4AutoIt's functions follow an intuitive naming convention, consisting of up to four parts, separated by underscores. The first two parts are always present, whereas the third and fourth can each be absent, depending on the function's context. “Actions” are often a single verb or noun; notable exceptions are those that start with "Get," "Set," "Reset," "Release," and "Convert," as well as those whose next word is "Matrix" or "Array." In most cases, alternate phrasing with underscores in different places will be converted into the official name through a multitude of alias function wrappers.
If no target is specified, a function will act on the entire matrix (or matrices) supplied. Functions with Diag suffix act on the main diagonal only, Col/Row on a specified column or row, and Block on a rectangular area defined by startRow, startCol (both base-0), blockRows (height), and blockCols (width). Colwise and Rowwise act on the entire matrix, but on each col/row individually, storing the result in a separate vector. Suffix _inPlace signals that the result of the action is to be stored in the input matrix itself, replacing the original content. This will only work if that result fits (see Multiplication). ColMajor and RowMajor determine the order of CwiseLinSpaced; Single applies only to MatrixSpecs. Various other suffices are used only in the context of specifc functions.
A special tool called the Function Selector can quickly familiarise beginners with how function names are constructed. It displays three animated barrels that can be spun in either direction at the click of a mouse (above or below the barrel's front face; click multiple times for additional speed). The left-most barrel cycles through all Actions; as soon as it is stopped (by clicking the front face, or after "braking" by clicking on the side opposite from the current rotation direction), the other two barrels have their faces updated to reflect the various suffix members that this Action may have. In the panel above the barrels, any valid combination of an Action and 0-2 suffices results in the display of a short description, and the formal function expression with all parameters and default values. Any such function can then be copied to the Clipboard by pressing Ctrl-C (without having to select the displayed text first); whether the listed
parameters are also copied depends on the parameter-mode, which is controlled by repeatedly pressing Ctrl-P to cycle thorugh the three options (no parameters, essential parameters only, all parameters). As a
bonus, This tool can also be used to add Eigen4AutoIt function tooltips and auto-completion to the Scite editor, by pressing Ctrl-A (whereas Ctrl-R removes these again from your Scite user profile).
Eigen4AutoIt functions, like AutoIt functions, are first class objects, meaning you can assign a function to a variable, and pass it around as an argument or return from another function. For example, instead of writing these two lines:
$matC = _Eigen_Multiply_AB ( $matA, $matB ) _Eigen_MatrixSpecs ( $matC )
one could nest the second call into the first, obviating the need to store the matrix ID of the intermediate result in a separate variable, like this:
_Eigen_MatrixSpecs ( _Eigen_Multiply_AB ( $matA, $matB ) )
But even though variable $matC is no longer used, a separate entry in the MatrixList is still created for each intermediate results matrix. You can maintain full control of your memory resources by placing the ListMarker just before starting some multi-step procedure with several intermediates, and releasing all matrices created afterwards, with the exception of the final result(s) you wish to keep. See
_Eigen_ReleaseFromMarker_Except() for details.
Many functions contain optional parameters that can be omitted. If you wish to specify an optional parameter, however, all preceding parameters must also be specified! This is a standard AutoIt convention.
For example, consider _Eigen_SetActiveMatrix( $matrixstring[, $resetAll[, $releaseExisting ]] ). If you wish to specify the last boolean flag $releaseExisting, you must specify $resetAll too. If you do not know what to parse, you can always use the Default keyword, to use its default setting.
@error = 0 is almost always success
Return = varies (often it is the target matrix ID), but is typically non-zero for success. If someFunc() Then ;...function worked
If Not someFunc() Then ;...function failed
$matA = _Eigen_LoadMatrix ( "C:\someMatrixFile.bin" ) If@error = -1 Then ; matrix was not properly loaded
If a function sets the @error flag, you should ideally check it before using a return value - if @error indicates an error then the function return value may be undefined or invalid.
Currently, the Eigen4AutoIt environment comprises 367 main functions, consisting of 257 dll-calling wrappers and 110 work environment functions (such as _Eigen_CreateMatrix() ). The function wrappers themselves call one of nine type-specific function variants (NB not all variants are available for each type), which total 1,851 altogether. Each of these variants exists in two versions, for Debugging mode (with internal error checking) and for Computing Mode (without such checks). Note that separate variants may exist that act on a complex matrix as entity, its real part, or its imaginary part (that is, the rightmost cyan subsections do not overlap with the red subsections). Lastly, to maximise ease-of-use, an additional 758 alias wrappers are provided that allow the same main function to be accessed using variations of the formal function name.
Created with the Personal Edition of HelpNDoc: Write EPub books for the iPad