1: #pragma once

  3: #include <petsctao.h>

  5: /* MANSEC = ML */
  6: /* SUBMANSEC = PetscRegressor */

  8: /*S
  9:    PetscRegressor - Abstract PETSc object that manages regression and classification problems

 11:    Level: beginner

 13:    Notes:
 14:    For linear problems `PetscRegressor` supports ordinary least squares, lasso, and ridge regression using the `PetscRegressorType` of `PETSCREGRESSORLINEAR`
 15:    and `PetscRegressorLinearType` of `REGRESSOR_LINEAR_OLS`, `REGRESSOR_LINEAR_LASSO`, and `REGRESSOR_LINEAR_RIDGE`.

 17:    We have slightly abused the term "regressor" in the naming of this component of PETSc.
 18:    Statisticians would say that we are doing "regression", and a "regressor", in this context, strictly means an
 19:    independent (or "predictor") variable in the regression analysis. However, "regressor" has taken on an informal
 20:    meaning in the machine-learning community of something along the lines of "algorithm or implementation used to fit
 21:    a regression model". Examples are `MLPRegressor` (multi-layer perceptron regressor) or `RandomForestRegressor`
 22:    from the scikit-learn toolkit (which is itself not consistent about the use of the term "regressor", since it has a
 23:    `LinearRegression` component instead of a `LinearRegressor` component).

 25: .seealso: `PetscRegressorCreate()`, `PetscRegressorLinearType`, `PetscRegressorSetType()`, `PetscRegressorType`, `PetscRegressorDestroy()`,
 26:           `PETSCREGRESSORLINEAR`, `PetscRegressorLinearType`, `REGRESSOR_LINEAR_OLS`, `REGRESSOR_LINEAR_LASSO`, `REGRESSOR_LINEAR_RIDGE`.
 27: S*/
 28: typedef struct _p_PetscRegressor *PetscRegressor;

 30: /*J
 31:   PetscRegressorType - String with the name of a PETSc regression method.

 33:   Level: beginner

 35: .seealso: [](ch_regressor), `PetscRegressorSetType()`, `PetscRegressor`, `PetscRegressorRegister()`, `PetscRegressorCreate()`, `PetscRegressorSetFromOptions()`,
 36:           `PETSCREGRESSORLINEAR`
 37: J*/
 38: typedef const char *PetscRegressorType;
 39: #define PETSCREGRESSORLINEAR "linear"

 41: /*E
 42:   PetscRegressorLinearType - Type of linear regression

 44:   Values:
 45: +  `REGRESSOR_LINEAR_OLS`    - ordinary least squares
 46: .  `REGRESSOR_LINEAR_LASSO`  - lasso
 47: -  `REGRESSOR_LINEAR_RIDGE`  - ridge

 49:   Level: advanced

 51: .seealso: `PetscRegressor`, `PETSCREGRESSORLINEAR`
 52: E*/

 54: typedef enum {
 55:   REGRESSOR_LINEAR_OLS,
 56:   REGRESSOR_LINEAR_LASSO,
 57:   REGRESSOR_LINEAR_RIDGE
 58: } PetscRegressorLinearType;
 59: PETSC_EXTERN const char *const PetscRegressorLinearTypes[];

 61: PETSC_EXTERN PetscFunctionList PetscRegressorList;
 62: PETSC_EXTERN PetscClassId      PETSCREGRESSOR_CLASSID;

 64: PETSC_EXTERN PetscErrorCode PetscRegressorInitializePackage(void);
 65: PETSC_EXTERN PetscErrorCode PetscRegressorFinalizePackage(void);
 66: PETSC_EXTERN PetscErrorCode PetscRegressorRegister(const char[], PetscErrorCode (*)(PetscRegressor));

 68: PETSC_EXTERN PetscErrorCode PetscRegressorCreate(MPI_Comm, PetscRegressor *);
 69: PETSC_EXTERN PetscErrorCode PetscRegressorReset(PetscRegressor);
 70: PETSC_EXTERN PetscErrorCode PetscRegressorDestroy(PetscRegressor *);

 72: PETSC_EXTERN PetscErrorCode PetscRegressorSetOptionsPrefix(PetscRegressor, const char[]);
 73: PETSC_EXTERN PetscErrorCode PetscRegressorAppendOptionsPrefix(PetscRegressor, const char[]);
 74: PETSC_EXTERN PetscErrorCode PetscRegressorGetOptionsPrefix(PetscRegressor, const char *[]);

 76: PETSC_EXTERN PetscErrorCode PetscRegressorSetType(PetscRegressor, PetscRegressorType);
 77: PETSC_EXTERN PetscErrorCode PetscRegressorGetType(PetscRegressor, PetscRegressorType *);
 78: PETSC_EXTERN PetscErrorCode PetscRegressorSetRegularizerWeight(PetscRegressor, PetscReal);
 79: PETSC_EXTERN PetscErrorCode PetscRegressorSetUp(PetscRegressor);
 80: PETSC_EXTERN PetscErrorCode PetscRegressorSetFromOptions(PetscRegressor);

 82: PETSC_EXTERN PetscErrorCode PetscRegressorView(PetscRegressor, PetscViewer);
 83: PETSC_EXTERN PetscErrorCode PetscRegressorViewFromOptions(PetscRegressor, PetscObject, const char[]);

 85: PETSC_EXTERN PetscErrorCode PetscRegressorFit(PetscRegressor, Mat, Vec);
 86: PETSC_EXTERN PetscErrorCode PetscRegressorPredict(PetscRegressor, Mat, Vec);
 87: PETSC_EXTERN PetscErrorCode PetscRegressorGetTao(PetscRegressor, Tao *);

 89: PETSC_EXTERN PetscErrorCode PetscRegressorLinearSetFitIntercept(PetscRegressor, PetscBool);
 90: PETSC_EXTERN PetscErrorCode PetscRegressorLinearSetUseKSP(PetscRegressor, PetscBool);
 91: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetKSP(PetscRegressor, KSP *);
 92: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetCoefficients(PetscRegressor, Vec *);
 93: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetIntercept(PetscRegressor, PetscScalar *);
 94: PETSC_EXTERN PetscErrorCode PetscRegressorLinearSetType(PetscRegressor, PetscRegressorLinearType);
 95: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetType(PetscRegressor, PetscRegressorLinearType *);