libhmsbeagle/beagle.h(3)

📦

version 3.1.2 · 3 versions

3.1.2 · ubuntu jammy (latest)
3.1.2 · ubuntu noble
3.1.2 · debian bookworm

✨ okay bestie, buckle up ✨ this is the libhmsbeagle/beagle.h(3) page from the BEAGLE manual. It's giving header energy, it's giving API docs, and it's literally the Broad-platform Evolutionary Analysis General Likelihood Evaluator. No cap, this file is the main character of the library. 💅

💖 NAME 💖

libhmsbeagle/beagle.h — this file documents the API as well as the header for the Broad-platform Evolutionary Analysis General Likelihood Evaluator. It's the blueprint, the vibe, the whole package. 🫶

✨ SYNOPSIS ✨

First thing you do, bestie, is include the platform header. Like this, exactly:

#include 'libhmsbeagle/platform.h'

yes, it's single quotes in the manpage. I am not changing it. periodt. 💀

🎀 Classes 🎀

These are the structs chillin' in this header. Each one is a little data moment with its own job. Obsessed.

struct BeagleInstanceDetails — information about a specific instance. It's giving "tell me about this one instance" energy. 💖
struct BeagleResource — a description of a hardware resource. Hardware lore, but make it a struct. ✨
struct BeagleResourceList — a list of hardware resources. Simple, effective, slay. 🎀
struct BeagleBenchmarkedResource — a description of a benchmarked hardware resource. It went through the benchmark vibe check. 🦋
struct BeagleBenchmarkedResourceList — an ordered list of benchmarked hardware resources, from fastest to slowest. Speed ranking, periodt. 🏁
struct BeagleOperation — a list of integer indices which specify a partial likelihoods operation. Math girlies, rise. 🔥
struct BeagleOperationByPartition — a list of integer indices which specify a partial likelihoods operation for a partitioned analysis. Same energy, but partitioned. 💅

🌸 Enumerations 🌸

Enums, bestie. Named constants, but make it fashion. 🌈

`enum BeagleReturnCodes`

Error return codes. When something goes sideways, one of these babies comes back to tell you what's up. 😭

       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`

Hardware and implementation capability flags. This is the big one, bestie. It's giving "what can this machine even do?" energy. 🦋

       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 BeagleBenchmarkFlags`

Benchmarking mode flags for resource performance evaluation with beagleGetOrderedResourceList. Basically: how hard do we want to vibe-check the hardware? 💅

       enum BeagleBenchmarkFlags { BEAGLE_BENCHFLAG_SCALING_NONE = 1 << 0,
           BEAGLE_BENCHFLAG_SCALING_ALWAYS = 1 << 1,
           BEAGLE_BENCHFLAG_SCALING_DYNAMIC = 1 << 2 }

`enum BeagleOpCodes`

Operation codes. Short, sweet, and they keep the partial likelihoods ops in check. ✨

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

✨ FUNCTIONS ✨

okay bestie, here's the whole function lineup 💖 every signature is copied exactly, no cap, and every description is giving the same facts with extra sparkle. periodt.

beagleGetVersion — Get version. Like, literally grab the version info, bestie. 💖

       BEAGLE_DLLEXPORT const char * beagleGetVersion (void)

beagleGetCitation — Get citation. The citation, bestie, so you can cite it correctly. ✨

       BEAGLE_DLLEXPORT const char * beagleGetCitation (void)

beagleGetResourceList — Get list of hardware resources. It's giving inventory energy, fr fr. 🖥️✨

       BEAGLE_DLLEXPORT BeagleResourceList * beagleGetResourceList (void)

beagleGetBenchmarkedResourceList — Get a benchmarked list of hardware resources for the given analysis parameters. So many params, bestie, but it's all there. 🔥

       BEAGLE_DLLEXPORT BeagleBenchmarkedResourceList *
           beagleGetBenchmarkedResourceList (int tipCount, int
           compactBufferCount, int stateCount, int patternCount, int
           categoryCount, int *resourceList, int resourceCount, long
           preferenceFlags, long requirementFlags, int eigenModelCount, int
           partitionCount, int calculateDerivatives, long benchmarkFlags)

beagleCreateInstance — Create a single instance. One instance, coming right up. 👑

       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)

beagleFinalizeInstance — Finalize this instance. Wrap it up, bestie. 🎀

       BEAGLE_DLLEXPORT int beagleFinalizeInstance (int instance)

beagleFinalize — Finalize the library. Whole library, done. 💅

       BEAGLE_DLLEXPORT int beagleFinalize (void)

beagleSetCPUThreadCount — Set number of threads for native CPU implementation. Thread count go brrr. 🧵✨

       BEAGLE_DLLEXPORT int beagleSetCPUThreadCount (int instance, int
           threadCount)

beagleSetTipStates — Set the compact state representation for tip node. Tip node states, compact style. 🦋

       BEAGLE_DLLEXPORT int beagleSetTipStates (int instance, int tipIndex,
           const int *inStates)

beagleSetTipPartials — Set an instance partials buffer for tip node. Partials for the tip node, got it. 🌸

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

beagleSetPartials — Set an instance partials buffer. Just a regular partials buffer, bestie. ✨

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

beagleGetPartials — Get partials from an instance buffer. Retrieve those partials. 💖

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

beagleSetEigenDecomposition — Set an eigen-decomposition buffer. Eigen-decomp, set. 🧚

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

beagleSetStateFrequencies — Set a state frequency buffer. Frequencies, set. 💜

       BEAGLE_DLLEXPORT int beagleSetStateFrequencies (int instance, int
           stateFrequenciesIndex, const double *inStateFrequencies)

beagleSetCategoryWeights — Set a category weights buffer. Weights, set. 🎀

       BEAGLE_DLLEXPORT int beagleSetCategoryWeights (int instance, int
           categoryWeightsIndex, const double *inCategoryWeights)

beagleSetCategoryRates — Set the default category rates buffer. Default rates, set. ✨

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

beagleSetCategoryRatesWithIndex — Set a category rates buffer. Rates, set. 🔥

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

beagleSetPatternWeights — Set pattern weights. Weights for patterns, periodt. 💅

       BEAGLE_DLLEXPORT int beagleSetPatternWeights (int instance, const double
           *inPatternWeights)

beagleSetPatternPartitions — Set pattern partition assignments. Assign those partitions, bestie. 🦋

       BEAGLE_DLLEXPORT int beagleSetPatternPartitions (int instance, int
           partitionCount, const int *inPatternPartitions)

beagleConvolveTransitionMatrices — Set partitions by pattern weight. Yes, that's what it says, bestie. 🌈

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

beagleUpdateTransitionMatrices — Calculate a list of transition probability matrices. Matrices, calculated. 🔥

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

beagleUpdateTransitionMatricesWithMultipleModels — Calculate a list of transition probability matrices with multiple models. Multiple models, multiple 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)

