HMSBEAGLE  1.0.0
beagle.h
1 /*
2  * @file beagle.h
3  *
4  * Copyright 2009 Phylogenetic Likelihood Working Group
5  *
6  * This file is part of BEAGLE.
7  *
8  * BEAGLE is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License as
10  * published by the Free Software Foundation, either version 3 of
11  * the License, or (at your option) any later version.
12  *
13  * BEAGLE is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public
19  * License along with BEAGLE. If not, see
20  * <http://www.gnu.org/licenses/>.
21  *
22  * @brief This file documents the API as well as header for the
23  * Broad-platform Evolutionary Analysis General Likelihood Evaluator
24  *
25  * OVERVIEW
26  *
27  * DEFINITION OF KEY CONCEPTS: INSTANCE, BUFFER, etc.
28  *
29  * @author Likelihood API Working Group
30  *
31  * @author Daniel Ayres
32  * @author Peter Beerli
33  * @author Michael Cummings
34  * @author Aaron Darling
35  * @author Mark Holder
36  * @author John Huelsenbeck
37  * @author Paul Lewis
38  * @author Michael Ott
39  * @author Andrew Rambaut
40  * @author Fredrik Ronquist
41  * @author Marc Suchard
42  * @author David Swofford
43  * @author Derrick Zwickl
44  *
45  */
46 
47 #ifndef __beagle__
48 #define __beagle__
49 
50 #include "libhmsbeagle/platform.h"
51 
59 enum BeagleReturnCodes {
60  BEAGLE_SUCCESS = 0,
61  BEAGLE_ERROR_GENERAL = -1,
62  BEAGLE_ERROR_OUT_OF_MEMORY = -2,
63  BEAGLE_ERROR_UNIDENTIFIED_EXCEPTION = -3,
64  BEAGLE_ERROR_UNINITIALIZED_INSTANCE = -4,
66  BEAGLE_ERROR_OUT_OF_RANGE = -5,
68  BEAGLE_ERROR_NO_RESOURCE = -6,
69  BEAGLE_ERROR_NO_IMPLEMENTATION = -7,
70  BEAGLE_ERROR_FLOATING_POINT = -8
71 };
72 
81 enum BeagleFlags {
82  BEAGLE_FLAG_PRECISION_SINGLE = 1 << 0,
83  BEAGLE_FLAG_PRECISION_DOUBLE = 1 << 1,
85  BEAGLE_FLAG_COMPUTATION_SYNCH = 1 << 2,
86  BEAGLE_FLAG_COMPUTATION_ASYNCH = 1 << 3,
88  BEAGLE_FLAG_EIGEN_REAL = 1 << 4,
89  BEAGLE_FLAG_EIGEN_COMPLEX = 1 << 5,
91  BEAGLE_FLAG_SCALING_MANUAL = 1 << 6,
92  BEAGLE_FLAG_SCALING_AUTO = 1 << 7,
93  BEAGLE_FLAG_SCALING_ALWAYS = 1 << 8,
94  BEAGLE_FLAG_SCALING_DYNAMIC = 1 << 19,
96  BEAGLE_FLAG_SCALERS_RAW = 1 << 9,
97  BEAGLE_FLAG_SCALERS_LOG = 1 << 10,
99  BEAGLE_FLAG_INVEVEC_STANDARD = 1 << 20,
100  BEAGLE_FLAG_INVEVEC_TRANSPOSED = 1 << 21,
102  BEAGLE_FLAG_VECTOR_SSE = 1 << 11,
103  BEAGLE_FLAG_VECTOR_NONE = 1 << 12,
105  BEAGLE_FLAG_THREADING_OPENMP = 1 << 13,
106  BEAGLE_FLAG_THREADING_NONE = 1 << 14,
108  BEAGLE_FLAG_PROCESSOR_CPU = 1 << 15,
109  BEAGLE_FLAG_PROCESSOR_GPU = 1 << 16,
110  BEAGLE_FLAG_PROCESSOR_FPGA = 1 << 17,
111  BEAGLE_FLAG_PROCESSOR_CELL = 1 << 18
112 };
113 
121 enum BeagleOpCodes {
122  BEAGLE_OP_COUNT = 7,
123  BEAGLE_OP_NONE = -1
124 };
125 
129 typedef struct {
131  char* resourceName;
133  char* implName;
136  long flags;
139 
143 typedef struct {
144  char* name;
145  char* description;
149 
153 typedef struct {
155  int length;
157 
158 /* using C calling conventions so that C programs can successfully link the beagle library
159  * (brace is closed at the end of this file)
160  */
161 #ifdef __cplusplus
162 extern "C" {
163 #endif
164 
172 BEAGLE_DLLEXPORT BeagleResourceList* beagleGetResourceList(void);
173 
203 // TODO: if setting your own matrices, might not need eigen buffers allocated, but still need
204 // category weight and state frequency buffers
205 BEAGLE_DLLEXPORT int beagleCreateInstance(int tipCount,
206  int partialsBufferCount,
207  int compactBufferCount,
208  int stateCount,
209  int patternCount,
210  int eigenBufferCount,
211  int matrixBufferCount,
212  int categoryCount,
213  int scaleBufferCount,
214  int* resourceList,
215  int resourceCount,
216  long preferenceFlags,
217  long requirementFlags,
218  BeagleInstanceDetails* returnInfo);
219 
229 BEAGLE_DLLEXPORT int beagleFinalizeInstance(int instance);
230 
239 BEAGLE_DLLEXPORT int beagleFinalize(void);
240 
255 BEAGLE_DLLEXPORT int beagleSetTipStates(int instance,
256  int tipIndex,
257  const int* inStates);
258 
273 BEAGLE_DLLEXPORT int beagleSetTipPartials(int instance,
274  int tipIndex,
275  const double* inPartials);
276 
289 BEAGLE_DLLEXPORT int beagleSetPartials(int instance,
290  int bufferIndex,
291  const double* inPartials);
292 
306 BEAGLE_DLLEXPORT int beagleGetPartials(int instance,
307  int bufferIndex,
308  int scaleIndex,
309  double* outPartials);
310 
325 BEAGLE_DLLEXPORT int beagleSetEigenDecomposition(int instance,
326  int eigenIndex,
327  const double* inEigenVectors,
328  const double* inInverseEigenVectors,
329  const double* inEigenValues);
330 
342 BEAGLE_DLLEXPORT int beagleSetStateFrequencies(int instance,
343  int stateFrequenciesIndex,
344  const double* inStateFrequencies);
345 
357 BEAGLE_DLLEXPORT int beagleSetCategoryWeights(int instance,
358  int categoryWeightsIndex,
359  const double* inCategoryWeights);
360 
371 BEAGLE_DLLEXPORT int beagleSetCategoryRates(int instance,
372  const double* inCategoryRates);
383 BEAGLE_DLLEXPORT int beagleSetPatternWeights(int instance,
384  const double* inPatternWeights);
385 
405 BEAGLE_DLLEXPORT int beagleUpdateTransitionMatrices(int instance,
406  int eigenIndex,
407  const int* probabilityIndices,
408  const int* firstDerivativeIndices,
409  const int* secondDerivativeIndices,
410  const double* edgeLengths,
411  int count);
412 
428 BEAGLE_DLLEXPORT int beagleSetTransitionMatrix(int instance,
429  int matrixIndex,
430  const double* inMatrix,
431  double paddedValue);
432 
446 BEAGLE_DLLEXPORT int beagleGetTransitionMatrix(int instance,
447  int matrixIndex,
448  double* outMatrix);
449 
466 BEAGLE_DLLEXPORT int beagleSetTransitionMatrices(int instance,
467  const int* matrixIndices,
468  const double* inMatrices,
469  const double* paddedValues,
470  int count);
471 
472 typedef struct {
473  int destinationPartials;
474  int destinationScaleWrite;
475  int destinationScaleRead;
476  int child1Partials;
477  int child1TransitionMatrix;
478  int child2Partials;
479  int child2TransitionMatrix;
481 
505 BEAGLE_DLLEXPORT int beagleUpdatePartials(const int instance,
506  const BeagleOperation* operations,
507  int operationCount,
508  int cumulativeScaleIndex);
509 
526 BEAGLE_DLLEXPORT int beagleWaitForPartials(const int instance,
527  const int* destinationPartials,
528  int destinationPartialsCount);
529 
541 BEAGLE_DLLEXPORT int beagleAccumulateScaleFactors(int instance,
542  const int* scaleIndices,
543  int count,
544  int cumulativeScaleIndex);
545 
557 BEAGLE_DLLEXPORT int beagleRemoveScaleFactors(int instance,
558  const int* scaleIndices,
559  int count,
560  int cumulativeScaleIndex);
561 
570 BEAGLE_DLLEXPORT int beagleResetScaleFactors(int instance,
571  int cumulativeScaleIndex);
572 
582 BEAGLE_DLLEXPORT int beagleCopyScaleFactors(int instance,
583  int destScalingIndex,
584  int srcScalingIndex);
585 
607 // TODO: only need one state frequency index
608 BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoods(int instance,
609  const int* bufferIndices,
610  const int* categoryWeightsIndices,
611  const int* stateFrequenciesIndices,
612  const int* cumulativeScaleIndices,
613  int count,
614  double* outSumLogLikelihood);
615 
643 BEAGLE_DLLEXPORT int beagleCalculateEdgeLogLikelihoods(int instance,
644  const int* parentBufferIndices,
645  const int* childBufferIndices,
646  const int* probabilityIndices,
647  const int* firstDerivativeIndices,
648  const int* secondDerivativeIndices,
649  const int* categoryWeightsIndices,
650  const int* stateFrequenciesIndices,
651  const int* cumulativeScaleIndices,
652  int count,
653  double* outSumLogLikelihood,
654  double* outSumFirstDerivative,
655  double* outSumSecondDerivative);
656 
668 BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods(int instance,
669  double* outLogLikelihoods);
670 
682 BEAGLE_DLLEXPORT int beagleGetSiteDerivatives(int instance,
683  double* outFirstDerivatives,
684  double* outSecondDerivatives);
685 
686 /* using C calling conventions so that C programs can successfully link the beagle library
687  * (closing brace)
688  */
689 #ifdef __cplusplus
690 }
691 #endif
692 
693 #endif // __beagle__