HMSBEAGLE  1.0.0
libhmsbeagle/beagle.h
00001 /*
00002  * @file beagle.h
00003  *
00004  * Copyright 2009 Phylogenetic Likelihood Working Group
00005  *
00006  * This file is part of BEAGLE.
00007  *
00008  * BEAGLE is free software: you can redistribute it and/or modify
00009  * it under the terms of the GNU Lesser General Public License as
00010  * published by the Free Software Foundation, either version 3 of
00011  * the License, or (at your option) any later version.
00012  *
00013  * BEAGLE is distributed in the hope that it will be useful,
00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00016  * GNU Lesser General Public License for more details.
00017  *
00018  * You should have received a copy of the GNU Lesser General Public
00019  * License along with BEAGLE.  If not, see
00020  * <http://www.gnu.org/licenses/>.
00021  *
00022  * @brief This file documents the API as well as header for the
00023  * Broad-platform Evolutionary Analysis General Likelihood Evaluator
00024  *
00025  * OVERVIEW
00026  *
00027  * DEFINITION OF KEY CONCEPTS: INSTANCE, BUFFER, etc.
00028  *
00029  * @author Likelihood API Working Group
00030  *
00031  * @author Daniel Ayres
00032  * @author Peter Beerli
00033  * @author Michael Cummings
00034  * @author Aaron Darling
00035  * @author Mark Holder
00036  * @author John Huelsenbeck
00037  * @author Paul Lewis
00038  * @author Michael Ott
00039  * @author Andrew Rambaut
00040  * @author Fredrik Ronquist
00041  * @author Marc Suchard
00042  * @author David Swofford
00043  * @author Derrick Zwickl
00044  * 
00045  */
00046 
00047 #ifndef __beagle__
00048 #define __beagle__
00049 
00050 #include "libhmsbeagle/platform.h"
00051 
00059 enum BeagleReturnCodes {
00060     BEAGLE_SUCCESS                      =  0,  
00061     BEAGLE_ERROR_GENERAL                = -1,  
00062     BEAGLE_ERROR_OUT_OF_MEMORY          = -2,  
00063     BEAGLE_ERROR_UNIDENTIFIED_EXCEPTION = -3,  
00064     BEAGLE_ERROR_UNINITIALIZED_INSTANCE = -4,  
00066     BEAGLE_ERROR_OUT_OF_RANGE           = -5,  
00068     BEAGLE_ERROR_NO_RESOURCE            = -6,  
00069     BEAGLE_ERROR_NO_IMPLEMENTATION      = -7,  
00070     BEAGLE_ERROR_FLOATING_POINT         = -8   
00071 };
00072 
00081 enum BeagleFlags {
00082     BEAGLE_FLAG_PRECISION_SINGLE    = 1 << 0,    
00083     BEAGLE_FLAG_PRECISION_DOUBLE    = 1 << 1,    
00085     BEAGLE_FLAG_COMPUTATION_SYNCH   = 1 << 2,    
00086     BEAGLE_FLAG_COMPUTATION_ASYNCH  = 1 << 3,    
00088     BEAGLE_FLAG_EIGEN_REAL          = 1 << 4,    
00089     BEAGLE_FLAG_EIGEN_COMPLEX       = 1 << 5,    
00091     BEAGLE_FLAG_SCALING_MANUAL      = 1 << 6,    
00092     BEAGLE_FLAG_SCALING_AUTO        = 1 << 7,    
00093     BEAGLE_FLAG_SCALING_ALWAYS      = 1 << 8,    
00094     BEAGLE_FLAG_SCALING_DYNAMIC     = 1 << 19,   
00096     BEAGLE_FLAG_SCALERS_RAW         = 1 << 9,    
00097     BEAGLE_FLAG_SCALERS_LOG         = 1 << 10,   
00099     BEAGLE_FLAG_INVEVEC_STANDARD    = 1 << 20,   
00100     BEAGLE_FLAG_INVEVEC_TRANSPOSED  = 1 << 21,   
00102     BEAGLE_FLAG_VECTOR_SSE          = 1 << 11,   
00103     BEAGLE_FLAG_VECTOR_NONE         = 1 << 12,   
00105     BEAGLE_FLAG_THREADING_OPENMP    = 1 << 13,   
00106     BEAGLE_FLAG_THREADING_NONE      = 1 << 14,   
00108     BEAGLE_FLAG_PROCESSOR_CPU       = 1 << 15,   
00109     BEAGLE_FLAG_PROCESSOR_GPU       = 1 << 16,   
00110     BEAGLE_FLAG_PROCESSOR_FPGA      = 1 << 17,   
00111     BEAGLE_FLAG_PROCESSOR_CELL      = 1 << 18    
00112 };
00113 
00121 enum BeagleOpCodes {
00122         BEAGLE_OP_COUNT    = 7, 
00123         BEAGLE_OP_NONE     = -1 
00124 };
00125 
00129 typedef struct {
00130     int resourceNumber; 
00131     char* resourceName; 
00133     char* implName;     
00135     char* implDescription; 
00136     long flags;         
00138 } BeagleInstanceDetails;
00139 
00143 typedef struct {
00144     char* name;         
00145     char* description;  
00146     long  supportFlags; 
00147     long  requiredFlags;
00148 } BeagleResource;
00149 
00153 typedef struct {
00154     BeagleResource* list; 
00155     int length;     
00156 } BeagleResourceList;
00157 
00158 /* using C calling conventions so that C programs can successfully link the beagle library
00159  * (brace is closed at the end of this file)
00160  */
00161 #ifdef __cplusplus
00162 extern "C" {
00163 #endif
00164     
00172 BEAGLE_DLLEXPORT BeagleResourceList* beagleGetResourceList(void);
00173 
00203 // TODO: if setting your own matrices, might not need eigen buffers allocated, but still need
00204 //        category weight and state frequency buffers
00205 BEAGLE_DLLEXPORT int beagleCreateInstance(int tipCount,
00206                          int partialsBufferCount,
00207                          int compactBufferCount,
00208                          int stateCount,
00209                          int patternCount,
00210                          int eigenBufferCount,
00211                          int matrixBufferCount,
00212                          int categoryCount,
00213                          int scaleBufferCount,
00214                          int* resourceList,
00215                          int resourceCount,
00216                          long preferenceFlags,
00217                          long requirementFlags,
00218                          BeagleInstanceDetails* returnInfo);
00219 
00229 BEAGLE_DLLEXPORT int beagleFinalizeInstance(int instance);
00230 
00239 BEAGLE_DLLEXPORT int beagleFinalize(void);
00240         
00255 BEAGLE_DLLEXPORT int beagleSetTipStates(int instance,
00256                        int tipIndex,
00257                        const int* inStates);
00258 
00273 BEAGLE_DLLEXPORT int beagleSetTipPartials(int instance,
00274                          int tipIndex,
00275                          const double* inPartials);
00276 
00289 BEAGLE_DLLEXPORT int beagleSetPartials(int instance,
00290                       int bufferIndex,
00291                       const double* inPartials);
00292 
00306 BEAGLE_DLLEXPORT int beagleGetPartials(int instance,
00307                       int bufferIndex,
00308                       int scaleIndex,
00309                       double* outPartials);
00310 
00325 BEAGLE_DLLEXPORT int beagleSetEigenDecomposition(int instance,
00326                                 int eigenIndex,
00327                                 const double* inEigenVectors,
00328                                 const double* inInverseEigenVectors,
00329                                 const double* inEigenValues);
00330 
00342 BEAGLE_DLLEXPORT int beagleSetStateFrequencies(int instance,
00343                                          int stateFrequenciesIndex,
00344                                          const double* inStateFrequencies);    
00345     
00357 BEAGLE_DLLEXPORT int beagleSetCategoryWeights(int instance,
00358                                         int categoryWeightsIndex,
00359                                         const double* inCategoryWeights);
00360 
00371 BEAGLE_DLLEXPORT int beagleSetCategoryRates(int instance,
00372                            const double* inCategoryRates);
00383 BEAGLE_DLLEXPORT int beagleSetPatternWeights(int instance,
00384                                        const double* inPatternWeights);
00385     
00405 BEAGLE_DLLEXPORT int beagleUpdateTransitionMatrices(int instance,
00406                                    int eigenIndex,
00407                                    const int* probabilityIndices,
00408                                    const int* firstDerivativeIndices,
00409                                    const int* secondDerivativeIndices,
00410                                    const double* edgeLengths,
00411                                    int count);
00412 
00428 BEAGLE_DLLEXPORT int beagleSetTransitionMatrix(int instance,
00429                               int matrixIndex,
00430                               const double* inMatrix,
00431                               double paddedValue);
00432 
00446 BEAGLE_DLLEXPORT int beagleGetTransitionMatrix(int instance,
00447                                                                 int matrixIndex,
00448                                                                 double* outMatrix);
00449     
00466 BEAGLE_DLLEXPORT int beagleSetTransitionMatrices(int instance,
00467                                                  const int* matrixIndices,
00468                                                  const double* inMatrices,
00469                                                  const double* paddedValues,
00470                                                  int count);
00471 
00472 typedef struct {
00473         int destinationPartials;
00474         int destinationScaleWrite;
00475         int destinationScaleRead;
00476         int child1Partials;
00477         int child1TransitionMatrix;
00478         int child2Partials;
00479         int child2TransitionMatrix;
00480 } BeagleOperation;
00481 
00505 BEAGLE_DLLEXPORT int beagleUpdatePartials(const int instance,
00506                          const BeagleOperation* operations,
00507                          int operationCount,
00508                          int cumulativeScaleIndex);
00509 
00526 BEAGLE_DLLEXPORT int beagleWaitForPartials(const int instance,
00527                           const int* destinationPartials,
00528                           int destinationPartialsCount);
00529 
00541 BEAGLE_DLLEXPORT int beagleAccumulateScaleFactors(int instance,
00542                                  const int* scaleIndices,
00543                                  int count,
00544                                  int cumulativeScaleIndex);
00545 
00557 BEAGLE_DLLEXPORT int beagleRemoveScaleFactors(int instance,
00558                              const int* scaleIndices,
00559                              int count,
00560                              int cumulativeScaleIndex);
00561 
00570 BEAGLE_DLLEXPORT int beagleResetScaleFactors(int instance,
00571                             int cumulativeScaleIndex);
00572 
00582 BEAGLE_DLLEXPORT int beagleCopyScaleFactors(int instance,
00583                                             int destScalingIndex,
00584                                             int srcScalingIndex);
00585     
00607 // TODO: only need one state frequency index
00608 BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoods(int instance,
00609                                       const int* bufferIndices,
00610                                       const int* categoryWeightsIndices,
00611                                       const int* stateFrequenciesIndices,
00612                                       const int* cumulativeScaleIndices,
00613                                       int count,
00614                                       double* outSumLogLikelihood);
00615 
00643 BEAGLE_DLLEXPORT int beagleCalculateEdgeLogLikelihoods(int instance,
00644                                       const int* parentBufferIndices,
00645                                       const int* childBufferIndices,
00646                                       const int* probabilityIndices,
00647                                       const int* firstDerivativeIndices,
00648                                       const int* secondDerivativeIndices,
00649                                       const int* categoryWeightsIndices,
00650                                       const int* stateFrequenciesIndices,
00651                                       const int* cumulativeScaleIndices,
00652                                       int count,
00653                                       double* outSumLogLikelihood,
00654                                       double* outSumFirstDerivative,
00655                                       double* outSumSecondDerivative);
00656 
00668 BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods(int instance,
00669                                        double* outLogLikelihoods);
00670 
00682 BEAGLE_DLLEXPORT int beagleGetSiteDerivatives(int instance,
00683                                     double* outFirstDerivatives,
00684                                     double* outSecondDerivatives);    
00685     
00686 /* using C calling conventions so that C programs can successfully link the beagle library
00687  * (closing brace)
00688  */
00689 #ifdef __cplusplus
00690 }
00691 #endif
00692 
00693 #endif // __beagle__