beagleSetTransitionMatrix — Set a finite-time transition probability matrix. One matrix, set. 💖

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

beagleGetTransitionMatrix — Get a finite-time transition probability matrix. One matrix, got it. ✨

       BEAGLE_DLLEXPORT int beagleGetTransitionMatrix (int instance, int
           matrixIndex, double *outMatrix)

beagleSetTransitionMatrices — Set multiple transition matrices. Many matrices, set. 🎀

       BEAGLE_DLLEXPORT int beagleSetTransitionMatrices (int instance, const
           int *matrixIndices, const double *inMatrices, const double
           *paddedValues, int count)

beagleUpdatePartials — Calculate or queue for calculation partials using a list of operations. Queue it up or calculate it, your call. 🧚

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

beagleUpdatePartialsByPartition — Calculate or queue for calculation partials using a list of partition operations. Partition operations, same energy. 💜

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

beagleWaitForPartials — Block until all calculations that write to the specified partials have completed. Blocking, bestie, like waiting for your boba order. 🧋

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

beagleAccumulateScaleFactors — Accumulate scale factors. Stack 'em up. 📚

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

beagleAccumulateScaleFactorsByPartition — Accumulate scale factors by partition. Per partition, stack 'em. 🗂️

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

beagleRemoveScaleFactors — Remove scale factors. Yeet those scale factors. 💀

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

beagleRemoveScaleFactorsByPartition — Remove scale factors by partition. Per partition, yeet. 🙈

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

beagleResetScaleFactors — Reset scalefactors. Reset, no cap. 🔄

       BEAGLE_DLLEXPORT int beagleResetScaleFactors (int instance, int
           cumulativeScaleIndex)

beagleResetScaleFactorsByPartition — Reset scalefactors by partition. Per partition reset. 🔁

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

beagleCopyScaleFactors — Copy scale factors. Copy-paste energy. 📋

       BEAGLE_DLLEXPORT int beagleCopyScaleFactors (int instance, int
           destScalingIndex, int srcScalingIndex)

beagleGetScaleFactors — Get scale factors. Retrieve those scale factors. 💖

       BEAGLE_DLLEXPORT int beagleGetScaleFactors (int instance, int
           srcScalingIndex, double *outScaleFactors)

beagleCalculateRootLogLikelihoods — Calculate site log likelihoods at a root node. Root node log likelihoods, calculated. 🌳

       BEAGLE_DLLEXPORT int beagleCalculateRootLogLikelihoods (int instance,
           const int *bufferIndices, const int *categoryWeightsIndices, const
           int *stateFrequenciesIndices, const int *cumulativeScaleIndices, int
           count, double *outSumLogLikelihood)

beagleCalculateRootLogLikelihoodsByPartition — Calculate site log likelihoods at a root node with per partition buffers. Per partition buffers, root node. 🗂️

       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)

beagleCalculateEdgeLogLikelihoods — Calculate site log likelihoods and derivatives along an edge. Edge likelihoods and derivatives, slay. 🔥

       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)

beagleCalculateEdgeLogLikelihoodsByPartition — Calculate multiple site log likelihoods and derivatives along an edge with per partition buffers. Multiple sites, per partition buffers. 🌈

       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)

beagleGetLogLikelihood — Returns log likelihood sum and subsequent to an asynchronous integration call. Async call, then get the sum. ⏳

       BEAGLE_DLLEXPORT int beagleGetLogLikelihood (int instance, double
           *outSumLogLikelihood)

beagleGetDerivatives — Returns derivative sums subsequent to an asynchronous integration call. Async call, then derivative sums. 📈

       BEAGLE_DLLEXPORT int beagleGetDerivatives (int instance, double
           *outSumFirstDerivative, double *outSumSecondDerivative)

beagleGetSiteLogLikelihoods — Get site log likelihoods for last beagleCalculateRootLogLikelihoods or beagleCalculateEdgeLogLikelihoods call. For the last call, get site log likelihoods. 💅

       BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods (int instance, double
           *outLogLikelihoods)

beagleGetSiteDerivatives — Get site derivatives for last beagleCalculateEdgeLogLikelihoods call. For the last edge call, get site derivatives. ✨

       BEAGLE_DLLEXPORT int beagleGetSiteDerivatives (int instance, double
           *outFirstDerivatives, double *outSecondDerivatives)

Detailed Description 💖

okay so this file is the documentation for the API and the header of the Broad-platform Evolutionary Analysis General Likelihood Evaluator. iconic behavior honestly.

This file is part of BEAGLE.

BEAGLE is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

BEAGLE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with BEAGLE. If not, see <http://www.gnu.org/licenses/>.

🔑 KEY CONCEPTS 🔑

bestie, the whole point of BEAGLE's speed is fine-scale parallelization while keeping data transfer and memory copy overhead as tiny as possible. and the way they do that?? the library literally has no concept of a data structure for a tree, even though phylogenetics is literally the whole reason it exists. wild, right? 💀

instead, BEAGLE acts directly on flexibly indexed data storage — called buffers — for observed character states and partial likelihoods. your client program sets up the input buffers to reflect the data, then calculates the likelihood of a particular phylogeny by invoking likelihood calculations on the appropriate input and output buffers in the correct order. no cap.

and because of that design simplicity, the library can support so many different tree inference algorithms and likelihood calculation on a whole variety of models. like:

arbitrary numbers of states can be used
nonreversible substitution matrices via complex eigen decompositions
mixture models with multiple rate categories and/or multiple eigen decompositions

finally — and this is the slay part — BEAGLE application programming interface (API) calls can be asynchronous, which lets the calling program implement other coarse-scale parallelization schemes, like evaluating independent genes or running concurrent Markov chains. main character energy fr fr. 👑

🛠️ USAGE 🛠️

okay so to actually use this thing, a client program first creates an instance of BEAGLE by calling beagleCreateInstance. and listen — multiple instances per client are possible and encouraged. yes bestie, go off. all the other functions get called with a reference to this instance.

the client program can optionally request that an instance run on certain hardware (like a GPU 👀) or have particular features (like double-precision math ✨).

next up, the client program must specify the data dimensions and specify key aspects of the phylogenetic model. then character state data get loaded, and they can be either discrete observed states or partial likelihoods for ambiguous characters. the observed data are usually unchanging and loaded only once at the start — that's to minimize memory copy overhead, iykyk. the character data can be compressed into unique "site patterns" plus associated weights for each one.

then the parameters of the substitution process get specified, including:

the equilibrium state frequencies
the rates for one or more substitution rate categories, and their weights
and finally, the eigen decomposition for the substitution process

so to calculate the likelihood of a particular tree, the client program then specifies a series of integration operations that correspond to steps in Felsenstein's algorithm. 🦋

