mlr: documentation

doc/doxygen/chapters/370_online_performance_tools.doxy

@@ -397,6 +397,38 @@ performance model to perform scheduling, without using regression.
 </li>
 
 <li>
+
+Another type of model is ::STARPU_MULTIPLE_REGRESSION_BASED, which
+is based on multiple linear regression. In this model, the user
+defines both the relevant parameters and the equation for computing the
+task duration.
+
+\f[
+T_{kernel} = a + b(M^{\alpha_1}\times N^{\beta_1} \times K^{\gamma_1}) + c(M^{\alpha_2}\times N^{\beta_2} \times K^{\gamma_2}) + ...
+\f]
+
+\f$M, N, K\f$ are the parameters of the task, added at the task
+creation. These need to be extracted by the <c>cl_perf_func</c>
+function, which should be defined by the user. \f$\alpha, \beta,
+\gamma\f$ are the exponents defined by user in
+<c>model->combinations<\c> matrix. Finally, coefficients $\fa, b, c\f$
+are computed automatically at the end of the execution, using least
+squares method of the <c>dgels_</c> LAPACK function.
+
+<c>examples/basic_examples/mlr.c</c> example provides more details on
+the usage of ::STARPU_MULTIPLE_REGRESSION_BASED models.
+
+Computing of the coefficient is done at the end of the execution, and
+the results are stored in standard codelet perfmodel files. Additional
+files containing the duration of each task together with the value of
+each parameter is stored in .starpu/sampling/codelets/tmp/
+directory. These files are reused when ::STARPU_CALIBRATE
+environment variable is set to 1, to recompute coefficients based on
+the current, but also on the previous executions.
+
+</li>
+
+<li>
 Provided as an estimation from the application itself (model type
 ::STARPU_COMMON and field starpu_perfmodel::cost_function),
 see for instance

doc/doxygen/chapters/api/performance_model.doxy

@@ -26,6 +26,9 @@ Automatic linear regression-based cost model  (alpha * size ^ beta)
 \var starpu_perfmodel_type::STARPU_NL_REGRESSION_BASED
 \ingroup API_Performance_Model
 Automatic non-linear regression-based cost model (a * size ^ b + c)
+\var starpu_perfmodel_type::STARPU_MULTIPLE_REGRESSION_BASED
+\ingroup API_Performance_Model
+Automatic multiple linear regression-based cost model. Application provides parameters, their combinations and exponents
 
 \struct starpu_perfmodel_device
 todo
@@ -60,6 +63,8 @@ is the type of performance model
 ::STARPU_NL_REGRESSION_BASED: No other fields needs to be provided,
 this is purely history-based.
 </li>
+<li> ::STARPU_MULTIPLE_REGRESSION_BASED: Need to provide fields starpu_perfmodel::nparameters (number of different parameters),  starpu_perfmodel::ncombinations (number of parameters combinations-tuples) and matrix starpu_perfmodel::combinations which defines exponents of the equation. Function cl_perf_func also needs to define how to extract parameters from the task.
+</li>
 <li> ::STARPU_PER_ARCH: either field starpu_perfmodel::arch_cost_function has to be
 filled with a function that returns the cost in micro-seconds on the arch given
 as parameter, or field starpu_perfmodel::per_arch has to be
@@ -132,6 +137,12 @@ estimated = a size ^b + c
 whether the non-linear regression model is valid (i.e. enough measures)
 \var unsigned starpu_perfmodel_regression_model::nsample
 number of sample values for non-linear regression
+\var double starpu_perfmodel_regression_model::coeff[]
+list of computed coefficients for multiple linear regression model
+\var double starpu_perfmodel_regression_model::ncoeff
+number of coefficients for multiple linear regression model
+\var double starpu_perfmodel_regression_model::multi_valid
+whether the multiple linear regression model is valid
 
 \struct starpu_perfmodel_per_arch
 contains information about the performance model of a given
@@ -150,12 +161,12 @@ depends on the architecture-specific implementation.
 The history of performance measurements.
 \var struct starpu_perfmodel_history_list *starpu_perfmodel_per_arch::list
 \private
-Used by ::STARPU_HISTORY_BASED and ::STARPU_NL_REGRESSION_BASED,
+Used by ::STARPU_HISTORY_BASED, ::STARPU_NL_REGRESSION_BASED and ::STARPU_MULTIPLE_REGRESSION_BASED,
 records all execution history measures.
 \var struct starpu_perfmodel_regression_model starpu_perfmodel_per_arch::regression
 \private
-Used by ::STARPU_REGRESSION_BASED and
-::STARPU_NL_REGRESSION_BASED, contains the estimated factors of the
+Used by ::STARPU_REGRESSION_BASED, 
+::STARPU_NL_REGRESSION_BASED and ::STARPU_MULTIPLE_REGRESSION_BASED, contains the estimated factors of the
 regression.
 
 \struct starpu_perfmodel_history_list