kml_fft(f)_mpi_plan_create

Create a plan for the three-dimensional C2C transform of a single contiguous data array.

Interface Definition

C interface:

kml_fft_plan kml_fft_mpi_plan_create(int backend, const int *inbox_low, const int *inbox_high, const int *inbox_order, const int *outbox_low, const int *outbox_high, const int *outbox_order, MPI_Comm comm, const kml_fft_mpi_options options);

kml_fftf_plan kml_fftf_mpi_plan_create(int backend, const int *inbox_low, const int *inbox_high, const int *inbox_order, const int *outbox_low, const int *outbox_high, const int *outbox_order, MPI_Comm comm, const kml_fftf_mpi_options options);

Return Value

The function returns a structure pointer of the kml_fft(f)_plan type. Pass this object to the kml_fft(f)_ mpi_execute_dft_ext function, kml_fft(f)_mpi_forward_c2c function, and kml_fft(f)_mpi_backward_c2c function as a parameter. The forward and backward directions can be reused. You do not need to specify the input and output buffers during plan creation.

If this function returns a non-null pointer, the plan has been successfully created. Otherwise, the plan fails to be created.

Parameters

Parameter	Data Type	Description	Input/Output
backend	int	Underlying library type. Currently, only BACKEND_KFFT is supported.	Input
inbox_low	const int *	It is a one-dimensional array with a length of 3. The lower limit of the input data in three dimensions is -1 ≤ inbox_low[i] ≤ n[i]-1 for i in 0, 1, and 2.	Input
inbox_high	const int *	It is a one-dimensional array with a length of 3. The upper limit of the input data in three dimensions is -1 ≤ inbox_high[i] ≤ n[i]-1 for i in 0, 1, 2, and 0 ≤ (inbox_high[i]-inbox_low[i]+1) ≤ n[i] for i in 0, 1, 2.	Input
inbox_order	const int *	It is a one-dimensional array with a length of 3, indicating the sequence of input data dimensions. The value is any combination of 0, 1, and 2. If this parameter is NULL, the default order is 0, 1, and 2.	Input
outbox_low	const int *	It is a one-dimensional array with a length of 3. The lower limit of the output data in the three dimensions is -1 ≤ outbox_low[i] ≤ n[i]-1 for i in 0, 1, and 2.	Input
outbox_high	const int *	It is a one-dimensional array with a length of 3. The upper limit of the output data in three dimensions is -1 ≤ outbox_high[i] ≤ n[i]-1 for i in 0, 1, and 2, and 0 ≤ (outbox_high[i] - outbox_low[i] + 1) ≤ n[i] for i in 0, 1, and 2.	Input
outbox_order	const int *	It is a one-dimensional array with a length of 3, indicating the sequence of output data dimensions. The value is any combination of 0, 1, and 2. If this parameter is NULL, the default order is 0, 1, and 2.	Input
comm	MPI_Comm	Communicator.	Input
options	Double precision: const kml_fft_mpi_options Single precision: const kml_fftf_mpi_options	Flag of the 3D FFT decomposition algorithm and communication algorithm.	Input

Dependencies

C: "kfft-mpi.h"

Examples

C interface:

    const int n0 = 4, n1 = 4, n2 = 4;
    kml_fft_plan plan;
    int provided;
    MPI_Init_thread(&argc, &argv, MPI_THREAD_MULTIPLE, &provided);
    MPI_Comm comm = MPI_COMM_WORLD;
    kml_fft_complex *in = NULL;
    kml_fft_complex *out = NULL;

    /* get local data size and allocate */
    ptrdiff_t low[3] = {0};
    ptrdiff_t high[3] = {0};
    ptrdiff_t n[3] = {n0, n1, n2};
    ptrdiff_t alloc_local = kml_fft_mpi_local_size_ext(3, n, comm, SCALFFT_DECOMPOSE_TYPE_PENCIL, low, high);
    if (alloc_local == -1) {
        printf("[%s][%d] allocate size fail.\n", __func__, __LINE__);
    }
    in = (kml_fft_complex *)kml_fft_malloc(sizeof(kml_fft_complex) * alloc_local);
    if (in == NULL) {
        printf("[%s][%d] malloc memory fail.\n", __func__, __LINE__);
    }
    out = (kml_fft_complex *)kml_fft_malloc(sizeof(kml_fft_complex) * alloc_local);
    if (out == NULL) {
        printf("[%s][%d] malloc memory fail.\n", __func__, __LINE__);
    }

    /* create plan */
    int low_int[3] = {low[0], low[1], low[2]};
    int high_int[3] = {high[0], high[1], high[2]};
    kml_fft_mpi_options options = {
        .a2a_algo    = A2A_ALGO_AUTO_TUNING,
        .decomp_type = SCALFFT_DECOMPOSE_TYPE_PENCIL
    };
    plan = kml_fft_mpi_plan_create(BACKEND_KFFT, low_int, high_int, NULL, low_int, high_int, NULL, comm, options);    

    /* execute plan */
    int scale = 0;
    kml_fft_mpi_execute_dft_ext(plan, in, out, scale, KML_FFT_FORWARD);
    kml_fft_mpi_execute_dft_ext(plan, out, in, scale, KML_FFT_BACKWARD);
    // kml_fft_mpi_forward_c2c(plan, in, out, scale);
    // kml_fft_mpi_backward_c2c(plan, out, in, scale);

    kml_fft_destroy_plan_ext(plan);

    kml_fft_free(in);
    kml_fft_free(out);
    MPI_Finalize();

Parent topic: C2C Transforms