finite-time transition probabilities for each edge are loaded directly if you're considering a nondiagonalizable model, or else calculated in parallel from the eigen decomposition and the edge lengths specified. all of this happens inside BEAGLE's memory space, to keep data transfers minimal. periodt.

then a single function call requests one or more integration operations to calculate partial likelihoods over some or all nodes. the operations are performed in the order they are provided, typically dictated by a postorder traversal of the tree topology. the client only needs to specify nodes for which the partial likelihoods need updating — but tracking those dependencies?? that's on the calling software, bestie. 🙈

the final step in evaluating the phylogenetic model is done with an API call that yields a single log likelihood for the model given the data. chef's kiss. 💅

aspects of the BEAGLE API design support both maximum likelihood (ML) and Bayesian phylogenetic tree inference. for ML inference, API calls can calculate first and second derivatives of the likelihood with respect to the lengths of edges (branches). in both cases, BEAGLE provides the ability to cache and reuse previously computed partial likelihood results, which can yield a tremendous speedup over recomputing the entire likelihood every time a new phylogenetic model is evaluated. obsessed.

Author 👑

Likelihood API Working Group

Daniel Ayres
Peter Beerli
Michael Cummings
Aaron Darling
Mark Holder
John Huelsenbeck
Paul Lewis
Michael Ott
Andrew Rambaut
Fredrik Ronquist
Marc Suchard
David Swofford
Derrick Zwickl

📚 Enumeration Type Documentation 📚

enum BeagleBenchmarkFlags

Benchmarking mode flags for resource performance evaluation with beagleGetOrderedResourceList.

this one enumerates all possible benchmarking mode flags. each mode is a bit in a long. 💫

Enumerator

BEAGLE_BENCHFLAG_SCALING_NONE — no scaling
BEAGLE_BENCHFLAG_SCALING_ALWAYS — scale at every iteration
BEAGLE_BENCHFLAG_SCALING_DYNAMIC — scale every fixed number of iterations, or when a numerical error occurs, and re-use scale factors for subsequent iterations

enum BeagleFlags

Hardware and implementation capability flags.

this one enumerates all possible hardware and implementation capability flags. each capability is a bit in a long. ⭐

Enumerator

BEAGLE_FLAG_PRECISION_SINGLE — single precision computation
BEAGLE_FLAG_PRECISION_DOUBLE — double precision computation
BEAGLE_FLAG_COMPUTATION_SYNCH — synchronous computation (blocking)
BEAGLE_FLAG_COMPUTATION_ASYNCH — asynchronous computation (non-blocking)
BEAGLE_FLAG_EIGEN_REAL — real eigenvalue computation
BEAGLE_FLAG_EIGEN_COMPLEX — complex eigenvalue computation
BEAGLE_FLAG_SCALING_MANUAL — manual scaling
BEAGLE_FLAG_SCALING_AUTO — auto-scaling on (deprecated, may not work correctly)
BEAGLE_FLAG_SCALING_ALWAYS — scale at every updatePartials (deprecated, may not work correctly)
BEAGLE_FLAG_SCALING_DYNAMIC — manual scaling with dynamic checking (deprecated, may not work correctly)
BEAGLE_FLAG_SCALERS_RAW — save raw scalers
BEAGLE_FLAG_SCALERS_LOG — save log scalers
BEAGLE_FLAG_INVEVEC_STANDARD — inverse eigen vectors passed to BEAGLE have not been transposed
BEAGLE_FLAG_INVEVEC_TRANSPOSED — inverse eigen vectors passed to BEAGLE have been transposed
BEAGLE_FLAG_VECTOR_SSE — SSE computation
BEAGLE_FLAG_VECTOR_AVX — AVX computation
BEAGLE_FLAG_VECTOR_NONE — no vector computation
BEAGLE_FLAG_THREADING_CPP — C++11 threading
BEAGLE_FLAG_THREADING_OPENMP — OpenMP threading
BEAGLE_FLAG_THREADING_NONE — no threading (default)
BEAGLE_FLAG_PROCESSOR_CPU — use CPU as main processor
BEAGLE_FLAG_PROCESSOR_GPU — use GPU as main processor
BEAGLE_FLAG_PROCESSOR_FPGA — use FPGA as main processor
BEAGLE_FLAG_PROCESSOR_CELL — use Cell as main processor
BEAGLE_FLAG_PROCESSOR_PHI — use Intel Phi as main processor
BEAGLE_FLAG_PROCESSOR_OTHER — use other type of processor
BEAGLE_FLAG_FRAMEWORK_CUDA — use CUDA implementation with GPU resources
BEAGLE_FLAG_FRAMEWORK_OPENCL — use OpenCL implementation with GPU resources
BEAGLE_FLAG_FRAMEWORK_CPU — use CPU implementation
BEAGLE_FLAG_PARALLELOPS_STREAMS — operations in updatePartials may be assigned to separate device streams
BEAGLE_FLAG_PARALLELOPS_GRID — operations in updatePartials may be folded into a single kernel launch (necessary for partitions; typically performs better for problems with fewer pattern sites)

enum BeagleOpCodes

Operation codes.

this one enumerates all possible BEAGLE operation codes. 🎀

Enumerator

BEAGLE_OP_COUNT — total number of integers per beagleUpdatePartials operation
BEAGLE_PARTITION_OP_COUNT — total number of integers per beagleUpdatePartialsByPartition operation
BEAGLE_OP_NONE — specify no use for indexed buffer

enum BeagleReturnCodes

Error return codes.

this one enumerates all possible BEAGLE return codes. and heads up bestie: error codes are always negative. 😭

Enumerator

BEAGLE_SUCCESS — success 🎉
BEAGLE_ERROR_GENERAL — unspecified error
BEAGLE_ERROR_OUT_OF_MEMORY — not enough memory could be allocated
BEAGLE_ERROR_UNIDENTIFIED_EXCEPTION — unspecified exception
BEAGLE_ERROR_UNINITIALIZED_INSTANCE — the instance index is out of range, or the instance has not been created
BEAGLE_ERROR_OUT_OF_RANGE — one of the indices specified exceeded the range of the array
BEAGLE_ERROR_NO_RESOURCE — no resource matches requirements
BEAGLE_ERROR_NO_IMPLEMENTATION — no implementation matches requirements
BEAGLE_ERROR_FLOATING_POINT — floating-point error (e.g., NaN)

🧚 Function Documentation 🧚

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

Accumulate scale factors. 💫

this function adds (log) scale factors from a list of scaleBuffers to a cumulative scale buffer. it's used to calculate the marginal scaling at a specific node for each site.

Parameters

instance — instance number (input)
scaleIndices — list of scaleBuffers to add (input)
count — number of scaleBuffers in list (input)
cumulativeScaleIndex — index number of scaleBuffer to accumulate factors into (input)

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

Accumulate scale factors by partition. 🌸

