Actual source code: productutils.c

      1: #include <petsc/private/dmproductimpl.h>

      3: /*@
      4:   DMProductGetDM - Get sub-`DM` whose coordinates will be associated with a particular dimension of the `DMPRODUCT`

      6:   Not Collective

      8:   Input Parameters:
      9: + dm   - the` DMPRODUCT`
     10: - slot - which dimension within `DMPRODUCT` whose coordinates is being provided, in the range 0 to $dim-1$

     12:   Output Parameter:
     13: . subdm - the sub-`DM`

     15:   Level: advanced

     17:   Note:
     18:   You can call `DMProductGetDimensionIndex()` to determine which dimension in `subdm` is to be used to provide the coordinates, see `DMPRODUCT`

     20: .seealso: `DMPRODUCT`, `DMProductSetDM()`, `DMProductGetDimensionIndex()`, `DMProductSetDimensionIndex()`
     21: @*/
     22: PetscErrorCode DMProductGetDM(DM dm, PetscInt slot, DM *subdm)
     23: {
     24:   DM_Product *product = (DM_Product *)dm->data;
     25:   PetscInt    dim;

     27:   PetscFunctionBegin;
     29:   PetscCall(DMGetDimension(dm, &dim));
     30:   PetscCheck(slot < dim && slot >= 0, PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "slot number must be in range 0-%" PetscInt_FMT, dim - 1);
     31:   *subdm = product->dm[slot];
     32:   PetscFunctionReturn(PETSC_SUCCESS);
     33: }

     35: /*@
     36:   DMProductSetDM - Set sub-`DM` whose coordinates will be associated with a particular dimension of the `DMPRODUCT`

     38:   Not Collective

     40:   Input Parameters:
     41: + dm    - the `DMPRODUCT`
     42: . slot  - which dimension within `DMPRODUCT` whose coordinates is being provided, in the range 0 to $dim-1$
     43: - subdm - the sub-`DM`

     45:   Level: advanced

     47:   Notes:
     48:   This function does not destroy the provided sub-`DM`. You may safely destroy it after calling this function.

     50:   You can call `DMProductSetDimensionIndex()` to determine which dimension in `subdm` is to be used to provide the coordinates, see `DMPRODUCT`

     52: .seealso: `DMPRODUCT`, `DMProductGetDM()`, `DMProductSetDimensionIndex()`, `DMProductGetDimensionIndex()`
     53: @*/
     54: PetscErrorCode DMProductSetDM(DM dm, PetscInt slot, DM subdm)
     55: {
     56:   DM_Product *product = (DM_Product *)dm->data;
     57:   PetscInt    dim;

     59:   PetscFunctionBegin;
     61:   PetscCall(DMGetDimension(dm, &dim));
     62:   PetscCheck(slot < dim && slot >= 0, PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "slot number must be in range 0-%" PetscInt_FMT, dim - 1);
     63:   PetscCall(PetscObjectReference((PetscObject)subdm));
     64:   PetscCall(DMDestroy(&product->dm[slot]));
     65:   product->dm[slot] = subdm;
     66:   PetscFunctionReturn(PETSC_SUCCESS);
     67: }

     69: /*@
     70:   DMProductSetDimensionIndex - Set which dimension `idx` of the sub-`DM` coordinates will be used associated with the `DMPRODUCT` dimension `slot`

     72:   Not Collective

     74:   Input Parameters:
     75: + dm   - the `DMPRODUCT`
     76: . slot - which dimension, in the range 0 to $dim-1$ you are providing to the `dm`
     77: - idx  - the dimension of the sub-`DM` to use

     79:   Level: advanced

     81: .seealso: `DMPRODUCT`, `DMProductGetDM()`, `DMProductGetDimensionIndex()`
     82: @*/
     83: PetscErrorCode DMProductSetDimensionIndex(DM dm, PetscInt slot, PetscInt idx)
     84: {
     85:   DM_Product *product = (DM_Product *)dm->data;
     86:   PetscInt    dim;

     88:   PetscFunctionBegin;
     90:   PetscCall(DMGetDimension(dm, &dim));
     91:   PetscCheck(slot < dim && slot >= 0, PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "slot number must be in range 0-%" PetscInt_FMT, dim - 1);
     92:   product->dim[slot] = idx;
     93:   PetscFunctionReturn(PETSC_SUCCESS);
     94: }

     96: /*@
     97:   DMProductGetDimensionIndex - Get which dimension `idx` of the sub-`DM` coordinates will be used associated with the `DMPRODUCT` dimension `slot`

     99:   Not Collective

    101:   Input Parameters:
    102: + dm   - the `DMPRODUCT`
    103: - slot - which dimension, in the range 0 to $dim-1$ of `dm`

    105:   Output Parameter:
    106: . idx - the dimension of the sub-`DM`

    108:   Level: advanced

    110: .seealso: `DMPRODUCT`, `DMProductGetDM()`, `DMProductSetDimensionIndex()`
    111: @*/
    112: PetscErrorCode DMProductGetDimensionIndex(DM dm, PetscInt slot, PetscInt *idx)
    113: {
    114:   DM_Product *product = (DM_Product *)dm->data;
    115:   PetscInt    dim;

    117:   PetscFunctionBegin;
    119:   PetscCall(DMGetDimension(dm, &dim));
    120:   PetscAssertPointer(idx, 3);
    121:   PetscCheck(slot < dim && slot >= 0, PetscObjectComm((PetscObject)dm), PETSC_ERR_ARG_OUTOFRANGE, "slot number must be in range 0-%" PetscInt_FMT, dim - 1);
    122:   *idx = product->dim[slot];
    123:   PetscFunctionReturn(PETSC_SUCCESS);
    124: }