BEAGLE
An Application Programming Interface and High-Performance Computing Library for Statistical Phylogenetics
beagle.h
Go to the documentation of this file.
1 
108 #ifndef __beagle__
109 #define __beagle__
110 
111 #include "libhmsbeagle/platform.h"
112 
132 };
133 
184 };
185 
197 };
198 
202 typedef struct {
204  char* resourceName;
206  char* implName;
209  long flags;
212 
216 typedef struct {
217  char* name;
218  char* description;
222 
226 typedef struct {
228  int length;
230 
231 /* using C calling conventions so that C programs can successfully link the beagle library
232  * (brace is closed at the end of this file)
233  */
234 #ifdef __cplusplus
235 extern "C" {
236 #endif
237 
245 BEAGLE_DLLEXPORT const char* beagleGetVersion(void);
246 
255 BEAGLE_DLLEXPORT const char* beagleGetCitation(void);
256 
265 BEAGLE_DLLEXPORT BeagleResourceList* beagleGetResourceList(void);
266 
296 // TODO: if setting your own matrices, might not need eigen buffers allocated, but still need
297 // category weight and state frequency buffers
298 BEAGLE_DLLEXPORT int beagleCreateInstance(int tipCount,
299  int partialsBufferCount,
300  int compactBufferCount,
301  int stateCount,
302  int patternCount,
303  int eigenBufferCount,
304  int matrixBufferCount,
305  int categoryCount,
306  int scaleBufferCount,
307  int* resourceList,
308  int resourceCount,
309  long preferenceFlags,
310  long requirementFlags,
311  BeagleInstanceDetails* returnInfo);
312 
322 BEAGLE_DLLEXPORT int beagleFinalizeInstance(int instance);
323 
332 BEAGLE_DLLEXPORT int beagleFinalize(void);
333 
348 BEAGLE_DLLEXPORT int beagleSetTipStates(int instance,
349  int tipIndex,
350  const int* inStates);
351 
366 BEAGLE_DLLEXPORT int beagleSetTipPartials(int instance,
367  int tipIndex,
368  const double* inPartials);
369 
382 BEAGLE_DLLEXPORT int beagleSetPartials(int instance,
383  int bufferIndex,
384  const double* inPartials);
385 
399 BEAGLE_DLLEXPORT int beagleGetPartials(int instance,
400  int bufferIndex,
401  int scaleIndex,
402  double* outPartials);
403 
418 BEAGLE_DLLEXPORT int beagleSetEigenDecomposition(int instance,
419  int eigenIndex,
420  const double* inEigenVectors,
421  const double* inInverseEigenVectors,
422  const double* inEigenValues);
423 
435 BEAGLE_DLLEXPORT int beagleSetStateFrequencies(int instance,
436  int stateFrequenciesIndex,
437  const double* inStateFrequencies);
438 
450 BEAGLE_DLLEXPORT int beagleSetCategoryWeights(int instance,
451  int categoryWeightsIndex,
452  const double* inCategoryWeights);
453 
464 BEAGLE_DLLEXPORT int beagleSetCategoryRates(int instance,
465  const double* inCategoryRates);
466 
478 BEAGLE_DLLEXPORT int beagleSetCategoryRatesWithIndex(int instance,
479  int categoryRatesIndex,
480  const double* inCategoryRates);
481 
492 BEAGLE_DLLEXPORT int beagleSetPatternWeights(int instance,
493  const double* inPatternWeights);
494 
507 BEAGLE_DLLEXPORT int beagleSetPatternPartitions(int instance,
508  int partitionCount,
509  const int* inPatternPartitions);
510 
523 // BEAGLE_DLLEXPORT int beagleSetPartitionsByPatternWeights(int instance,
524 // const int** inPartitionPatternWeights,
525 // int partitionCount);
526 
528 //---TODO: Epoch model---//
530 
545 BEAGLE_DLLEXPORT int beagleConvolveTransitionMatrices(int instance,
546  const int* firstIndices,
547  const int* secondIndices,
548  const int* resultIndices,
549  int matrixCount);
550 
570 BEAGLE_DLLEXPORT int beagleUpdateTransitionMatrices(int instance,
571  int eigenIndex,
572  const int* probabilityIndices,
573  const int* firstDerivativeIndices,
574  const int* secondDerivativeIndices,
575  const double* edgeLengths,
576  int count);
577 
598 BEAGLE_DLLEXPORT int beagleUpdateTransitionMatricesWithMultipleModels(int instance,
599  const int* eigenIndices,
600  const int* categoryRateIndices,
601  const int* probabilityIndices,
602  const int* firstDerivativeIndices,
603  const int* secondDerivativeIndices,
604  const double* edgeLengths,
605  int count);
606 
622 BEAGLE_DLLEXPORT int beagleSetTransitionMatrix(int instance,
623  int matrixIndex,
624  const double* inMatrix,
625  double paddedValue);
626 
640 BEAGLE_DLLEXPORT int beagleGetTransitionMatrix(int instance,
641  int matrixIndex,
642  double* outMatrix);
643 
660 BEAGLE_DLLEXPORT int beagleSetTransitionMatrices(int instance,
661  const int* matrixIndices,
662  const double* inMatrices,
663  const double* paddedValues,
664  int count);
665 
666 
670 typedef struct {
679 
694 BEAGLE_DLLEXPORT int beagleUpdatePartials(const int instance,
695  const BeagleOperation* operations,
696  int operationCount,
697  int cumulativeScaleIndex);
698 
702 typedef struct {
710  int partition;
713 
727 BEAGLE_DLLEXPORT int beagleUpdatePartialsByPartition(const int instance,
728  const BeagleOperationByPartition* operations,
729  int operationCount);
730 
747 BEAGLE_DLLEXPORT int beagleWaitForPartials(const int instance,
748  const int* destinationPartials,
749  int destinationPartialsCount);
750 
762 BEAGLE_DLLEXPORT int beagleAccumulateScaleFactors(int instance,
763  const int* scaleIndices,
764  int count,
765  int cumulativeScaleIndex);
766 
779 BEAGLE_DLLEXPORT int beagleAccumulateScaleFactorsByPartition(int instance,
780  const int* scaleIndices,
781  int count,
782  int cumulativeScaleIndex,
783  int partitionIndex);
784 
796 BEAGLE_DLLEXPORT int beagleRemoveScaleFactors(int instance,
797  const int* scaleIndices,
798  int count,
799  int cumulativeScaleIndex);
800 
801 
815 BEAGLE_DLLEXPORT int beagleRemoveScaleFactorsByPartition(int instance,
816  const int* scaleIndices,
817  int count,
818  int cumulativeScaleIndex,
819  int partitionIndex);
820 
821 
830 BEAGLE_DLLEXPORT int beagleResetScaleFactors(int instance,
831  int cumulativeScaleIndex);
832 
843 BEAGLE_DLLEXPORT int beagleResetScaleFactorsByPartition(int instance,
844  int cumulativeScaleIndex,
845  int partitionIndex);
846 
847 
857 BEAGLE_DLLEXPORT int beagleCopyScaleFactors(int instance,
858  int destScalingIndex,
859  int srcScalingIndex);
860 
870 BEAGLE_DLLEXPORT int beagleGetScaleFactors(int instance,
871  int srcScalingIndex,
872  double* outScaleFactors);
873 
895 // TODO: only need one state frequency index
896 BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoods(int instance,
897  const int* bufferIndices,
898  const int* categoryWeightsIndices,
899  const int* stateFrequenciesIndices,
900  const int* cumulativeScaleIndices,
901  int count,
902  double* outSumLogLikelihood);
903 
930 BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoodsByPartition(int instance,
931  const int* bufferIndices,
932  const int* categoryWeightsIndices,
933  const int* stateFrequenciesIndices,
934  const int* cumulativeScaleIndices,
935  const int* partitionIndices,
936  int partitionCount,
937  int count,
938  double* outSumLogLikelihoodByPartition,
939  double* outSumLogLikelihood);
940 
968 BEAGLE_DLLEXPORT int beagleCalculateEdgeLogLikelihoods(int instance,
969  const int* parentBufferIndices,
970  const int* childBufferIndices,
971  const int* probabilityIndices,
972  const int* firstDerivativeIndices,
973  const int* secondDerivativeIndices,
974  const int* categoryWeightsIndices,
975  const int* stateFrequenciesIndices,
976  const int* cumulativeScaleIndices,
977  int count,
978  double* outSumLogLikelihood,
979  double* outSumFirstDerivative,
980  double* outSumSecondDerivative);
981 
1018  int instance,
1019  const int* parentBufferIndices,
1020  const int* childBufferIndices,
1021  const int* probabilityIndices,
1022  const int* firstDerivativeIndices,
1023  const int* secondDerivativeIndices,
1024  const int* categoryWeightsIndices,
1025  const int* stateFrequenciesIndices,
1026  const int* cumulativeScaleIndices,
1027  const int* partitionIndices,
1028  int partitionCount,
1029  int count,
1030  double* outSumLogLikelihoodByPartition,
1031  double* outSumLogLikelihood,
1032  double* outSumFirstDerivativeByPartition,
1033  double* outSumFirstDerivative,
1034  double* outSumSecondDerivativeByPartition,
1035  double* outSumSecondDerivative);
1036 
1048 BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods(int instance,
1049  double* outLogLikelihoods);
1050 
1062 BEAGLE_DLLEXPORT int beagleGetSiteDerivatives(int instance,
1063  double* outFirstDerivatives,
1064  double* outSecondDerivatives);
1065 
1066 /* using C calling conventions so that C programs can successfully link the beagle library
1067  * (closing brace)
1068  */
1069 #ifdef __cplusplus
1070 }
1071 #endif
1072 
1073 #endif // __beagle__
BEAGLE_DLLEXPORT const char * beagleGetVersion(void)
Get version.
BEAGLE_DLLEXPORT int beagleSetCategoryRates(int instance, const double *inCategoryRates)
Set the default category rates buffer.
Definition: beagle.h:147
Definition: beagle.h:194
BEAGLE_DLLEXPORT int beagleUpdatePartialsByPartition(const int instance, const BeagleOperationByPartition *operations, int operationCount)
Calculate or queue for calculation partials using a list of partition operations. ...
Definition: beagle.h:168
char * implName
Definition: beagle.h:206
List of hardware resources.
Definition: beagle.h:226
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)
Calculate site log likelihoods at a root node with per partition buffers.
int child1Partials
Definition: beagle.h:674
long requiredFlags
Definition: beagle.h:220
BEAGLE_DLLEXPORT int beagleSetEigenDecomposition(int instance, int eigenIndex, const double *inEigenVectors, const double *inInverseEigenVectors, const double *inEigenValues)
Set an eigen-decomposition buffer.
Definition: beagle.h:130
Definition: beagle.h:182
int destinationPartials
Definition: beagle.h:703
Definition: beagle.h:196
Definition: beagle.h:129
Information about a specific instance.
Definition: beagle.h:202
int destinationScaleRead
Definition: beagle.h:673
char * description
Definition: beagle.h:218
BeagleOpCodes
Operation codes.
Definition: beagle.h:193
Definition: beagle.h:163
Definition: beagle.h:123
long supportFlags
Definition: beagle.h:219
int length
Definition: beagle.h:228
BEAGLE_DLLEXPORT int beagleSetPartials(int instance, int bufferIndex, const double *inPartials)
Set an instance partials buffer.
Definition: beagle.h:175
Definition: beagle.h:195
Definition: beagle.h:176
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)
Calculate site log likelihoods and derivatives along an edge.
BEAGLE_DLLEXPORT int beagleGetTransitionMatrix(int instance, int matrixIndex, double *outMatrix)
Get a finite-time transition probability matrix.
Definition: beagle.h:169
BEAGLE_DLLEXPORT int beagleAccumulateScaleFactorsByPartition(int instance, const int *scaleIndices, int count, int cumulativeScaleIndex, int partitionIndex)
Accumulate scale factors by partition.
Definition: beagle.h:155
Definition: beagle.h:165
Definition: beagle.h:180
BEAGLE_DLLEXPORT int beagleGetPartials(int instance, int bufferIndex, int scaleIndex, double *outPartials)
Get partials from an instance buffer.
int child2Partials
Definition: beagle.h:708
BEAGLE_DLLEXPORT int beagleSetTransitionMatrix(int instance, int matrixIndex, const double *inMatrix, double paddedValue)
Set a finite-time transition probability matrix.
Definition: beagle.h:171
int child1TransitionMatrix
Definition: beagle.h:707
char * implDescription
Definition: beagle.h:208
Definition: beagle.h:149
BEAGLE_DLLEXPORT int beagleFinalize(void)
Finalize the library.
int cumulativeScaleIndex
Definition: beagle.h:711
int child2TransitionMatrix
Definition: beagle.h:709
BEAGLE_DLLEXPORT int beagleSetCategoryRatesWithIndex(int instance, int categoryRatesIndex, const double *inCategoryRates)
Set a category rates buffer.
int child2TransitionMatrix
Definition: beagle.h:677
int child2Partials
Definition: beagle.h:676
BEAGLE_DLLEXPORT int beagleAccumulateScaleFactors(int instance, const int *scaleIndices, int count, int cumulativeScaleIndex)
Accumulate scale factors.
char * resourceName
Definition: beagle.h:204
long flags
Definition: beagle.h:209
Definition: beagle.h:152
Definition: beagle.h:154
int child1TransitionMatrix
Definition: beagle.h:675
Definition: beagle.h:183
Definition: beagle.h:174
Definition: beagle.h:164
BeagleResource * list
Definition: beagle.h:227
int partition
Definition: beagle.h:710
Definition: beagle.h:146
BEAGLE_DLLEXPORT int beagleWaitForPartials(const int instance, const int *destinationPartials, int destinationPartialsCount)
Block until all calculations that write to the specified partials have completed. ...
int destinationScaleWrite
Definition: beagle.h:704
BEAGLE_DLLEXPORT const char * beagleGetCitation(void)
Get citation.
BEAGLE_DLLEXPORT int beagleSetCategoryWeights(int instance, int categoryWeightsIndex, const double *inCategoryWeights)
Set a category weights buffer.
BEAGLE_DLLEXPORT int beagleCopyScaleFactors(int instance, int destScalingIndex, int srcScalingIndex)
Copy scale factors.
int child1Partials
Definition: beagle.h:706
int resourceNumber
Definition: beagle.h:203
Definition: beagle.h:143
Definition: beagle.h:127
BEAGLE_DLLEXPORT int beagleSetPatternPartitions(int instance, int partitionCount, const int *inPatternPartitions)
Set pattern partition assignments.
BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoods(int instance, const int *bufferIndices, const int *categoryWeightsIndices, const int *stateFrequenciesIndices, const int *cumulativeScaleIndices, int count, double *outSumLogLikelihood)
Calculate site log likelihoods at a root node.
Definition: beagle.h:157
BEAGLE_DLLEXPORT int beagleRemoveScaleFactorsByPartition(int instance, const int *scaleIndices, int count, int cumulativeScaleIndex, int partitionIndex)
Remove scale factors by partition.
Definition: beagle.h:121
Definition: beagle.h:179
BEAGLE_DLLEXPORT int beagleUpdateTransitionMatrices(int instance, int eigenIndex, const int *probabilityIndices, const int *firstDerivativeIndices, const int *secondDerivativeIndices, const double *edgeLengths, int count)
Calculate a list of transition probability matrices.
Definition: beagle.h:167
Definition: beagle.h:131
BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods(int instance, double *outLogLikelihoods)
Get site log likelihoods for last beagleCalculateRootLogLikelihoods or beagleCalculateEdgeLogLikeliho...
Definition: beagle.h:160
BEAGLE_DLLEXPORT int beagleUpdatePartials(const int instance, const BeagleOperation *operations, int operationCount, int cumulativeScaleIndex)
Calculate or queue for calculation partials using a list of operations.
BEAGLE_DLLEXPORT int beagleConvolveTransitionMatrices(int instance, const int *firstIndices, const int *secondIndices, const int *resultIndices, int matrixCount)
Set partitions by pattern weight.
Definition: beagle.h:153
BEAGLE_DLLEXPORT int beagleSetTipPartials(int instance, int tipIndex, const double *inPartials)
Set an instance partials buffer for tip node.
int destinationPartials
Definition: beagle.h:671
BEAGLE_DLLEXPORT int beagleFinalizeInstance(int instance)
Finalize this instance.
Definition: beagle.h:124
BEAGLE_DLLEXPORT int beagleSetPatternWeights(int instance, const double *inPatternWeights)
Set pattern weights.
BEAGLE_DLLEXPORT int beagleSetStateFrequencies(int instance, int stateFrequenciesIndex, const double *inStateFrequencies)
Set a state frequency buffer.
A list of integer indices which specify a partial likelihoods operation for a partitioned analysis...
Definition: beagle.h:702
Definition: beagle.h:172
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)
Create a single instance.
Description of a hardware resource.
Definition: beagle.h:216
BEAGLE_DLLEXPORT int beagleResetScaleFactorsByPartition(int instance, int cumulativeScaleIndex, int partitionIndex)
Reset scalefactors by partition.
Definition: beagle.h:122
Definition: beagle.h:173
BEAGLE_DLLEXPORT BeagleResourceList * beagleGetResourceList(void)
Get list of hardware resources.
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)
Calculate multiple site log likelihoods and derivatives along an edge with per partition buffers...
Definition: beagle.h:144
BeagleFlags
Hardware and implementation capability flags.
Definition: beagle.h:142
int destinationScaleRead
Definition: beagle.h:705
BEAGLE_DLLEXPORT int beagleSetTipStates(int instance, int tipIndex, const int *inStates)
Set the compact state representation for tip node.
BEAGLE_DLLEXPORT int beagleGetScaleFactors(int instance, int srcScalingIndex, double *outScaleFactors)
Get scale factors.
BEAGLE_DLLEXPORT int beagleGetSiteDerivatives(int instance, double *outFirstDerivatives, double *outSecondDerivatives)
Get site derivatives for last beagleCalculateEdgeLogLikelihoods call.
BEAGLE_DLLEXPORT int beagleRemoveScaleFactors(int instance, const int *scaleIndices, int count, int cumulativeScaleIndex)
Remove scale factors.
int destinationScaleWrite
Definition: beagle.h:672
Definition: beagle.h:158
char * name
Definition: beagle.h:217
Definition: beagle.h:125
Definition: beagle.h:178
A list of integer indices which specify a partial likelihoods operation.
Definition: beagle.h:670
Definition: beagle.h:161
BEAGLE_DLLEXPORT int beagleResetScaleFactors(int instance, int cumulativeScaleIndex)
Reset scalefactors.
BeagleReturnCodes
Error return codes.
Definition: beagle.h:120
Definition: beagle.h:150
BEAGLE_DLLEXPORT int beagleSetTransitionMatrices(int instance, const int *matrixIndices, const double *inMatrices, const double *paddedValues, int count)
Set multiple transition matrices.
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)
Calculate a list of transition probability matrices with multiple models.