Removed inlining from mxMatrix functions.
[openmx:openmx.git] / src / omxMatrix.h
1 /*
2  *  Copyright 2007-2009 The OpenMx Project
3  *
4  *  Licensed under the Apache License, Version 2.0 (the "License");
5  *  you may not use this file except in compliance with the License.
6  *  You may obtain a copy of the License at
7  *
8  *       http://www.apache.org/licenses/LICENSE-2.0
9  *
10  *   Unless required by applicable law or agreed to in writing, software
11  *   distributed under the License is distributed on an "AS IS" BASIS,
12  *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  *  See the License for the specific language governing permissions and
14  *  limitations under the License.
15  *
16  */
17
18 /***********************************************************
19  *
20  *  omxMatrix.h
21  *
22  *  Created: Timothy R. Brick   Date: 2008-11-13 12:33:06
23  *
24  *      Contains header information for the omxMatrix class
25  *   omxDataMatrices hold necessary information to simplify
26  *      dealings between the OpenMX back end and BLAS.
27  *
28  **********************************************************/
29
30 #ifndef _OMXMATRIX_H_
31 #define _OMXMATRIX_H_
32
33 #include "R.h"
34 #include <Rinternals.h>
35 #include <Rdefines.h>
36 #include <R_ext/Rdynload.h>
37 #include <R_ext/BLAS.h>
38 #include <R_ext/Lapack.h>
39 #include "omxDefines.h"
40
41 typedef struct omxMatrix omxMatrix;
42
43 #include "omxAlgebra.h"
44 #include "omxObjective.h"
45 #include "omxState.h"
46
47
48 struct omxMatrix {                                              // A matrix
49                                                                                 //TODO: Improve encapsulation
50 /* Actually Useful Members */
51         int rows, cols;                                         // Matrix size  (specifically, its leading edge)
52         double* data;                                           // Actual Data Pointer
53         unsigned short colMajor;                        // and column-majority.
54
55 /* For Memory Administrivia */
56         unsigned short localData;                       // If data has been malloc'd, and must be freed.
57
58 /* For aliased matrices */                              // Maybe this should be a subclass, as well.
59         omxMatrix* aliasedPtr;                          // For now, assumes outside data if aliased.
60         unsigned short originalColMajor;        // Saved for reset of aliased matrix.
61         unsigned short originalRows;            // Saved for reset of aliased matrix.
62         unsigned short originalCols;            // Saved for reset of aliased matrix.
63
64 /* For BLAS Multiplication Speedup */   // TODO: Replace some of these with inlines or macros.
65         const char* majority;                           // Filled by compute(), included for speed
66         const char* minority;                           // Filled by compute(), included for speed
67         int leading;                                            // Leading edge; depends on original majority
68         int lagging;                                            // Non-leading edge.
69
70 /* Curent State */
71         omxState* currentState;                         // Optimizer State
72         unsigned short isDirty;                         // Retained, for historical purposes.
73         unsigned short isTemporary;                     // Whether or not to destroy the omxMatrix Structure when omxFreeAllMatrixData is called.
74         int lastCompute;                                        // Compute Count Number at last computation
75         int lastRow;                                            // Compute Count Number at last row update (Used for row-by-row computation only)
76
77 /* For Algebra Functions */                             // At most, one of these may be non-NULL.
78         omxAlgebra* algebra;                            // If it's not an algebra, this is NULL.
79         omxObjective* objective;                        // If it's not an objective function, this is NULL.
80
81 /* For inclusion in(or of) other matrices */
82         int numPopulateLocations;
83         omxMatrix** populateFrom;
84         int *populateFromRow, *populateFromCol;
85         int *populateToRow, *populateToCol;
86
87 };
88
89 /* Initialize and Destroy */
90         omxMatrix* omxInitMatrix(omxMatrix* om, int nrows, int ncols, unsigned short colMajor, omxState* os);                   // Set up matrix 
91         omxMatrix* omxInitTemporaryMatrix(omxMatrix* om, int nrows, int ncols, unsigned short colMajor, omxState* os);  // Set up matrix that can be freed
92         void omxFreeMatrixData(omxMatrix* om);                                                  // Release any held data.
93         void omxFreeAllMatrixData(omxMatrix* om);                                               // Ditto, traversing argument trees
94
95 /* Matrix Creation Functions */
96         omxMatrix* omxNewMatrixFromMxMatrix(SEXP matrix, omxState *state);                      // Create an omxMatrix from an R MxMatrix
97         omxMatrix* omxNewIdentityMatrix(int nrows, omxState* state);                            // Creates an Identity Matrix of a given size
98         extern omxMatrix* omxNewMatrixFromMxIndex(SEXP matrix, omxState* os);   // Create a matrix/algebra from a matrix pointer
99         extern omxMatrix* omxNewMatrixFromIndexSlot(SEXP rObj, omxState* state, char* const slotName);  // Gets a matrix from an R SEXP slot
100         
101
102 /* Getters 'n Setters */
103         double omxMatrixElement(omxMatrix *om, int row, int col);
104         double omxVectorElement(omxMatrix *om, int index);
105         void omxSetMatrixElement(omxMatrix *om, int row, int col, double value);
106         void omxSetVectorElement(omxMatrix *om, int index, double value);
107         double omxAliasedMatrixElement(omxMatrix *om, int row, int col);                        // Element from unaliased form of the same matrix
108         double* omxLocationOfMatrixElement(omxMatrix *om, int row, int col);
109         void omxMarkDirty(omxMatrix *om);
110
111 /* Matrix Modification Functions */
112         void omxZeroByZeroMatrix(omxMatrix *source);
113         void omxResizeMatrix(omxMatrix *source, int nrows, int ncols,
114                                                         unsigned short keepMemory);                                                                     // Resize, with or without re-initialization
115         omxMatrix* omxFillMatrixFromMxMatrix(omxMatrix* om, SEXP matrix, omxState *state);      // Populate an omxMatrix from an R MxMatrix
116         void omxProcessMatrixPopulationList(omxMatrix *matrix, SEXP matStruct);
117         void omxCopyMatrix(omxMatrix *dest, omxMatrix *src);                                                            // Copy across another matrix.
118
119 /* Function wrappers that switch based on inclusion of algebras */
120         void omxPrint(omxMatrix *source, char* d);                                                                                      // Pretty-print a (small) matrix
121         unsigned short int omxNeedsUpdate(omxMatrix *matrix);                                                           // Does this need to be recomputed?
122         void omxRecompute(omxMatrix *matrix);                                                                                           // Recompute the matrix if needed.
123         void omxCompute(omxMatrix *matrix);                                                                                                     // Recompute the matrix no matter what.
124
125 /* BLAS Wrappers */
126
127         void omxDGEMM(unsigned short int transposeA, unsigned short int transposeB,             // result <- alpha * A %*% B + beta * C
128                                         double* alpha, omxMatrix* a, omxMatrix *b, double* beta, omxMatrix* result);
129         void omxDGEMV(unsigned short int transposeMat, double* alpha, omxMatrix* mat,   // result <- alpha * A %*% B + beta * C
130                                         omxMatrix* vec, double* beta, omxMatrix*result, int* info);             // where B is treated as a vector
131
132         void omxDSYMV(unsigned short int transposeMat, double* alpha, omxMatrix* mat,   // result <- alpha * A %*% B + beta * C
133                                         omxMatrix* vec, double* beta, omxMatrix*result, int* info);             // only A is symmetric, and B is a vector
134
135         void omxDSYMM(unsigned short int symmOnLeft, double* alpha, omxMatrix* a,               // result <- alpha * A %*% B + beta * C
136                                         omxMatrix *b, double* beta, omxMatrix* result);                                 // One of A or B is symmetric
137
138         void omxDGETRF(omxMatrix* mat, int* ipiv, int* info);                                                   // LUP decomposition of mat
139         void omxDGETRI(omxMatrix* mat, int* ipiv, double* work, int* info);                             // Invert mat from LUP decomposition
140
141         void omxDPOTRF(omxMatrix* mat, int* info);                                                                              // Cholesky decomposition of mat
142         void omxDPOTRI(omxMatrix* mat, int* info);                                                                              // Invert mat from Cholesky
143
144 /* Aliased Matrix Functions */
145         void omxAliasMatrix(omxMatrix *alias, omxMatrix* const source);         // Allows aliasing for faster reset.
146         void omxResetAliasedMatrix(omxMatrix *matrix);                                          // Reset to the original matrix
147         void omxRemoveRowsAndColumns(omxMatrix* om, int numRowsRemoved, int numColsRemoved, int rowsRemoved[], int colsRemoved[]);
148
149 /* Matrix-Internal Helper functions */
150         void omxMatrixCompute(omxMatrix *matrix);
151         void omxPrintMatrix(omxMatrix *source, char* d);                    // Pretty-print a (small) matrix
152         unsigned short int omxMatrixNeedsUpdate(omxMatrix *matrix);
153
154 #endif /* _OMXMATRIX_H_ */