include/ode/matrix_coop.h

   1 /*************************************************************************
   2  *                                                                       *
   3  * Open Dynamics Engine, Copyright (C) 2001-2003 Russell L. Smith.       *
   4  * All rights reserved.  Email: russ@q12.org   Web: www.q12.org          *
   5  *                                                                       *
   6  * This library is free software; you can redistribute it and/or         *
   7  * modify it under the terms of EITHER:                                  *
   8  *   (1) The GNU Lesser General Public License as published by the Free  *
   9  *       Software Foundation; either version 2.1 of the License, or (at  *
  10  *       your option) any later version. The text of the GNU Lesser      *
  11  *       General Public License is included with this library in the     *
  12  *       file LICENSE.TXT.                                               *
  13  *   (2) The BSD-style license that is included with this library in     *
  14  *       the file LICENSE-BSD.TXT.                                       *
  15  *                                                                       *
  16  * This library is distributed in the hope that it will be useful,       *
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files    *
  19  * LICENSE.TXT and LICENSE-BSD.TXT for more details.                     *
  20  *                                                                       *
  21  *************************************************************************/
  22
  23 #ifndef _ODE_MATRIX_COOP_H_
  24 #define _ODE_MATRIX_COOP_H_
  25
  26
  27 #include <ode/common.h>
  28 #include <ode/cooperative.h>
  29 #include <ode/threading.h>
  30
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @defgroup matrix_coop Matrix Cooperative Algorithms
  38  *
  39  * Cooperative algorithms operating on matrices and vectors.
  40  *
  41  * @ingroup coop
  42  */
  43
  44
  45 /**
  46  * @brief Estimates resource requirements for a @c dCooperativelyFactorLDLT call
  47  *
  48  * The function updates the contents of @a requirements to also suffice for calling
  49  * @c dCooperativelyFactorLDLT with the given parameters.
  50  *
  51  * Note: The requirements that could have already been in the @a requirements parameter
  52  * are never decreased.
  53  *
  54  * @param requirements The ResourceRequirements object to update
  55  * @param maximalAllowedThreadCount Maximal value of allowedThreadCount parameter that is going to be used
  56  * @param maximalRowCount Maximal value of rowCount parameter that is going to be used
  57  * @ingroup matrix_coop
  58  * @see dCooperativelyFactorLDLT
  59  * @see dResourceRequirementsCreate
  60  */
  61 ODE_API void dEstimateCooperativelyFactorLDLTResourceRequirements(dResourceRequirementsID requirements,
  62     unsigned maximalAllowedThreadCount, unsigned maximalRowCount);
  63
  64 /**
  65  * @brief Cooperatively factorizes a matrix `A' into L*D*L'
  66  *
  67  * The function factorizes a matrix `A' into L*D*L', where `L' is lower triangular with ones on
  68  * the diagonal, and `D' is diagonal.
  69  * @a A is a rowCount*rowCount matrix stored by rows, with a leading dimension of @a rowCount rounded
  70  * up at least to 4 elements. `L; is written into the strict lower triangle of @a A
  71  * (the ones are not written) and the reciprocal of the diagonal elements of `D' are written into @a d.
  72  *
  73  * The @a resources must have had been allocated from a ResourceRequirements object
  74  * estimated in @c dEstimateCooperativelyFactorLDLTResourceRequirements.
  75  *
  76  * The operation is performed cooperatively by up to @a allowedThreadCount threads
  77  * from thread pool available in @a resources. The threading must not be simultaneously
  78  * used (via other @c dResourceContainerID instances) in other calls that employ its features.
  79  *
  80  * @param resources The resources allocated for the function
  81  * @param allowedThreadCount Maximum thread count to use (the actual thread count could be less, depending on other parameters)
  82  * @param A The `A' matrix
  83  * @param d The `d' vector
  84  * @param rowCount The row count in @a A and @a d
  85  * @param rowskip The actual number of elements to be added to skip to next row in @a A
  86  * @ingroup matrix_coop
  87  * @see dEstimateCooperativelyFactorLDLTResourceRequirements
  88  * @see dResourceContainerAcquire
  89  * @see dCooperativelySolveLDLT
  90  */
  91 ODE_API void dCooperativelyFactorLDLT(dResourceContainerID resources, unsigned allowedThreadCount,
  92     dReal *A, dReal *d, unsigned rowCount, unsigned rowSkip);
  93
  94
  95 /**
  96  * @brief Estimates resource requirements for a @c dCooperativelySolveLDLT call
  97  *
  98  * The function updates the contents of @a requirements to also suffice for calling
  99  * @c dCooperativelySolveLDLT with the given parameters.
 100  *
 101  * Note: The requirements that could have already been in the @a requirements parameter
 102  * are never decreased.
 103  *
 104  * @param requirements The ResourceRequirements object to update
 105  * @param maximalAllowedThreadCount Maximal value of allowedThreadCount parameter that is going to be used
 106  * @param maximalRowCount Maximal value of rowCount parameter that is going to be used
 107  * @ingroup matrix_coop
 108  * @see dCooperativelySolveLDLT
 109  * @see dResourceRequirementsCreate
 110  */
 111 ODE_API void dEstimateCooperativelySolveLDLTResourceRequirements(dResourceRequirementsID requirements,
 112     unsigned maximalAllowedThreadCount, unsigned maximalRowCount);
 113
 114 /**
 115  * @brief Cooperatively solves L*D*L'*x=b
 116  *
 117  * Given `L', a rowCount*rowCount lower triangular matrix with ones on the diagonal,
 118  * and `d', a rowCount*1 vector of the reciprocal diagonal elements of a rowCount*rowCount matrix
 119  * D, the function solves L*D*L'*x=b where `x' and `b' are rowCount*1.
 120  * The leading dimension of @a L is @a rowSkip. The resulting vector `x' overwrites @a b.
 121  *
 122  * The @a resources must have had been allocated from a ResourceRequirements object
 123  * estimated in @c dEstimateCooperativelySolveLDLTResourceRequirements.
 124  *
 125  * The operation is performed cooperatively by up to @a allowedThreadCount threads
 126  * from thread pool available in @a resources. The threading must not be simultaneously
 127  * used (via other @c dResourceContainerID instances) in other calls that employ its features.
 128  *
 129  * @param resources The resources allocated for the function
 130  * @param allowedThreadCount Maximum thread count to use (the actual thread count could be less, depending on other parameters)
 131  * @param L The `L' matrix
 132  * @param d The `d' vector
 133  * @param b The `b' vector; also the result is stored here
 134  * @param rowCount The row count in @a L, @a d and @a b
 135  * @param rowskip The actual number of elements to be added to skip to next row in @a L
 136  * @ingroup matrix_coop
 137  * @see dEstimateCooperativelySolveLDLTResourceRequirements
 138  * @see dResourceContainerAcquire
 139  * @see dCooperativelyFactorLDLT
 140  */
 141 ODE_API void dCooperativelySolveLDLT(dResourceContainerID resources, unsigned allowedThreadCount,
 142     const dReal *L, const dReal *d, dReal *b, unsigned rowCount, unsigned rowSkip);
 143
 144
 145 /**
 146  * @brief Estimates resource requirements for a @c dCooperativelySolveL1Straight call
 147  *
 148  * The function updates the contents of @a requirements to also suffice for calling
 149  * @c dCooperativelySolveL1Straight with the given parameters.
 150  *
 151  * Note: The requirements that could have already been in the @a requirements parameter
 152  * are never decreased.
 153  *
 154  * @param requirements The ResourceRequirements object to update
 155  * @param maximalAllowedThreadCount Maximal value of allowedThreadCount parameter that is going to be used
 156  * @param maximalRowCount Maximal value of rowCount parameter that is going to be used
 157  * @ingroup matrix_coop
 158  * @see dCooperativelySolveL1Straight
 159  * @see dResourceRequirementsCreate
 160  */
 161 ODE_API void dEstimateCooperativelySolveL1StraightResourceRequirements(dResourceRequirementsID requirements,
 162     unsigned maximalAllowedThreadCount, unsigned maximalRowCount);
 163
 164 /**
 165  * @brief Cooperatively solves L*x=b
 166  *
 167  * The function solves L*x=b, where `L' is rowCount*rowCount lower triangular with ones on the diagonal,
 168  * and `x', `b' are rowCount*1. The leading dimension of @a L is @a rowSkip.
 169  * @a b is overwritten with `x'.
 170  *
 171  * The @a resources must have had been allocated from a ResourceRequirements object
 172  * estimated in @c dEstimateCooperativelySolveL1StraightResourceRequirements.
 173  *
 174  * The operation is performed cooperatively by up to @a allowedThreadCount threads
 175  * from thread pool available in @a resources. The threading must not be simultaneously
 176  * used (via other @c dResourceContainerID instances) in other calls that employ its features.
 177  *
 178  * @param resources The resources allocated for the function
 179  * @param allowedThreadCount Maximum thread count to use (the actual thread count could be less, depending on other parameters)
 180  * @param L The `L' matrix
 181  * @param b The `b' vector; also the result is stored here
 182  * @param rowCount The row count in @a L and @a b
 183  * @param rowskip The actual number of elements to be added to skip to next row in @a L
 184  * @ingroup matrix_coop
 185  * @see dEstimateCooperativelySolveL1StraightResourceRequirements
 186  * @see dResourceContainerAcquire
 187  * @see dCooperativelyFactorLDLT
 188  */
 189 ODE_API void dCooperativelySolveL1Straight(dResourceContainerID resources, unsigned allowedThreadCount,
 190     const dReal *L, dReal *b, unsigned rowCount, unsigned rowSkip);
 191
 192
 193 /**
 194  * @brief Estimates resource requirements for a @c dCooperativelySolveL1Transposed call
 195  *
 196  * The function updates the contents of @a requirements to also suffice for calling
 197  * @c dCooperativelySolveL1Transposed with the given parameters.
 198  *
 199  * Note: The requirements that could have already been in the @a requirements parameter
 200  * are never decreased.
 201  *
 202  * @param requirements The ResourceRequirements object to update
 203  * @param maximalAllowedThreadCount Maximal value of allowedThreadCount parameter that is going to be used
 204  * @param maximalRowCount Maximal value of rowCount parameter that is going to be used
 205  * @ingroup matrix_coop
 206  * @see dCooperativelySolveL1Transposed
 207  * @see dResourceRequirementsCreate
 208  */
 209 ODE_API void dEstimateCooperativelySolveL1TransposedResourceRequirements(dResourceRequirementsID requirements,
 210     unsigned maximalAllowedThreadCount, unsigned maximalRowCount);
 211
 212 /**
 213  * @brief Cooperatively solves L'*x=b
 214  *
 215  * The function solves L'*x=b, where `L' is rowCount*rowCount lower triangular with ones on the diagonal,
 216  * and `x', b are rowCount*1. The leading dimension of @a L is @a rowSkip.
 217  * @a b is overwritten with `x'.
 218  *
 219  * The @a resources must have had been allocated from a ResourceRequirements object
 220  * estimated in @c dEstimateCooperativelySolveL1TransposedResourceRequirements.
 221  *
 222  * The operation is performed cooperatively by up to @a allowedThreadCount threads
 223  * from thread pool available in @a resources. The threading must not be simultaneously
 224  * used (via other @c dResourceContainerID instances) in other calls that employ its features.
 225  *
 226  * @param resources The resources allocated for the function
 227  * @param allowedThreadCount Maximum thread count to use (the actual thread count could be less, depending on other parameters)
 228  * @param L The `L' matrix
 229  * @param b The `b' vector; also the result is stored here
 230  * @param rowCount The row count in @a L and @a b
 231  * @param rowskip The actual number of elements to be added to skip to next row in @a L
 232  * @ingroup matrix_coop
 233  * @see dEstimateCooperativelySolveL1TransposedResourceRequirements
 234  * @see dResourceContainerAcquire
 235  * @see dCooperativelyFactorLDLT
 236  */
 237 ODE_API void dCooperativelySolveL1Transposed(dResourceContainerID resources, unsigned allowedThreadCount,
 238     const dReal *L, dReal *b, unsigned rowCount, unsigned rowSkip);
 239
 240
 241 /**
 242  * @brief Estimates resource requirements for a @c dCooperativelyScaleVector call
 243  *
 244  * The function updates the contents of @a requirements to also suffice for calling
 245  * @c dCooperativelyScaleVector with the given parameters.
 246  *
 247  * Note: The requirements that could have already been in the @a requirements parameter
 248  * are never decreased.
 249  *
 250  * @param requirements The ResourceRequirements object to update
 251  * @param maximalAllowedThreadCount Maximal value of allowedThreadCount parameter that is going to be used
 252  * @param maximalElementCount Maximal value of elementCount parameter that is going to be used
 253  * @ingroup matrix_coop
 254  * @see dCooperativelyScaleVector
 255  * @see dResourceRequirementsCreate
 256  */
 257 ODE_API void dEstimateCooperativelyScaleVectorResourceRequirements(dResourceRequirementsID requirements,
 258     unsigned maximalAllowedThreadCount, unsigned maximalElementCount);
 259
 260 /**
 261  * @brief Multiplies elements of one vector by corresponding element of another one
 262  *
 263  * In matlab syntax, the operation performed is: dataVector(1:elementCount) = dataVector(1:elementCount) .* scaleVector(1:elementCount)
 264  *
 265  * The @a resources must have had been allocated from a ResourceRequirements object
 266  * estimated in @c dEstimateCooperativelyScaleVectorResourceRequirements.
 267  *
 268  * The operation is performed cooperatively by up to @a allowedThreadCount threads
 269  * from thread pool available in @a resources. The threading must not be simultaneously
 270  * used (via other @c dResourceContainerID instances) in other calls that employ its features.
 271  *
 272  * @param resources The resources allocated for the function
 273  * @param allowedThreadCount Maximum thread count to use (the actual thread count could be less, depending on other parameters)
 274  * @param dataVector The vector to be scaled in place
 275  * @param scaleVector The scale vector
 276  * @param elementCount The number of elements in @a dataVector and @a scaleVector
 277  * @ingroup matrix_coop
 278  * @see dEstimateCooperativelyScaleVectorResourceRequirements
 279  * @see dResourceContainerAcquire
 280  * @see dCooperativelyFactorLDLT
 281  */
 282 ODE_API void dCooperativelyScaleVector(dResourceContainerID resources, unsigned allowedThreadCount,
 283     dReal *dataVector, const dReal *scaleVector, unsigned elementCount);
 284
 285
 286 #ifdef __cplusplus
 287 } // extern "C"
 288 #endif
 289
 290
 291 #endif // #ifndef _ODE_MATRIX_COOP_H_