beagle.h

Go to the documentation of this file.

#ifndef __beagle__
#define __beagle__

#include "libhmsbeagle/platform.h"

enum BeagleReturnCodes {
    BEAGLE_SUCCESS                      =  0,  
    BEAGLE_ERROR_GENERAL                = -1,  
    BEAGLE_ERROR_OUT_OF_MEMORY          = -2,  
    BEAGLE_ERROR_UNIDENTIFIED_EXCEPTION = -3,  
    BEAGLE_ERROR_UNINITIALIZED_INSTANCE = -4,  
    BEAGLE_ERROR_OUT_OF_RANGE           = -5,  
    BEAGLE_ERROR_NO_RESOURCE            = -6,  
    BEAGLE_ERROR_NO_IMPLEMENTATION      = -7,  
    BEAGLE_ERROR_FLOATING_POINT         = -8   
};

enum BeagleFlags {
    BEAGLE_FLAG_PRECISION_SINGLE    = 1 << 0,    
    BEAGLE_FLAG_PRECISION_DOUBLE    = 1 << 1,    
    BEAGLE_FLAG_COMPUTATION_SYNCH   = 1 << 2,    
    BEAGLE_FLAG_COMPUTATION_ASYNCH  = 1 << 3,    
    BEAGLE_FLAG_EIGEN_REAL          = 1 << 4,    
    BEAGLE_FLAG_EIGEN_COMPLEX       = 1 << 5,    
    BEAGLE_FLAG_SCALING_MANUAL      = 1 << 6,    
    BEAGLE_FLAG_SCALING_AUTO        = 1 << 7,    
    BEAGLE_FLAG_SCALING_ALWAYS      = 1 << 8,    
    BEAGLE_FLAG_SCALING_DYNAMIC     = 1 << 25,   
    BEAGLE_FLAG_SCALERS_RAW         = 1 << 9,    
    BEAGLE_FLAG_SCALERS_LOG         = 1 << 10,   
    BEAGLE_FLAG_INVEVEC_STANDARD    = 1 << 20,   
    BEAGLE_FLAG_INVEVEC_TRANSPOSED  = 1 << 21,   
    BEAGLE_FLAG_VECTOR_SSE          = 1 << 11,   
    BEAGLE_FLAG_VECTOR_AVX          = 1 << 24,   
    BEAGLE_FLAG_VECTOR_NONE         = 1 << 12,   
    BEAGLE_FLAG_THREADING_CPP       = 1 << 30,   
    BEAGLE_FLAG_THREADING_OPENMP    = 1 << 13,   
    BEAGLE_FLAG_THREADING_NONE      = 1 << 14,   
    BEAGLE_FLAG_PROCESSOR_CPU       = 1 << 15,   
    BEAGLE_FLAG_PROCESSOR_GPU       = 1 << 16,   
    BEAGLE_FLAG_PROCESSOR_FPGA      = 1 << 17,   
    BEAGLE_FLAG_PROCESSOR_CELL      = 1 << 18,   
    BEAGLE_FLAG_PROCESSOR_PHI       = 1 << 19,   
    BEAGLE_FLAG_PROCESSOR_OTHER     = 1 << 26,   
    BEAGLE_FLAG_FRAMEWORK_CUDA      = 1 << 22,   
    BEAGLE_FLAG_FRAMEWORK_OPENCL    = 1 << 23,   
    BEAGLE_FLAG_FRAMEWORK_CPU       = 1 << 27,   
    BEAGLE_FLAG_PARALLELOPS_STREAMS = 1 << 28,   
    BEAGLE_FLAG_PARALLELOPS_GRID    = 1 << 29    
};

enum BeagleOpCodes {
    BEAGLE_OP_COUNT              = 7, 
    BEAGLE_PARTITION_OP_COUNT    = 9, 
    BEAGLE_OP_NONE               = -1 
};

typedef struct {
    int resourceNumber; 
    char* resourceName; 
    char* implName;     
    char* implDescription; 
    long flags;         
} BeagleInstanceDetails;

typedef struct {
    char* name;         
    char* description;  
    long  supportFlags; 
    long  requiredFlags;
} BeagleResource;

typedef struct {
    BeagleResource* list; 
    int length;     
} BeagleResourceList;

/* using C calling conventions so that C programs can successfully link the beagle library
 * (brace is closed at the end of this file)
 */
