Final returns ought to support matrices (?)
[openmx:openmx.git] / src / omxFitFunction.h
1 /*
2  *  Copyright 2007-2013 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 *  omxFitFunction.h
20 *
21 *  Created: Timothy R. Brick    Date: 2009-02-17
22 *
23 *       Contains header information for the omxFitFunction class
24 *   omxFitFunction objects hold necessary information to simplify
25 *       fit function calculation.
26 *
27 **********************************************************/
28
29 #ifndef _OMXFITFUNCTION_H_
30 #define _OMXFITFUNCTION_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 omxFitFunction omxFitFunction;
41
42
43 #include "omxMatrix.h"
44 #include "omxAlgebra.h"
45 #include "omxAlgebraFunctions.h"
46 #include "omxData.h"
47 #include "omxState.h"
48 #include "omxExpectation.h"
49
50 typedef struct {
51         char label[250];
52         double* values;
53         int numValues;
54         int rows, cols;
55 } omxRListElement;
56
57 struct omxFitFunction {                                 // A fit function
58
59         /* Fields unique to FitFunction Functions */
60         void (*initFun)(omxFitFunction *oo, SEXP rObj);                                                         // Wrapper for initialization function (probably not needed)
61         void (*destructFun)(omxFitFunction* oo);                                                                        // Wrapper for the destructor object
62         // ffcompute is somewhat redundent because grad=NULL when gradients are unwanted
63         void (*computeFun)(omxFitFunction* oo, int ffcompute, double* grad);
64         void (*repopulateFun)(omxFitFunction* oo, double* x, int n);                                    // To repopulate any data stored in the fit function
65         omxRListElement* (*setFinalReturns)(omxFitFunction* oo, int *numVals);          // Sets any R returns.
66         double* (*getStandardErrorFun)(omxFitFunction* oo);                                                     // To calculate standard errors
67         void (*populateAttrFun)(omxFitFunction* oo, SEXP algebra);                                      // Add attributes to the result algebra object
68         
69         SEXP rObj;                                                                                                                                      // Original r Object Pointer
70         omxExpectation* expectation;                                                                                            // Data expectation object
71         void* sharedArgs;                                                                                                                       // Common argument structure
72         void* argStruct;                                                                                                                        // Arguments needed for fit function
73 // This is always a pointer to a static string.
74 // We do not need to allocate or free it.
75         const char* fitType;                                                                                                            // Type of FitFunction Function
76         double* hessian;                                                                                                                        // Hessian details
77         double* gradient;                                                                                                                       // Gradient details
78         double* stdError;                                                                                                                       // Standard Error estimates
79         unsigned short int isPrepopulated;                                                                                      // Object has had some values prepopulated to allow object sharing
80
81         omxMatrix* matrix;                                                                                                                      // The (1x1) matrix populated by this fit function
82         int usesChildModels;    // whether to create child models for parallelization
83 };
84
85 /* Initialize and Destroy */
86         void omxInitEmptyFitFunction(omxFitFunction *oo);
87         void omxFillMatrixFromMxFitFunction(omxMatrix* om, SEXP mxobj, 
88                 unsigned short hasMatrixNumber, int matrixNumber);                                              // Create an omxFitFunction from an R MxFitFunction object
89         void omxFreeFitFunctionArgs(omxFitFunction* fitFunction);                                               // Frees all args
90         void omxGetFitFunctionStandardErrors(omxFitFunction *oo);                                       // Get Standard Errors
91
92 /* FitFunction-specific implementations of matrix functions */
93 void omxFitFunctionCompute(omxFitFunction *off, int want, double* gradient);
94         void omxDuplicateFitMatrix(omxMatrix *tgt, const omxMatrix *src, omxState* targetState);
95         omxFitFunction* omxCreateDuplicateFitFunction(omxFitFunction *tgt, const omxFitFunction *src, omxState* newState);
96         
97         void omxFitFunctionPrint(omxFitFunction *source, char* d);                                      // Pretty-print a (small) matrix
98         
99         /* Helper functions */
100         void omxCalculateStdErrorFromHessian(double scale, omxFitFunction *oo); // Does what it says
101         
102         /* Helpers related to fit function initialization */
103         omxMatrix* omxNewMatrixFromSlot(SEXP rObj, omxState* state, char* const slotName);      // Gets a matrix from an R SEXP slot
104
105 void omxFitFunctionCreateChildren(omxState *globalState, int numThreads);
106
107 enum omxFFCompute {
108   FF_COMPUTE_FIT      = 1<<0,
109   FF_COMPUTE_GRADIENT = 1<<1,
110   FF_COMPUTE_HESSIAN  = 1<<2
111 };
112
113 #endif /* _OMXFITFUNCTION_H_ */