this function adds (log) scale factors from a list of scaleBuffers to a cumulative scale buffer. it's used to calculate the marginal scaling at a specific node for each site.

Parameters

okay so real quick, here's the parameter rundown for the function we were just talking about:

instance — Instance number (input)
scaleIndices — List of scaleBuffers to add (input)
count — Number of scaleBuffers in list (input)
cumulativeScaleIndex — Index number of scaleBuffer to accumulate factors into (input)
partitionIndex — Index of partition to accumulate into (input)

`beagleCalculateEdgeLogLikelihoods` 💖

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. Bestie, this one integrates a list of partials at a parent and child node with respect to a set of partials-weights and state frequencies, and hands you back the log likelihood plus the first and second derivative sums. it's giving math girlboss energy ngl ✨

Parameters

instance — Instance number (input)
parentBufferIndices — List of indices of parent partialsBuffers (input)
childBufferIndices — List of indices of child partialsBuffers (input)
probabilityIndices — List indices of transition probability matrices for this edge (input)
firstDerivativeIndices — List indices of first derivative matrices (input)
secondDerivativeIndices — List indices of second derivative matrices (input)
categoryWeightsIndices — List of weights to apply to each partialsBuffer (input)
stateFrequenciesIndices — List of state frequencies for each partialsBuffer (input). There should be one set for each of parentBufferIndices
cumulativeScaleIndices — List of scaleBuffers containing accumulated factors to apply to each partialsBuffer (input). There should be one index for each of parentBufferIndices
count — Number of partialsBuffers (input)
outSumLogLikelihood — Pointer to destination for resulting log likelihood (output)
outSumFirstDerivative — Pointer to destination for resulting first derivative (output)
outSumSecondDerivative — Pointer to destination for resulting second derivative (output)

Returns

error code 💅

`beagleCalculateEdgeLogLikelihoodsByPartition` 🦋

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. same vibe as the last one, except it integrates lists of partials at a parent and child node w.r.t. a set of partials-weights and state frequencies, and returns the log likelihood and first and second derivative sums — but now with partition flavor 🌸

Parameters

instance — Instance number (input)
parentBufferIndices — List of indices of parent partialsBuffers (input)
childBufferIndices — List of indices of child partialsBuffers (input)
probabilityIndices — List indices of transition probability matrices for this edge (input)
firstDerivativeIndices — List indices of first derivative matrices (input)
secondDerivativeIndices — List indices of second derivative matrices (input)
categoryWeightsIndices — List of weights to apply to each partialsBuffer (input)
stateFrequenciesIndices — List of state frequencies for each partialsBuffer (input). There should be one set for each of parentBufferIndices
cumulativeScaleIndices — List of scaleBuffers containing accumulated factors to apply to each partialsBuffer (input). There should be one index for each of parentBufferIndices
partitionIndices — List of partition indices indicating which sites in each partialsBuffer should be used (input). There should be one index for each of parentBufferIndices
partitionCount — Number of distinct partitionIndices (input)
count — Number of sets of partitions to integrate across (input)
outSumLogLikelihoodByPartition — Pointer to destination for resulting log likelihoods for each partition (output)
outSumLogLikelihood — Pointer to destination for resulting log likelihood (output)
outSumFirstDerivativeByPartition — Pointer to destination for resulting first derivative for each partition (output)
outSumFirstDerivative — Pointer to destination for resulting first derivative (output)
outSumSecondDerivativeByPartition — Pointer to destination for resulting second derivative for each partition (output)
outSumSecondDerivative — Pointer to destination for resulting second derivative (output)

Returns

error code 💅

`beagleCalculateRootLogLikelihoods` 🌿

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. this one integrates a list of partials at a node with respect to a set of partials-weights and state frequencies, and gives you the log likelihood sum. root node said main character fr fr 👑

Parameters

instance — Instance number (input)
bufferIndices — List of partialsBuffer indices to integrate (input)
categoryWeightsIndices — List of weights to apply to each partialsBuffer (input). There should be one categoryCount sized set for each of parentBufferIndices
stateFrequenciesIndices — List of state frequencies for each partialsBuffer (input). There should be one set for each of parentBufferIndices
cumulativeScaleIndices — List of scaleBuffers containing accumulated factors to apply to each partialsBuffer (input). There should be one index for each of parentBufferIndices
count — Number of partialsBuffer to integrate (input)
outSumLogLikelihood — Pointer to destination for resulting log likelihood (output)

Returns

error code 💅

`beagleCalculateRootLogLikelihoodsByPartition` 🫶

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. integrates lists of partials at a node w.r.t. a set of partials-weights and state frequencies, and returns the log likelihood sums — partitions edition 💖

Parameters

instance — Instance number (input)
bufferIndices — List of partialsBuffer indices to integrate (input)
categoryWeightsIndices — List of weights to apply to each partialsBuffer (input). There should be one categoryCount sized set for each of bufferIndices
stateFrequenciesIndices — List of state frequencies for each partialsBuffer (input). There should be one set for each of bufferIndices
cumulativeScaleIndices — List of scaleBuffers containing accumulated factors to apply to each partialsBuffer (input). There should be one index for each of bufferIndices
partitionIndices — List of partition indices indicating which sites in each partialsBuffer should be used (input). There should be one index for each of bufferIndices
partitionCount — Number of distinct partitionIndices (input)
count — Number of sets of partitions to integrate across (input)
outSumLogLikelihoodByPartition — Pointer to destination for resulting log likelihoods for each partition (output)
outSumLogLikelihood — Pointer to destination for resulting log likelihood (output)

Returns

error code 💅

`beagleConvolveTransitionMatrices` ⭐

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

Set partitions by pattern weight. okay so this function defines partitions by setting their vectors of pattern-weights for an instance. heads up bestie: it should be called after beagleSetTipPartials or beagleSetTipStates. don't skip that step, it's giving order matters 🙈

Parameters

instance — Instance number (input)
inPartitionPatternWeights — partitionCount arrays, each containing patternCount pattern weights (input)
partitionCount — Number of partitions (input)

Returns

error code 💅

Convolve lists of transition probability matrices

