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:   Note:
 52:   One can perform binary classification using the ridge regressor type by converting labels into the
 53:   values -1 and +1, corresponding to the two classes, and then performing a ridge regression.
 54:   Observations with a negative prediction value are then placed in the -1 class, while those with positive values
 55:   are placed in the +1 class.
 56:   This is the approach used in the RidgeClassifer implementation provided by the scikit-learn library.

 58: .seealso: `PetscRegressor`, `PETSCREGRESSORLINEAR`
 59: E*/

 61: typedef enum {
 62:   REGRESSOR_LINEAR_OLS,
 63:   REGRESSOR_LINEAR_LASSO,
 64:   REGRESSOR_LINEAR_RIDGE
 65: } PetscRegressorLinearType;
 66: PETSC_EXTERN const char *const PetscRegressorLinearTypes[];

 68: PETSC_EXTERN PetscFunctionList PetscRegressorList;
 69: PETSC_EXTERN PetscClassId      PETSCREGRESSOR_CLASSID;

 71: PETSC_EXTERN PetscErrorCode PetscRegressorInitializePackage(void);
 72: PETSC_EXTERN PetscErrorCode PetscRegressorFinalizePackage(void);
 73: PETSC_EXTERN PetscErrorCode PetscRegressorRegister(const char[], PetscErrorCode (*)(PetscRegressor));

 75: PETSC_EXTERN PetscErrorCode PetscRegressorCreate(MPI_Comm, PetscRegressor *);
 76: PETSC_EXTERN PetscErrorCode PetscRegressorReset(PetscRegressor);
 77: PETSC_EXTERN PetscErrorCode PetscRegressorDestroy(PetscRegressor *);

 79: PETSC_EXTERN PetscErrorCode PetscRegressorSetOptionsPrefix(PetscRegressor, const char[]);
 80: PETSC_EXTERN PetscErrorCode PetscRegressorAppendOptionsPrefix(PetscRegressor, const char[]);
 81: PETSC_EXTERN PetscErrorCode PetscRegressorGetOptionsPrefix(PetscRegressor, const char *[]);

 83: PETSC_EXTERN PetscErrorCode PetscRegressorSetType(PetscRegressor, PetscRegressorType);
 84: PETSC_EXTERN PetscErrorCode PetscRegressorGetType(PetscRegressor, PetscRegressorType *);
 85: PETSC_EXTERN PetscErrorCode PetscRegressorSetRegularizerWeight(PetscRegressor, PetscReal);
 86: PETSC_EXTERN PetscErrorCode PetscRegressorSetUp(PetscRegressor);
 87: PETSC_EXTERN PetscErrorCode PetscRegressorSetFromOptions(PetscRegressor);

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

 92: PETSC_EXTERN PetscErrorCode PetscRegressorFit(PetscRegressor, Mat, Vec);
 93: PETSC_EXTERN PetscErrorCode PetscRegressorPredict(PetscRegressor, Mat, Vec);
 94: PETSC_EXTERN PetscErrorCode PetscRegressorGetTao(PetscRegressor, Tao *);

 96: PETSC_EXTERN PetscErrorCode PetscRegressorLinearSetFitIntercept(PetscRegressor, PetscBool);
 97: PETSC_EXTERN PetscErrorCode PetscRegressorLinearSetUseKSP(PetscRegressor, PetscBool);
 98: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetKSP(PetscRegressor, KSP *);
 99: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetCoefficients(PetscRegressor, Vec *);
100: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetIntercept(PetscRegressor, PetscScalar *);
101: PETSC_EXTERN PetscErrorCode PetscRegressorLinearSetType(PetscRegressor, PetscRegressorLinearType);
102: PETSC_EXTERN PetscErrorCode PetscRegressorLinearGetType(PetscRegressor, PetscRegressorLinearType *);