First swipe at State duplication for parallelism. Also some changes to subobjective...
[openmx:openmx.git] / src / omxObjective.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 *  omxObjective.h
20 *
21 *  Created: Timothy R. Brick    Date: 2009-02-17
22 *
23 *       Contains header information for the omxObjective class
24 *   omxObjective objects hold necessary information to simplify
25 *       objective function calculation.
26 *
27 **********************************************************/
28
29 #ifndef _OMXOBJECTIVE_H_
30 #define _OMXOBJECTIVE_H_
31
32 #include "R.h"
33 #include <Rinternals.h> 
34 #include <Rdefines.h>
35 #include <R_ext/Rdynload.h> 
36 #include <R_ext/BLAS.h>
37 #include <R_ext/Lapack.h>
38 #include "omxDefines.h"
39
40 typedef struct omxObjective omxObjective;
41 typedef struct omxRListElement omxRListElement;
42
43 #include "omxMatrix.h"
44 #include "omxAlgebra.h"
45 #include "omxAlgebraFunctions.h"
46 #include "omxData.h"
47 #include "omxState.h"
48 #include "omxObjectiveTable.h"
49
50 struct omxRListElement {
51         char label[250];
52         double* values;
53         int numValues;
54         int rows, cols;
55 };
56
57 struct omxObjective {                                   // An objective
58
59         /* Fields unique to Objective Functions */
60         void (*initFun)(omxObjective *oo, SEXP rObj);                                                           // Wrapper for initialization function (probably not needed)
61         void (*destructFun)(omxObjective* oo);                                                                          // Wrapper for the destructor object
62         void (*objectiveFun)(omxObjective* oo);                                                                         // Wrapper for the objective function itself
63         void (*repopulateFun)(omxObjective* oo, double* x, int n);                                      // To repopulate any data stored in the objective function
64         omxRListElement* (*setFinalReturns)(omxObjective* oo, int *numVals);            // Sets any R returns.
65         unsigned short int (*needsUpdateFun)(omxObjective* oo);                                         // To calculate recomputation
66         double* (*getStandardErrorFun)(omxObjective* oo);                                                       // To calculate standard errors
67         void (*gradientFun)(omxObjective* oo, double* grad);                                            // To calculate gradient
68         void (*populateAttrFun)(omxObjective* oo, SEXP algebra);                                        // Add attributes to the result algebra object
69     void* (*duplicateUnsharedArgs)(omxObjective*, const omxObjective*);         // Duplicate unshared args for thread safety
70         
71         omxObjective* subObjective;                                                                                                     // Subobjective structure in case it is needed.
72         
73     void* sharedArgs;                                                           // Common argument structure
74         void* argStruct;                                                                                                                        // Arguments needed for objective function
75         char* objType;                                                                                                                          // Type of Objective Function
76         double* hessian;                                                                                                                        // Hessian details
77         double* gradient;                                                                                                                       // Gradient details
78         double* stdError;                                                                                                                       // Standard Error estimates
79
80         omxMatrix* matrix;                                                                                                                      // The (1x1) matrix populated by this objective function
81
82 };
83
84 /* Initialize and Destroy */
85         void omxInitEmptyObjective(omxObjective *oo);
86         omxObjective* omxCreateSubObjective(omxObjective *oo);                                  // Generate a subobjective object
87         void omxFillMatrixFromMxObjective(omxMatrix* om, SEXP mxobj);                   // Create an objective function from an R MxObjective object
88         void omxFreeObjectiveArgs(omxObjective* objective);                                             // Frees all args
89         void omxGetObjectiveStandardErrors(omxObjective *oo);                                   // Get Standard Errors
90
91 /* Objective-specific implementations of matrix functions */
92         void omxObjectiveCompute(omxObjective *oo);
93         unsigned short int omxObjectiveNeedsUpdate(omxObjective *oo);
94         void omxObjectiveGradient(omxObjective* oo, double* gradient);                  // For gradient calculation.  If needed.
95     void omxDuplicateObjectiveMatrix(omxMatrix *tgt, const omxMatrix *src, omxState* targetState, short duplicateUnshared);
96     omxObjective* omxDuplicateObjective(omxObjective *target, const omxObjective *source, omxState* targetState, short duplicateUnshared);
97                                                                             // Duplicates the Objective object for parallelization
98         void omxObjectivePrint(omxObjective *source, char* d);                                  // Pretty-print a (small) matrix
99         
100         /* Helper functions */
101         void omxCalculateStdErrorFromHessian(double scale, omxObjective *oo);   // Does what it says
102         
103         /* Helpers related to objective initialization */
104         omxMatrix* omxNewMatrixFromIndexSlot(SEXP rObj, omxState* state, char* const slotName); // Gets a matrix from an R SEXP slot
105         omxData* omxNewDataFromDataSlot(SEXP rObj, omxState* state, char* const dataSlotName);  // Gets an mxData object from a data slot
106
107 #endif /* _OMXOBJECTIVE_H_ */