Date: 2025-03-29T05:58:34+00:00

Actual source code: matmpidensehip.hip.cpp

      1: #include "../matmpidensecupm.hpp"

      3: using namespace Petsc::mat::cupm;
      4: using Petsc::device::cupm::DeviceType;

      6: static constexpr impl::MatDense_MPI_CUPM<DeviceType::HIP> mat_cupm{};

      8: /*MC
      9:   MATDENSEHIP - "densehip" - A matrix type to be used for dense matrices on GPUs.

     11:   This matrix type is identical to `MATSEQDENSEHIP` when constructed with a single process
     12:   communicator, and `MATMPIDENSEHIP` otherwise.

     14:   Options Database Key:
     15: . -mat_type densehip - sets the matrix type to `MATDENSEHIP` during a call to
     16:                         `MatSetFromOptions()`

     18:   Level: beginner

     20: .seealso: [](ch_matrices), `Mat`, `MATSEQDENSEHIP`, `MATMPIDENSEHIP`, `MATSEQDENSECUDA`,
     21: `MATMPIDENSECUDA`, `MATDENSE`
     22: M*/

     24: /*MC
     25:   MATMPIDENSEHIP - "mpidensehip" - A matrix type to be used for distributed dense matrices on
     26:   GPUs.

     28:   Options Database Key:
     29: . -mat_type mpidensehip - sets the matrix type to `MATMPIDENSEHIP` during a call to
     30:                            `MatSetFromOptions()`

     32:   Level: beginner

     34: .seealso: [](ch_matrices), `Mat`, `MATDENSEHIP`, `MATMPIDENSE`, `MATSEQDENSE`,
     35: `MATSEQDENSEHIP`, `MATSEQDENSECUDA`
     36: M*/
     37: PETSC_INTERN PetscErrorCode MatCreate_MPIDenseHIP(Mat A)
     38: {
     39:   PetscFunctionBegin;
     40:   PetscCall(mat_cupm.Create(A));
     41:   PetscFunctionReturn(PETSC_SUCCESS);
     42: }

     44: PetscErrorCode MatConvert_MPIDense_MPIDenseHIP(Mat A, MatType type, MatReuse reuse, Mat *ret)
     45: {
     46:   PetscFunctionBegin;
     47:   PetscCall(mat_cupm.Convert_MPIDense_MPIDenseCUPM(A, type, reuse, ret));
     48:   PetscFunctionReturn(PETSC_SUCCESS);
     49: }

     51: /*@C
     52:   MatCreateDenseHIP - Creates a matrix in `MATDENSEHIP` format using HIP.

     54:   Collective

     56:   Input Parameters:
     57: + comm - MPI communicator
     58: . m    - number of local rows (or `PETSC_DECIDE` to have calculated if `M` is given)
     59: . n    - number of local columns (or `PETSC_DECIDE` to have calculated if `N` is given)
     60: . M    - number of global rows (or `PETSC_DECIDE` to have calculated if `m` is given)
     61: . N    - number of global columns (or `PETSC_DECIDE` to have calculated if `n` is given)
     62: - data - optional location of GPU matrix data. Pass `NULL` to have PETSc to control matrix
     63:          memory allocation.

     65:   Output Parameter:
     66: . A - the matrix

     68:   Level: intermediate

     70: .seealso: `MATDENSEHIP`, `MatCreate()`, `MatCreateDense()`
     71: @*/
     72: PetscErrorCode MatCreateDenseHIP(MPI_Comm comm, PetscInt m, PetscInt n, PetscInt M, PetscInt N, PetscScalar *data, Mat *A)
     73: {
     74:   PetscFunctionBegin;
     75:   PetscCall(MatCreateDenseCUPM<DeviceType::HIP>(comm, m, n, M, N, data, A));
     76:   PetscFunctionReturn(PETSC_SUCCESS);
     77: }

     79: /*@C
     80:   MatDenseHIPPlaceArray - Allows one to replace the GPU array in a `MATDENSEHIP` matrix with an
     81:   array provided by the user. This is useful to avoid copying an array into a matrix.

     83:   Not Collective

     85:   Input Parameters:
     86: + mat   - the matrix
     87: - array - the array in column major order

     89:   Level: developer

     91:   Note:
     92:   Adding `const` to `array` was an oversight, see notes in `VecPlaceArray()`.

     94:   You can return to the original array with a call to `MatDenseHIPResetArray()`. The user is
     95:   responsible for freeing this array; it will not be freed when the matrix is destroyed. The
     96:   array must have been allocated with `hipMalloc()`.

     98: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPResetArray()`,
     99: `MatDenseHIPReplaceArray()`
    100: @*/
    101: PetscErrorCode MatDenseHIPPlaceArray(Mat mat, const PetscScalar *array)
    102: {
    103:   PetscFunctionBegin;
    104:   PetscCall(MatDenseCUPMPlaceArray<DeviceType::HIP>(mat, array));
    105:   PetscFunctionReturn(PETSC_SUCCESS);
    106: }

    108: /*@C
    109:   MatDenseHIPResetArray - Resets the matrix array to that it previously had before the call to
    110:   `MatDenseHIPPlaceArray()`

    112:   Not Collective

    114:   Input Parameter:
    115: . mat - the matrix

    117:   Level: developer

    119:   Note:
    120:   You can only call this after a call to `MatDenseHIPPlaceArray()`

    122: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPPlaceArray()`
    123: @*/
    124: PetscErrorCode MatDenseHIPResetArray(Mat mat)
    125: {
    126:   PetscFunctionBegin;
    127:   PetscCall(MatDenseCUPMResetArray<DeviceType::HIP>(mat));
    128:   PetscFunctionReturn(PETSC_SUCCESS);
    129: }

    131: /*@C
    132:   MatDenseHIPReplaceArray - Allows one to replace the GPU array in a `MATDENSEHIP` matrix
    133:   with an array provided by the user. This is useful to avoid copying an array into a matrix.

    135:   Not Collective

    137:   Input Parameters:
    138: + mat   - the matrix
    139: - array - the array in column major order

    141:   Level: developer

    143:   Note:
    144:   Adding `const` to `array` was an oversight, see notes in `VecPlaceArray()`.

    146:   This permanently replaces the GPU array and frees the memory associated with the old GPU
    147:   array. The memory passed in CANNOT be freed by the user. It will be freed when the matrix is
    148:   destroyed. The array should respect the matrix leading dimension.

    150: .seealso: `MatDenseHIPGetArray()`, `MatDenseHIPPlaceArray()`, `MatDenseHIPResetArray()`
    151: @*/
    152: PetscErrorCode MatDenseHIPReplaceArray(Mat mat, const PetscScalar *array)
    153: {
    154:   PetscFunctionBegin;
    155:   PetscCall(MatDenseCUPMReplaceArray<DeviceType::HIP>(mat, array));
    156:   PetscFunctionReturn(PETSC_SUCCESS);
    157: }

    159: /*@C
    160:   MatDenseHIPGetArrayWrite - Provides write access to the HIP buffer inside a `MATDENSEHIP`
    161:   matrix.

    163:   Not Collective

    165:   Input Parameter:
    166: . A - the matrix

    168:   Output Parameter:
    169: . a - the GPU array in column major order

    171:   Level: developer

    173:   Notes:
    174:   The data on the GPU may not be updated due to operations done on the CPU. If you need updated
    175:   data, use `MatDenseHIPGetArray()`.

    177:   The array must be restored with `MatDenseHIPRestoreArrayWrite()` when no longer needed.

    179: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPRestoreArray()`,
    180: `MatDenseHIPRestoreArrayWrite()`, `MatDenseHIPGetArrayRead()`,
    181: `MatDenseHIPRestoreArrayRead()`
    182: @*/
    183: PetscErrorCode MatDenseHIPGetArrayWrite(Mat A, PetscScalar **a)
    184: {
    185:   PetscFunctionBegin;
    186:   PetscCall(MatDenseCUPMGetArrayWrite<DeviceType::HIP>(A, a));
    187:   PetscFunctionReturn(PETSC_SUCCESS);
    188: }

    190: /*@C
    191:   MatDenseHIPRestoreArrayWrite - Restore write access to the HIP buffer inside a
    192:   `MATDENSEHIP` matrix previously obtained with `MatDenseHIPGetArrayWrite()`.

    194:   Not Collective

    196:   Input Parameters:
    197: + A - the matrix
    198: - a - the GPU array in column major order

    200:   Level: developer

    202: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPRestoreArray()`,
    203: `MatDenseHIPGetArrayWrite()`, `MatDenseHIPRestoreArrayRead()`, `MatDenseHIPGetArrayRead()`
    204: @*/
    205: PetscErrorCode MatDenseHIPRestoreArrayWrite(Mat A, PetscScalar **a)
    206: {
    207:   PetscFunctionBegin;
    208:   PetscCall(MatDenseCUPMRestoreArrayWrite<DeviceType::HIP>(A, a));
    209:   PetscFunctionReturn(PETSC_SUCCESS);
    210: }

    212: /*@C
    213:   MatDenseHIPGetArrayRead - Provides read-only access to the HIP buffer inside a
    214:   `MATDENSEHIP` matrix. The array must be restored with `MatDenseHIPRestoreArrayRead()` when
    215:   no longer needed.

    217:   Not Collective

    219:   Input Parameter:
    220: . A - the matrix

    222:   Output Parameter:
    223: . a - the GPU array in column major order

    225:   Level: developer

    227:   Note:
    228:   Data may be copied to the GPU due to operations done on the CPU. If you need write only
    229:   access, use `MatDenseHIPGetArrayWrite()`.

    231: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPRestoreArray()`,
    232: `MatDenseHIPRestoreArrayWrite()`, `MatDenseHIPGetArrayWrite()`,
    233: `MatDenseHIPRestoreArrayRead()`
    234: @*/
    235: PetscErrorCode MatDenseHIPGetArrayRead(Mat A, const PetscScalar **a)
    236: {
    237:   PetscFunctionBegin;
    238:   PetscCall(MatDenseCUPMGetArrayRead<DeviceType::HIP>(A, a));
    239:   PetscFunctionReturn(PETSC_SUCCESS);
    240: }

    242: /*@C
    243:   MatDenseHIPRestoreArrayRead - Restore read-only access to the HIP buffer inside a
    244:   `MATDENSEHIP` matrix previously obtained with a call to `MatDenseHIPGetArrayRead()`.

    246:   Not Collective

    248:   Input Parameters:
    249: + A - the matrix
    250: - a - the GPU array in column major order

    252:   Level: developer

    254:   Note:
    255:   Data can be copied to the GPU due to operations done on the CPU. If you need write only
    256:   access, use `MatDenseHIPGetArrayWrite()`.

    258: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPRestoreArray()`,
    259: `MatDenseHIPRestoreArrayWrite()`, `MatDenseHIPGetArrayWrite()`, `MatDenseHIPGetArrayRead()`
    260: @*/
    261: PetscErrorCode MatDenseHIPRestoreArrayRead(Mat A, const PetscScalar **a)
    262: {
    263:   PetscFunctionBegin;
    264:   PetscCall(MatDenseCUPMRestoreArrayRead<DeviceType::HIP>(A, a));
    265:   PetscFunctionReturn(PETSC_SUCCESS);
    266: }

    268: /*@C
    269:   MatDenseHIPGetArray - Provides access to the HIP buffer inside a `MATDENSEHIP` matrix. The
    270:   array must be restored with `MatDenseHIPRestoreArray()` when no longer needed.

    272:   Not Collective

    274:   Input Parameter:
    275: . A - the matrix

    277:   Output Parameter:
    278: . a - the GPU array in column major order

    280:   Level: developer

    282:   Note:
    283:   Data can be copied to the GPU due to operations done on the CPU. If you need write only
    284:   access, use `MatDenseHIPGetArrayWrite()`. For read-only access, use
    285:   `MatDenseHIPGetArrayRead()`.

    287: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArrayRead()`, `MatDenseHIPRestoreArray()`,
    288: `MatDenseHIPRestoreArrayWrite()`, `MatDenseHIPGetArrayWrite()`,
    289: `MatDenseHIPRestoreArrayRead()`
    290: @*/
    291: PetscErrorCode MatDenseHIPGetArray(Mat A, PetscScalar **a)
    292: {
    293:   PetscFunctionBegin;
    294:   PetscCall(MatDenseCUPMGetArray<DeviceType::HIP>(A, a));
    295:   PetscFunctionReturn(PETSC_SUCCESS);
    296: }

    298: /*@C
    299:   MatDenseHIPRestoreArray - Restore access to the HIP buffer inside a `MATDENSEHIP` matrix
    300:   previously obtained with `MatDenseHIPGetArray()`.

    302:   Not Collective

    304:   Level: developer

    306:   Input Parameters:
    307: + A - the matrix
    308: - a - the GPU array in column major order

    310: .seealso: `MATDENSEHIP`, `MatDenseHIPGetArray()`, `MatDenseHIPRestoreArrayWrite()`,
    311: `MatDenseHIPGetArrayWrite()`, `MatDenseHIPRestoreArrayRead()`, `MatDenseHIPGetArrayRead()`
    312: @*/
    313: PetscErrorCode MatDenseHIPRestoreArray(Mat A, PetscScalar **a)
    314: {
    315:   PetscFunctionBegin;
    316:   PetscCall(MatDenseCUPMRestoreArray<DeviceType::HIP>(A, a));
    317:   PetscFunctionReturn(PETSC_SUCCESS);
    318: }

    320: /*@C
    321:   MatDenseHIPSetPreallocation - Set the device array used for storing the matrix elements of a
    322:   `MATDENSEHIP` matrix

    324:   Collective

    326:   Input Parameters:
    327: + A            - the matrix
    328: - device_array - the array (or `NULL`)

    330:   Level: intermediate

    332: .seealso: [](ch_matrices), `Mat`, `MATDENSEHIP`, `MatCreate()`, `MatCreateDenseHIP()`,
    333: `MatSetValues()`, `MatDenseSetLDA()`
    334: @*/
    335: PetscErrorCode MatDenseHIPSetPreallocation(Mat A, PetscScalar *device_array)
    336: {
    337:   PetscFunctionBegin;
    338:   PetscCall(MatDenseCUPMSetPreallocation<DeviceType::HIP>(A, device_array));
    339:   PetscFunctionReturn(PETSC_SUCCESS);
    340: }