This function convolves two lists of transition probability matrices. (yes, the description above is doing its own thing, we don't question the manpage, we just report it 💀)

Parameters

instance — Instance number (input)
firstIndices — List of indices of the first transition probability matrices to convolve (input)
secondIndices — List of indices of the second transition probability matrices to convolve (input)
resultIndices — List of indices of resulting transition probability matrices (input)
matrixCount — Length of lists

`beagleCopyScaleFactors` 🎀

BEAGLE_DLLEXPORT int beagleCopyScaleFactors (int instance, int destScalingIndex, int srcScalingIndex)

Copy scale factors. literally just copies scale factors from one buffer to another. no thoughts, just vibes ✨

Parameters

instance — Instance number (input)
destScalingIndex — Destination scaleBuffer (input)
srcScalingIndex — Source scaleBuffer (input)

`beagleCreateInstance` 👑

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. this function creates a single instance of the BEAGLE library, and bestie you can call it multiple times to create multiple data partition instances — each one returning a unique identifier 🌈

okay bestie, so the function that hands you back the unique instance id — here's the full tea on what you pass in: ✨

tipCount — Number of tip data elements (input) 🦋
partialsBufferCount — Number of partials buffers to create (input) 🎀
compactBufferCount — Number of compact state representation buffers to create (input) 💖
stateCount — Number of states in the continuous-time Markov chain (input) 🌸
patternCount — Number of site patterns to be handled by the instance (input) 💅
eigenBufferCount — Number of rate matrix eigen-decomposition, category weight, category rates, and state frequency buffers to allocate (input) 👑
matrixBufferCount — Number of transition probability matrix buffers (input) 🔥
categoryCount — Number of rate categories (input) 🌈
scaleBufferCount — Number of scale buffers to create, ignored for auto scale or always scale (input) ⭐
resourceList — List of potential resources on which this instance is allowed (input, NULL implies no restriction) 💀
resourceCount — Length of resourceList list (input) 🍓
preferenceFlags — Bit-flags indicating preferred implementation characteristics, see BeagleFlags (input) 🧚
requirementFlags — Bit-flags indicating required implementation characteristics, see BeagleFlags (input) 💜
returnInfo — Pointer to return implementation and resource details 🫶

Returns: the unique instance identifier (<0 if failed, see BeagleReturnCodes) 😭

`beagleFinalize` — the big goodbye 💅

BEAGLE_DLLEXPORT int beagleFinalize (void)

Finalize the library. This function finalizes the library and releases all allocated memory. This function is automatically called under GNU C via attribute ((destructor)).

Returns: error code

`beagleFinalizeInstance` — one instance, peace out ✌️

BEAGLE_DLLEXPORT int beagleFinalizeInstance (int instance)

Finalize this instance. This function finalizes the instance by releasing allocated memory

Parameters:

instance — Instance number

Returns: error code

`beagleGetBenchmarkedResourceList` — the hardware speed dating 🌈

BEAGLE_DLLEXPORT BeagleBenchmarkedResourceList*
beagleGetBenchmarkedResourceList (int tipCount, int compactBufferCount,
    int stateCount, int patternCount, int categoryCount, int * resourceList,
    int resourceCount, long preferenceFlags, long requirementFlags, int
    eigenModelCount, int partitionCount, int calculateDerivatives, long
    benchmarkFlags)

Get a benchmarked list of hardware resources for the given analysis parameters. This function returns a pointer to a BeagleBenchmarkedResourceList struct, which includes a BeagleBenchmarkedResource array describing the available hardware resources with benchmark times and CPU performance ratios for each resource. Resources are benchmarked with the given analysis parameters and the array is ordered from fastest to slowest. If there is an error the function returns NULL.

Parameters:

tipCount — Number of tip data elements (input)
compactBufferCount — Number of compact state representation tips (input)
stateCount — Number of states in the continuous-time Markov chain (input)
patternCount — Number of site patterns (input)
categoryCount — Number of rate categories (input)
resourceList — List of resources to be benchmarked, NULL implies no restriction (input)
resourceCount — Length of resourceList list (input)
preferenceFlags — Bit-flags indicating preferred implementation characteristics, see BeagleFlags (input)
requirementFlags — Bit-flags indicating required implementation characteristics, see BeagleFlags (input)
eigenModelCount — Number of full-alignment rate matrix eigen-decomposition models (input)
partitionCount — Number of partitions (input)
calculateDerivatives — Indicates if calculation of derivatives are required (input)
benchmarkFlags — Bit-flags indicating benchmarking preferences (input)

Returns: An ordered (fastest to slowest) list of hardware resources available to the library as a BeagleBenchmarkedResourceList for the specified analysis parameters

`beagleGetCitation` — cite your faves 🎀

BEAGLE_DLLEXPORT const char* beagleGetCitation (void)

Get citation. This function returns a pointer to a string describing the version of the library and how to cite it.

Returns: A string describing the version of the library and how to cite it

`beagleGetDerivatives` — async girlies only 💅

BEAGLE_DLLEXPORT int beagleGetDerivatives (int instance, double *
    outSumFirstDerivative, double * outSumSecondDerivative)

Returns derivative sums subsequent to an asynchronous integration call. This function is optional and only has to be called by clients that use the non-blocking asynchronous computation mode (BEAGLE_FLAG_COMPUTATION_ASYNCH).

If used, this function must be called after a beagleCalculateEdgeLogLikelihoods call. The library will block until the derivatives have been calculated.

Parameters:

instance — Instance number (input)
outSumFirstDerivative — Pointer to destination for resulting first derivative (output)
outSumSecondDerivative — Pointer to destination for resulting second derivative (output)

Returns: error code

`beagleGetLogLikelihood` — the likelihood tea ☕

BEAGLE_DLLEXPORT int beagleGetLogLikelihood (int instance, double *
    outSumLogLikelihood)

Returns log likelihood sum and subsequent to an asynchronous integration call. This function is optional and only has to be called by clients that use the non-blocking asynchronous computation mode (BEAGLE_FLAG_COMPUTATION_ASYNCH).

If used, this function must be called after a beagleCalculateRootLogLikelihoods or beagleCalculateEdgeLogLikelihoods call. The library will block until the likelihood has been calculated.

Parameters:

instance — Instance number (input)
outSumLogLikelihood — Pointer to destination for resulting log likelihood (output)

Returns: error code

`beagleGetPartials` — grab those partials 🫶

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

Get partials from an instance buffer. This function copies an instance buffer into the array outPartials. The outPartials array should be stateCount * patternCount * categoryCount in length.

Parameters:

instance — Instance number from which to get partialsBuffer (input)
bufferIndex — Index of source partialsBuffer (input)
scaleIndex — Index of scaleBuffer to apply to partialsBuffer (input)
outPartials — Pointer to which to receive partialsBuffer (output)

Returns: error code

BEAGLE_DLLEXPORT BeagleResourceList* beagleGetResourceList (void)

Get list of hardware resources. This function returns a pointer to a BeagleResourceList struct, which includes a BeagleResource array describing the available hardware resources.

Returns: A list of hardware resources available to the library as a BeagleResourceList

`beagleGetScaleFactors` — scale factor vibes ⭐

BEAGLE_DLLEXPORT int beagleGetScaleFactors (int instance, int
    srcScalingIndex, double * outScaleFactors)

Get scale factors. This function retrieves a buffer of scale factors.

Parameters:

instance — Instance number (input)
srcScalingIndex — Source scaleBuffer (input)
outScaleFactors — Pointer to which to receive scaleFactors (output)

`beagleGetSiteDerivatives` — per-site derivatives, periodt 💅

BEAGLE_DLLEXPORT int beagleGetSiteDerivatives (int instance, double *
    outFirstDerivatives, double * outSecondDerivatives)

Get site derivatives for last beagleCalculateEdgeLogLikelihoods call. This function returns the derivatives for each site

Parameters:

instance — Instance number (input)
outFirstDerivatives — Pointer to destination for resulting first derivatives (output)
outSecondDerivatives — Pointer to destination for resulting second derivatives (output)

Returns: error code

`beagleGetSiteLogLikelihoods` — per-site log-likelihoods 🌸

BEAGLE_DLLEXPORT int beagleGetSiteLogLikelihoods (int instance, double *
    outLogLikelihoods)

Get site log likelihoods for last beagleCalculateRootLogLikelihoods or beagleCalculateEdgeLogLikelihoods call. This function returns the log likelihoods for each site

Parameters:

instance — Instance number (input)
outLogLikelihoods — Pointer to destination for resulting log likelihoods (output)

Returns: error code

`beagleGetTransitionMatrix` — matrix moment 💖

BEAGLE_DLLEXPORT int beagleGetTransitionMatrix (int instance, int
    matrixIndex, double * outMatrix)

Get a finite-time transition probability matrix. This function copies a finite-time transition matrix buffer into the array outMatrix. The outMatrix array should be of size stateCount * stateCount * categoryCount and will be filled with one matrix for each rate category.

Parameters:

instance — Instance number (input)
matrixIndex — Index of matrix buffer (input)
outMatrix — Pointer to destination transition probability matrix (output)

Returns: error code

`beagleGetVersion` — what's the version, bestie? 🦋

BEAGLE_DLLEXPORT const char* beagleGetVersion (void)

Get version. This function returns a pointer to a string with the library version number.

Returns: A string with the version number

`beagleRemoveScaleFactors` — bye-bye scale factors 👋

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

Remove scale factors. This function removes (log) scale factors from a cumulative scale buffer. The scale factors to be removed are indicated in a list of scaleBuffers.

Parameters:

instance — Instance number (input)
scaleIndices — List of scaleBuffers to remove (input)
count — Number of scaleBuffers in list (input)
cumulativeScaleIndex — Index number of scaleBuffer containing accumulated factors (input)

`beagleRemoveScaleFactorsByPartition` — partition-specific removal 🎀

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

Remove scale factors by partition. This function removes (log) scale factors from a cumulative scale buffer. The scale factors to be removed are indicated in a list of scaleBuffers.

Parameters:

instance — Instance number (input)
scaleIndices — List of scaleBuffers to remove (input)
count — Number of scaleBuffers in list (input)
cumulativeScaleIndex — Index number of scaleBuffer containing accumulated factors (input)
partitionIndex — Index of partition to remove from (input)

`beagleResetScaleFactors` — reset the scale factors 🔄

BEAGLE_DLLEXPORT int beagleResetScaleFactors (int instance, int
    cumulativeScaleIndex)

Reset scalefactors. This function resets a cumulative scale buffer.

Parameters:

instance — Instance number (input)
cumulativeScaleIndex — Index number of cumulative scaleBuffer (input)

`beagleResetScaleFactorsByPartition` — reset by partition, slay ✨

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

Reset scalefactors by partition. This function resets a cumulative scale buffer.

Parameters:

instance — Instance number (input)
cumulativeScaleIndex — Index number of cumulative scaleBuffer (input)
partitionIndex — Index of partition to reset (input)

`beagleSetCategoryRates` — set those rates 💅

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

Set the default category rates buffer. This function sets the default vector of category rates for an instance.

okay so finishing up the deets on the function from before 💅 (the one whose heading already went by, you know the vibe):

Parameters

instance — the instance number, and yeah it's an input
inCategoryRates — array holding categoryCount rate scalers, also input

Returns

error code, bestie

🌸 `beagleSetCategoryRatesWithIndex` 🌸

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

okay so this one sets a category rates buffer — like, it takes the vector of category rates and drops it into a specific buffer inside an instance. not all buffers, that buffer. iykyk ✨

Parameters

instance — instance number (input)
categoryRatesIndex — the index of the category rates buffer you're targeting (input)
inCategoryRates — array containing categoryCount rate scalers (input)

Returns

error code 🫶

🎀 `beagleSetCategoryWeights` 🎀

BEAGLE_DLLEXPORT int beagleSetCategoryWeights (int instance, int categoryWeightsIndex, const double * inCategoryWeights)

set a category weights buffer!! it literally just copies a category weights array into an instance buffer. no drama, no plot twist, just copying ✨

Parameters

instance — instance number (input)
categoryWeightsIndex — index of the category weights buffer (input)
inCategoryWeights — the category weights array, sized categoryCount (input)

Returns

error code 💖

🦋 `beagleSetCPUThreadCount` 🦋

BEAGLE_DLLEXPORT int beagleSetCPUThreadCount (int instance, int threadCount)

so this sets how many threads the native CPU implementation gets to use — like, the max number of worker threads. the lore:

it should only be called after beagleCreateInstance ⚠️
it requires the BEAGLE_FLAG_THREADING_CPP flag to be set
it has no effect on GPU-based implementations, periodt
it also has no effect with the default BEAGLE_FLAG_THREADING_NONE setting
if BEAGLE_FLAG_THREADING_CPP is set and you never call this function, BEAGLE will use a heuristic to pick an appropriate number of threads for you. main character energy fr fr 🧚

Parameters

instance — instance number (input)
threadCount — number of threads (input)

Returns

error code 💜

✨ `beagleSetEigenDecomposition` ✨

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

sets an eigen-decomposition buffer — it copies an eigen-decomposition straight into an instance buffer. iconic math moment tbh 🌈

Parameters

instance — instance number (input)
eigenIndex — index of the eigen-decomposition buffer (input)
inEigenVectors — flattened matrix (stateCount x stateCount) of eigenvectors (input)
inInverseEigenVectors — flattened matrix (stateCount x stateCount) of inverse-eigenvectors (input)
inEigenValues — vector of eigenvalues

Returns

error code ⭐

💅 `beagleSetPartials` 💅

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

sets an instance partials buffer — it copies an array of partials into an instance buffer. heads up bestie: the inPartials array should be stateCount * patternCount * categoryCount in length. that's the whole size, no shortcuts 🔥

Parameters

instance — instance number in which to set a partialsBuffer (input)
bufferIndex — index of destination partialsBuffer (input)
inPartials — pointer to partials values to set (input)

Returns

error code 🍓

🌸 `beagleSetPatternPartitions` 🌸

BEAGLE_DLLEXPORT int beagleSetPatternPartitions (int instance, int partitionCount, const int * inPatternPartitions)

sets the pattern partition assignments — it sets the vector of pattern partition indices for an instance. and listen, the order matters: it should only be called after beagleSetTipPartials and beagleSetPatternWeights. not before. do not be chaotic about this 🙈

Parameters

instance — instance number (input)
partitionCount — number of partitions (input)
inPatternPartitions — array containing partitionCount partition indices (input)

Returns

error code 💖

🦋 `beagleSetPatternWeights` 🦋

BEAGLE_DLLEXPORT int beagleSetPatternWeights (int instance, const double * inPatternWeights)

sets the pattern weights — it sets the vector of pattern weights for an instance. simple, clean, slay ✨

Parameters

instance — instance number (input)
inPatternWeights — array containing patternCount weights (input)

Returns

error code 👑

🎀 `beagleSetStateFrequencies` 🎀

BEAGLE_DLLEXPORT int beagleSetStateFrequencies (int instance, int stateFrequenciesIndex, const double * inStateFrequencies)

sets a state frequency buffer — copies a state frequency array into an instance buffer. that's it, that's the function 💜

Parameters

instance — instance number (input)
stateFrequenciesIndex — index of the state frequencies buffer (input)
inStateFrequencies — state frequencies array, sized stateCount (input)

Returns

error code 🫶

🌈 `beagleSetTipPartials` 🌈

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

sets an instance partials buffer for a tip node — it copies an array of partials into an instance buffer. the inPartials array should be stateCount * patternCount in length. for most applications this is what you'll use to set the partial likelihoods for the observed states. and internally? the partials get copied categoryCount times. no cap 🔥

Parameters

instance — instance number in which to set a partialsBuffer (input)
tipIndex — index of destination partialsBuffer (input)
inPartials — pointer to partials values to set (input)

Returns

error code 💖

⭐ `beagleSetTipStates` ⭐

BEAGLE_DLLEXPORT int beagleSetTipStates (int instance, int tipIndex, const int * inStates)

sets the compact state representation for a tip node — it copies a compact state representation into an instance buffer. compact state representation is literally an array of states: 0 to stateCount - 1, and missing = stateCount. the inStates array should be patternCount in length, and nope, replication across categoryCount is not required here 🧚

Parameters

instance — instance number (input)
tipIndex — index of destination compactBuffer (input)
inStates — pointer to compact states (input)

Returns

error code ✨

💅 `beagleSetTransitionMatrices` 💅

BEAGLE_DLLEXPORT int beagleSetTransitionMatrices (int instance, const int * matrixIndices, const double * inMatrices, const double * paddedValues, int count)

sets multiple transition matrices at once — it copies multiple transition matrices into matrix buffers. you'd use this when your app wants to explicitly set the transition matrices itself instead of going through beagleSetEigenDecomposition and beagleUpdateTransitionMatrices. the inMatrices array should be size stateCount * stateCount * categoryCount * count. yes, that's a lot of multiplying, it's giving "dimensionality" 💀

Parameters

instance — instance number (input)
matrixIndices — indices of matrix buffers (input)
inMatrices — pointer to source transition matrices (input)
paddedValues — values to be used for padding for ambiguous states, e.g. 1 for probability matrices, 0 for derivative matrices (input)
count — number of transition matrices (input)

Returns

error code 🍓

🦋 `beagleSetTransitionMatrix` 🦋

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

sets a finite-time transition probability matrix — copies one into a matrix buffer. again, this is the "i'll set it myself" route instead of using beagleSetEigenDecomposition and beagleUpdateTransitionMatrices. the inMatrix array should be size stateCount * stateCount * categoryCount and will contain one matrix for each rate category. one matrix per category, we love an organized queen 👑

Parameters

instance — instance number (input)
matrixIndex — index of matrix buffer (input)
inMatrix — pointer to source transition probability matrix (input)
paddedValue — value to be used for padding for ambiguous states, e.g. 1 for probability matrices, 0 for derivative matrices (input)

Returns

error code 💜

🔥 `beagleUpdatePartials` 🔥

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

calculates — or queues for calculation — partials using a list of operations. so here's the tea: implementations supporting ASYNCH may queue these calculations, while other implementations perform these operations immediately and in order. two very different vibes, same function 🌈

Parameters

instance — instance number (input)
operations — BeagleOperation list specifying operations (input)
operationCount — number of operations (input)
cumulativeScaleIndex — index number of scaleBuffer to store accumulated factors (input)

Returns

error code 💖

✨ `beagleUpdatePartialsByPartition` ✨

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

same energy as the last one but partitioned: calculates or queues for calculation a list of partitioned partials, using a list of partition operations. and yeah, ASYNCH-supporting implementations may queue these while others do them immediately and in order 💅

Parameters

instance — instance number (input)
operations — BeagleOperation list specifying operations (input)
operationCount — number of operations (input)

Returns

error code ⭐

🌸 `beagleUpdateTransitionMatrices` 🌸

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

calculates a list of transition probability matrices — and their first and second derivatives, but only if you asked for them. no free derivatives, bestie 🫶

Parameters

instance — instance number (input)
eigenIndex — index of eigen-decomposition buffer (input)
probabilityIndices — list of indices of transition probability matrices to update (input)
firstDerivativeIndices — list of indices of first derivative matrices to update (input, NULL implies no calculation)
secondDerivativeIndices — list of indices of second derivative matrices to update (input, NULL implies no calculation)
edgeLengths — list of edge lengths with which to perform calculations (input)
count — length of lists

Returns

error code 💜

🧚 `beagleUpdateTransitionMatricesWithMultipleModels` 🧚

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)

