1: #pragma once

  3: #include <petscmat.h>

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

  8: /*S
  9:    PetscDA - Abstract PETSc object that manages data assimilation

 11:    Level: beginner

 13:    Notes:
 14:    This is new code, please independently verify all results you obtain using it.

 16:    Some planned work for `PetscDA` is available as GitLab Issue #1882

 18:    Currently we supply two ensemble-based assimilators: `PETSCDAETKF` and `PETSCDALETKF`

 20: .seealso: [](ch_da), `PetscDAType`, `PETSCDAETKF`, `PETSCDALETKF`, `PetscDASqrtType`, `PetscDACreate()`, `PetscDASetType()`,
 21:           `PetscDASetSizes()`, `PetscDAEnsembleSetSize()`, `PetscDAEnsembleAnalysis()`, `PetscDAEnsembleForecast()`,
 22:           `PetscDADestroy()`, `PetscDAView()`
 23: S*/
 24: typedef struct _p_PetscDA *PetscDA;

 26: /*E
 27:   PetscDASqrtType - Type of square root of matrices to use the data assimilation algorithms

 29:   Values:
 30: +  `PETSCDA_SQRT_CHOLESKY` - Use the Cholesky factorization
 31: -  `PETSCDA_SQRT_EIGEN`    - Use the eigenvalue decomposition

 33:   Option Database Key:
 34: . -petscda_ensemble_sqrt_type <cholesky, eigen> - select the square root type at run time

 36:   Level: intermediate

 38: .seealso: [](ch_da), `PetscDA`, `PetscDAEnsembleSetSqrtType()`, `PetscDAEnsembleGetSqrtType()`
 39: E*/
 40: typedef enum {
 41:   PETSCDA_SQRT_CHOLESKY = 0,
 42:   PETSCDA_SQRT_EIGEN    = 1
 43: } PetscDASqrtType;

 45: /*J
 46:   PetscDAType - String with the name of a PETSc data assimilation method

 48:   Level: beginner

 50: .seealso: [](ch_da), `PetscDA`, `PetscDASetType()`, `PETSCDAETKF`, `PETSCDALETKF`
 51: J*/
 52: typedef const char *PetscDAType;
 53: #define PETSCDAETKF  "etkf"
 54: #define PETSCDALETKF "letkf"

 56: PETSC_EXTERN PetscErrorCode PetscDAInitializePackage(void);
 57: PETSC_EXTERN PetscErrorCode PetscDAFinalizePackage(void);

 59: PETSC_EXTERN PetscErrorCode PetscDARegister(const char[], PetscErrorCode (*)(PetscDA));
 60: PETSC_EXTERN PetscErrorCode PetscDARegisterAll(void);

 62: PETSC_EXTERN PetscErrorCode PetscDACreate(MPI_Comm, PetscDA *);
 63: PETSC_EXTERN PetscErrorCode PetscDADestroy(PetscDA *);
 64: PETSC_EXTERN PetscErrorCode PetscDASetType(PetscDA, PetscDAType);
 65: PETSC_EXTERN PetscErrorCode PetscDAGetType(PetscDA, PetscDAType *);
 66: PETSC_EXTERN PetscErrorCode PetscDAView(PetscDA, PetscViewer);
 67: PETSC_EXTERN PetscErrorCode PetscDAViewFromOptions(PetscDA, PetscObject, const char[]);
 68: PETSC_EXTERN PetscErrorCode PetscDASetFromOptions(PetscDA);

 70: PETSC_EXTERN PetscErrorCode PetscDASetSizes(PetscDA, PetscInt, PetscInt);
 71: PETSC_EXTERN PetscErrorCode PetscDASetLocalSizes(PetscDA, PetscInt, PetscInt);
 72: PETSC_EXTERN PetscErrorCode PetscDAGetSizes(PetscDA, PetscInt *, PetscInt *);
 73: PETSC_EXTERN PetscErrorCode PetscDASetNDOF(PetscDA, PetscInt);
 74: PETSC_EXTERN PetscErrorCode PetscDAGetNDOF(PetscDA, PetscInt *);
 75: PETSC_EXTERN PetscErrorCode PetscDASetUp(PetscDA);

 77: PETSC_EXTERN PetscErrorCode PetscDASetObsErrorVariance(PetscDA, Vec);
 78: PETSC_EXTERN PetscErrorCode PetscDAGetObsErrorVariance(PetscDA, Vec *);

 80: PETSC_EXTERN PetscErrorCode PetscDASetOptionsPrefix(PetscDA, const char[]);
 81: PETSC_EXTERN PetscErrorCode PetscDAAppendOptionsPrefix(PetscDA, const char[]);
 82: PETSC_EXTERN PetscErrorCode PetscDAGetOptionsPrefix(PetscDA, const char *[]);

 84: PETSC_EXTERN PetscErrorCode PetscDAEnsembleSetSize(PetscDA, PetscInt);
 85: PETSC_EXTERN PetscErrorCode PetscDAEnsembleGetSize(PetscDA, PetscInt *);
 86: PETSC_EXTERN PetscErrorCode PetscDAEnsembleSetInflation(PetscDA, PetscReal);
 87: PETSC_EXTERN PetscErrorCode PetscDAEnsembleGetInflation(PetscDA, PetscReal *);

 89: PETSC_EXTERN PetscErrorCode PetscDAEnsembleGetMember(PetscDA, PetscInt, Vec *);
 90: PETSC_EXTERN PetscErrorCode PetscDAEnsembleRestoreMember(PetscDA, PetscInt, Vec *);
 91: PETSC_EXTERN PetscErrorCode PetscDAEnsembleSetMember(PetscDA, PetscInt, Vec);

 93: PETSC_EXTERN PetscErrorCode PetscDAEnsembleComputeMean(PetscDA, Vec);
 94: PETSC_EXTERN PetscErrorCode PetscDAEnsembleComputeAnomalies(PetscDA, Vec, Mat *);
 95: PETSC_EXTERN PetscErrorCode PetscDAEnsembleAnalysis(PetscDA, Vec, Mat);
 96: PETSC_EXTERN PetscErrorCode PetscDAEnsembleForecast(PetscDA, PetscErrorCode (*)(Vec, Vec, PetscCtx), PetscCtx);
 97: PETSC_EXTERN PetscErrorCode PetscDAEnsembleInitialize(PetscDA, Vec, PetscReal, PetscRandom);

 99: PETSC_EXTERN PetscErrorCode PetscDAEnsembleComputeNormalizedInnovationMatrix(Mat, Vec, Vec, PetscInt, PetscScalar, Mat);