#ifdef __cplusplus
extern "C" {
#endif

BEAGLE_DLLEXPORT const char* beagleGetVersion(void);

BEAGLE_DLLEXPORT const char* beagleGetCitation(void);

BEAGLE_DLLEXPORT BeagleResourceList* beagleGetResourceList(void);

// TODO: if setting your own matrices, might not need eigen buffers allocated, but still need
//        category weight and state frequency buffers
BEAGLE_DLLEXPORT int beagleCreateInstance(int tipCount,
                         int partialsBufferCount,
                         int compactBufferCount,
                         int stateCount,
                         int patternCount,
                         int eigenBufferCount,
                         int matrixBufferCount,
                         int categoryCount,
                         int scaleBufferCount,
                         int* resourceList,
                         int resourceCount,
                         long preferenceFlags,
                         long requirementFlags,
                         BeagleInstanceDetails* returnInfo);

BEAGLE_DLLEXPORT int beagleFinalizeInstance(int instance);

BEAGLE_DLLEXPORT int beagleFinalize(void);
        
BEAGLE_DLLEXPORT int beagleSetTipStates(int instance,
                       int tipIndex,
                       const int* inStates);

BEAGLE_DLLEXPORT int beagleSetTipPartials(int instance,
                         int tipIndex,
                         const double* inPartials);

BEAGLE_DLLEXPORT int beagleSetPartials(int instance,
                      int bufferIndex,
                      const double* inPartials);

BEAGLE_DLLEXPORT int beagleGetPartials(int instance,
                      int bufferIndex,
                      int scaleIndex,
                      double* outPartials);

BEAGLE_DLLEXPORT int beagleSetEigenDecomposition(int instance,
                                int eigenIndex,
                                const double* inEigenVectors,
                                const double* inInverseEigenVectors,
                                const double* inEigenValues);

BEAGLE_DLLEXPORT int beagleSetStateFrequencies(int instance,
                                         int stateFrequenciesIndex,
                                         const double* inStateFrequencies);    
    
BEAGLE_DLLEXPORT int beagleSetCategoryWeights(int instance,
                                        int categoryWeightsIndex,
                                        const double* inCategoryWeights);

BEAGLE_DLLEXPORT int beagleSetCategoryRates(int instance,
                                            const double* inCategoryRates);

BEAGLE_DLLEXPORT int beagleSetCategoryRatesWithIndex(int instance,
                                                     int categoryRatesIndex,
                                                     const double* inCategoryRates);

BEAGLE_DLLEXPORT int beagleSetPatternWeights(int instance,
                                       const double* inPatternWeights);
   
BEAGLE_DLLEXPORT int beagleSetPatternPartitions(int instance,
                                                int partitionCount,
                                                const int* inPatternPartitions);

// BEAGLE_DLLEXPORT int beagleSetPartitionsByPatternWeights(int instance,
//                                                          const int** inPartitionPatternWeights,
//                                                          int partitionCount);

//---TODO: Epoch model---//

BEAGLE_DLLEXPORT int beagleConvolveTransitionMatrices(int instance,
                                    const int* firstIndices,
                                    const int* secondIndices,
                                    const int* resultIndices,
                                    int matrixCount);

BEAGLE_DLLEXPORT int beagleUpdateTransitionMatrices(int instance,
                                   int eigenIndex,
                                   const int* probabilityIndices,
                                   const int* firstDerivativeIndices,
                                   const int* secondDerivativeIndices,
                                   const double* edgeLengths,
                                   int count);

BEAGLE_DLLEXPORT int beagleUpdateTransitionMatricesWithMultipleModels(int instance,
                                                                      const int* eigenIndices,
                                                                      const int* categoryRateIndices,
                                                                      const int* probabilityIndices,
                                                                      const int* firstDerivativeIndices,
                                                                      const int* secondDerivativeIndices,
                                                                      const double* edgeLengths,
                                                                      int count);

BEAGLE_DLLEXPORT int beagleSetTransitionMatrix(int instance,
                              int matrixIndex,
                              const double* inMatrix,
                              double paddedValue);

BEAGLE_DLLEXPORT int beagleGetTransitionMatrix(int instance,
                                int matrixIndex,
                                double* outMatrix);
    
BEAGLE_DLLEXPORT int beagleSetTransitionMatrices(int instance,
                                                 const int* matrixIndices,
                                                 const double* inMatrices,
                                                 const double* paddedValues,
                                                 int count);

    
typedef struct {
    int destinationPartials;    
    int destinationScaleWrite;  
    int destinationScaleRead;   
    int child1Partials;         
    int child1TransitionMatrix; 
    int child2Partials;         
    int child2TransitionMatrix; 
} BeagleOperation;

BEAGLE_DLLEXPORT int beagleUpdatePartials(const int instance,
                         const BeagleOperation* operations,
                         int operationCount,
                         int cumulativeScaleIndex);

typedef struct {
    int destinationPartials;    
    int destinationScaleWrite;  
    int destinationScaleRead;   
    int child1Partials;         
    int child1TransitionMatrix; 
    int child2Partials;         
    int child2TransitionMatrix; 
    int partition;              
    int cumulativeScaleIndex;   
} BeagleOperationByPartition;

BEAGLE_DLLEXPORT int beagleUpdatePartialsByPartition(const int instance,
                                                     const BeagleOperationByPartition* operations,
                                                     int operationCount);

BEAGLE_DLLEXPORT int beagleWaitForPartials(const int instance,
                          const int* destinationPartials,
                          int destinationPartialsCount);

BEAGLE_DLLEXPORT int beagleAccumulateScaleFactors(int instance,
                                 const int* scaleIndices,
                                 int count,
                                 int cumulativeScaleIndex);

BEAGLE_DLLEXPORT int beagleAccumulateScaleFactorsByPartition(int instance,
                                                             const int* scaleIndices,
                                                             int count,
                                                             int cumulativeScaleIndex,
                                                             int partitionIndex);

BEAGLE_DLLEXPORT int beagleRemoveScaleFactors(int instance,
                             const int* scaleIndices,
                             int count,
                             int cumulativeScaleIndex);


BEAGLE_DLLEXPORT int beagleRemoveScaleFactorsByPartition(int instance,
                                                         const int* scaleIndices,
                                                         int count,
                                                         int cumulativeScaleIndex,
                                                         int partitionIndex);


BEAGLE_DLLEXPORT int beagleResetScaleFactors(int instance,
                            int cumulativeScaleIndex);

BEAGLE_DLLEXPORT int beagleResetScaleFactorsByPartition(int instance,
                                                        int cumulativeScaleIndex,
                                                        int partitionIndex);


BEAGLE_DLLEXPORT int beagleCopyScaleFactors(int instance,
                                            int destScalingIndex,
                                            int srcScalingIndex);
                                            
BEAGLE_DLLEXPORT int beagleGetScaleFactors(int instance,                                            
                                           int srcScalingIndex,
                                           double* outScaleFactors);     
                                                                                                                                                                                                   
// TODO: only need one state frequency index
BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoods(int instance,
                                      const int* bufferIndices,
                                      const int* categoryWeightsIndices,
                                      const int* stateFrequenciesIndices,
                                      const int* cumulativeScaleIndices,
                                      int count,
                                      double* outSumLogLikelihood);

BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoodsByPartition(int instance,
                                                                  const int* bufferIndices,
                                                                  const int* categoryWeightsIndices,
                                                                  const int* stateFrequenciesIndices,
                                                                  const int* cumulativeScaleIndices,
                                                                  const int* partitionIndices,
                                                                  int partitionCount,
                                                                  int count,
                                                                  double* outSumLogLikelihoodByPartition,
                                                                  double* outSumLogLikelihood);

BEAGLE_DLLEXPORT int beagleCalculateEdgeLogLikelihoods(int instance,
                                      const int* parentBufferIndices,
                                      const int* childBufferIndices,
                                      const int* probabilityIndices,
                                      const int* firstDerivativeIndices,
                                      const int* secondDerivativeIndices,
                                      const int* categoryWeightsIndices,
                                      const int* stateFrequenciesIndices,
                                      const int* cumulativeScaleIndices,
                                      int count,
                                      double* outSumLogLikelihood,
                                      double* outSumFirstDerivative,
                                      double* outSumSecondDerivative);

BEAGLE_DLLEXPORT int beagleCalculateEdgeLogLikelihoodsByPartition(
                                                    int instance,
                                                    const int* parentBufferIndices,
                                                    const int* childBufferIndices,
                                                    const int* probabilityIndices,
                                                    const int* firstDerivativeIndices,
                                                    const int* secondDerivativeIndices,
                                                    const int* categoryWeightsIndices,
                                                    const int* stateFrequenciesIndices,
                                                    const int* cumulativeScaleIndices,
                                                    const int* partitionIndices,
                                                    int partitionCount,
                                                    int count,
                                                    double* outSumLogLikelihoodByPartition,
                                                    double* outSumLogLikelihood,
                                                    double* outSumFirstDerivativeByPartition,
                                                    double* outSumFirstDerivative,
                                                    double* outSumSecondDerivativeByPartition,
                                                    double* outSumSecondDerivative);

BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods(int instance,
                                       double* outLogLikelihoods);

BEAGLE_DLLEXPORT int beagleGetSiteDerivatives(int instance,
                                    double* outFirstDerivatives,
                                    double* outSecondDerivatives);    
    
/* using C calling conventions so that C programs can successfully link the beagle library
 * (closing brace)
 */
#ifdef __cplusplus
}
#endif

#endif // __beagle__