calculates a list of transition probability matrices with multiple models — this function calculates a list of transition probabilities matrices and their first and second derivatives (if requested).

Parameters 🫶

okay so here's the tea on what you gotta hand over 👇

instance — Instance number (input)
eigenIndices — List of indices of eigen-decomposition buffers to use for updates (input)
categoryRateIndices — List of indices of category-rate buffers to use for updates (input)
probabilityIndices — List of indices of transition probability matrices to update (input)
firstDerivativeIndices — List of indices of first derivative matrices to update (input, NULL implies no calculation)
secondDerivativeIndices — List of indices of second derivative matrices to update (input, NULL implies no calculation)
edgeLengths — List of edge lengths with which to perform calculations (input)
count — Length of lists

Returns ✨

error code 💖 (yes bestie, that's the whole vibe, it just hands you back an error code)

🌸 `beagleWaitForPartials` 🌸

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

Block until all calculations that write to the specified partials have completed. Okay so this one is optional, like genuinely optional — you only ever call it if you're a client that 'recycles' partials. Reusing partials? Iconic. But then you gotta wait for them, no cutting the line 🫶

If you do use it, here's the rules, bestie, listen up:

It must be called after a beagleUpdatePartials call.
It must refer to indices of 'destinationPartials' that were used in a previous beagleUpdatePartials call.

The library will just sit there and block until those partials have been calculated. That's it. That's the whole job. It's giving bouncer at the club door, checking that everybody's inside before it lets you through 💅

Parameters 💜

instance — Instance number (input)
destinationPartials — List of the indices of destinationPartials that must be calculated before the function returns
destinationPartialsCount — Number of destinationPartials (input)

Returns 🌈

error code ⭐

👑 Author

Generated automatically by Doxygen for BEAGLE from the source code. (no human wrote this by hand, the robots did it, and honestly? slay 🤖✨)

aaaand that's a wrap on the whole page, bestie!! 🎀 This was Version 3.1.2, dated Tue Oct 19 2021, and it's all about libhmsbeagle/beagle.h(3) — go forth and phylogenetically compute, you main character 🦋💖

📦 where this page comes from

ubuntu jammy: libhmsbeagle-dev 3.1.2+dfsg-12ubuntu1 · LGPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

libhmsbeagle/beagle.h(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🎀 Classes 🎀

🌸 Enumerations 🌸

enum BeagleReturnCodes

enum BeagleFlags

enum BeagleBenchmarkFlags

enum BeagleOpCodes

✨ FUNCTIONS ✨

Detailed Description 💖

🔑 KEY CONCEPTS 🔑

🛠️ USAGE 🛠️

Author 👑

📚 Enumeration Type Documentation 📚

enum BeagleBenchmarkFlags

Enumerator

enum BeagleFlags

Enumerator

enum BeagleOpCodes

Enumerator

enum BeagleReturnCodes

Enumerator

🧚 Function Documentation 🧚

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

Parameters

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

Parameters

beagleCalculateEdgeLogLikelihoods 💖

beagleCalculateEdgeLogLikelihoodsByPartition 🦋

beagleCalculateRootLogLikelihoods 🌿

beagleCalculateRootLogLikelihoodsByPartition 🫶

beagleConvolveTransitionMatrices ⭐

beagleCopyScaleFactors 🎀

beagleCreateInstance 👑

beagleFinalize — the big goodbye 💅

beagleFinalizeInstance — one instance, peace out ✌️

beagleGetBenchmarkedResourceList — the hardware speed dating 🌈

beagleGetCitation — cite your faves 🎀

beagleGetDerivatives — async girlies only 💅

beagleGetLogLikelihood — the likelihood tea ☕

beagleGetPartials — grab those partials 🫶

beagleGetResourceList — hardware menu 👑

beagleGetScaleFactors — scale factor vibes ⭐

beagleGetSiteDerivatives — per-site derivatives, periodt 💅

beagleGetSiteLogLikelihoods — per-site log-likelihoods 🌸

beagleGetTransitionMatrix — matrix moment 💖

beagleGetVersion — what's the version, bestie? 🦋

beagleRemoveScaleFactors — bye-bye scale factors 👋

beagleRemoveScaleFactorsByPartition — partition-specific removal 🎀

beagleResetScaleFactors — reset the scale factors 🔄

beagleResetScaleFactorsByPartition — reset by partition, slay ✨

beagleSetCategoryRates — set those rates 💅

🌸 beagleSetCategoryRatesWithIndex 🌸

🎀 beagleSetCategoryWeights 🎀

🦋 beagleSetCPUThreadCount 🦋

✨ beagleSetEigenDecomposition ✨

💅 beagleSetPartials 💅

🌸 beagleSetPatternPartitions 🌸

🦋 beagleSetPatternWeights 🦋

🎀 beagleSetStateFrequencies 🎀

🌈 beagleSetTipPartials 🌈

⭐ beagleSetTipStates ⭐

💅 beagleSetTransitionMatrices 💅

🦋 beagleSetTransitionMatrix 🦋

🔥 beagleUpdatePartials 🔥

✨ beagleUpdatePartialsByPartition ✨

🌸 beagleUpdateTransitionMatrices 🌸

🧚 beagleUpdateTransitionMatricesWithMultipleModels 🧚

Parameters 🫶

Returns ✨

🌸 beagleWaitForPartials 🌸

Parameters 💜

Returns 🌈

👑 Author

`enum BeagleReturnCodes`

`enum BeagleFlags`

`enum BeagleBenchmarkFlags`

`enum BeagleOpCodes`

`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)`

`beagleCalculateEdgeLogLikelihoods` 💖

`beagleCalculateEdgeLogLikelihoodsByPartition` 🦋

`beagleCalculateRootLogLikelihoods` 🌿

`beagleCalculateRootLogLikelihoodsByPartition` 🫶

`beagleConvolveTransitionMatrices` ⭐

`beagleCopyScaleFactors` 🎀

`beagleCreateInstance` 👑

`beagleFinalize` — the big goodbye 💅

`beagleFinalizeInstance` — one instance, peace out ✌️

`beagleGetBenchmarkedResourceList` — the hardware speed dating 🌈

`beagleGetCitation` — cite your faves 🎀

`beagleGetDerivatives` — async girlies only 💅

`beagleGetLogLikelihood` — the likelihood tea ☕

`beagleGetPartials` — grab those partials 🫶

`beagleGetResourceList` — hardware menu 👑

`beagleGetScaleFactors` — scale factor vibes ⭐

`beagleGetSiteDerivatives` — per-site derivatives, periodt 💅

`beagleGetSiteLogLikelihoods` — per-site log-likelihoods 🌸

`beagleGetTransitionMatrix` — matrix moment 💖

`beagleGetVersion` — what's the version, bestie? 🦋

`beagleRemoveScaleFactors` — bye-bye scale factors 👋

`beagleRemoveScaleFactorsByPartition` — partition-specific removal 🎀

`beagleResetScaleFactors` — reset the scale factors 🔄

`beagleResetScaleFactorsByPartition` — reset by partition, slay ✨

`beagleSetCategoryRates` — set those rates 💅

🌸 `beagleSetCategoryRatesWithIndex` 🌸

🎀 `beagleSetCategoryWeights` 🎀

🦋 `beagleSetCPUThreadCount` 🦋

✨ `beagleSetEigenDecomposition` ✨

💅 `beagleSetPartials` 💅

🌸 `beagleSetPatternPartitions` 🌸

🦋 `beagleSetPatternWeights` 🦋

🎀 `beagleSetStateFrequencies` 🎀

🌈 `beagleSetTipPartials` 🌈

⭐ `beagleSetTipStates` ⭐

💅 `beagleSetTransitionMatrices` 💅

🦋 `beagleSetTransitionMatrix` 🦋

🔥 `beagleUpdatePartials` 🔥

✨ `beagleUpdatePartialsByPartition` ✨

🌸 `beagleUpdateTransitionMatrices` 🌸

🧚 `beagleUpdateTransitionMatricesWithMultipleModels` 🧚

🌸 `beagleWaitForPartials` 🌸