100: PETSC_EXTERN PetscErrorCode PetscDAEnsembleSetSqrtType(PetscDA, PetscDASqrtType);
101: PETSC_EXTERN PetscErrorCode PetscDAEnsembleGetSqrtType(PetscDA, PetscDASqrtType *);
102: PETSC_EXTERN PetscErrorCode PetscDAEnsembleTFactor(PetscDA, Mat);
103: PETSC_EXTERN PetscErrorCode PetscDAEnsembleApplyTInverse(PetscDA, Vec, Vec);
104: PETSC_EXTERN PetscErrorCode PetscDAEnsembleApplySqrtTInverse(PetscDA, Mat, Mat);

106: PETSC_EXTERN PetscErrorCode PetscDALETKFSetLocalization(PetscDA, Mat, Mat);
107: PETSC_EXTERN PetscErrorCode PetscDALETKFSetObsPerVertex(PetscDA, PetscInt);
108: PETSC_EXTERN PetscErrorCode PetscDALETKFGetObsPerVertex(PetscDA, PetscInt *);

110: #if defined(PETSC_HAVE_KOKKOS_KERNELS)
111: PETSC_EXTERN PetscErrorCode PetscDALETKFGetLocalizationMatrix(const PetscInt, const PetscInt, Vec[3], PetscReal[3], Mat, Mat *);
112: #endif