Fortran Bindings

subroutine cpl_init(callingrealm, returned_realm_comm, ierror)

(cfd+md) Splits MPI_COMM_WORLD in both the CFD and MD code respectively and create intercommunicator between CFD and MD

Remarks

Assumes MPI has been initialised MPI_init and communicator MPI_COMM_WORLD exists and contains all processors in both CFD and MD regions

Synopsis

CPL_init(
         callingrealm,
         RETURNED_REALM_COMM,
         ierror
         )

Inputs

  • callingrealm
    • Should identify calling processor as either CFD_REALM (integer with value 1) or MD_REALM (integer with value 2).

Outputs

  • RETURNED_REALM_COMM
    • Communicator based on callingrealm value local to CFD or MD processor and resulting from the split of MPI_COMM_WORLD
  • ierror
    • Error flag

Example

program main_CFD
   use cpl, only : CPL_init
   use mpi
   implicit none

   integer :: rank, nprocs, ierr
   integer :: CFD_COMM
   integer, parameter :: CFD_realm=1

   !Initialise MPI
   call MPI_Init(ierr)

   !Create MD Comm by spliting world
   call CPL_init(CFD_realm, CFD_COMM, ierr)

   !get local processor rank and print
   call MPI_comm_size(CFD_COMM, nprocs, ierr)
   call MPI_comm_rank(CFD_COMM, rank, ierr)

   print*, "CFD code processor ", rank+1, " of ", nprocs

   !No need for seperate CPL finalise as MPI finalise takes care of this
   call MPI_finalize(ierr)

end program main_CFD
program main_MD
   use cpl, only : CPL_init
   use mpi
   implicit none

   integer :: rank, nprocs, ierr
   integer :: MD_COMM
   integer, parameter :: MD_realm=2

   !Initialise MPI
   call MPI_Init(ierr)

   !Create MD Comm by spliting world
   call CPL_init(MD_realm, MD_COMM, ierr)

   call MPI_comm_size(MD_COMM, nprocs, ierr)
   call MPI_comm_rank(MD_COMM, rank, ierr)

   print*, "MD code processor ", rank+1, " of ", nprocs

   !No need for seperate CPL finalise as MPI finalise takes care of this
   call MPI_finalize(ierr)

end program main_MD


Errors

COUPLER_ERROR_REALM = 1 ! wrong realm value COUPLER_ERROR_ONE_REALM = 2 ! one realm missing COUPLER_ERROR_INIT = 3 ! initialisation error
Parameters:
  • callingrealm [integer,in] :: CFD_REALM=1 or MD_REALM=2
  • returned_realm_comm [integer,out]
  • ierror [integer,out]
subroutine cpl_setup_md(nsteps, initialstep, dt, icomm_grid, xyzl, xyz_orig, density)

Initialisation routine for coupler module - Every variable is sent and stored to ensure both md and cfd region have an identical list of parameters

Remarks

Assumes CPL has been initialised CPL_init and communicator MD_REALM exists

Synopsis

coupler_md_init(
                nsteps,
                initialstep,
                dt,
                icomm_grid,
                xyzL,
                xyz_orig,
                density
                )

Inputs

  • nsteps
    • Number of steps in MD simulation.
  • initialstep
    • Initial steps in MD simulation.
  • dt
    • Timestep in MD simulation.
  • icomm_grid
    • Communicator based on MD processor topology returned from a call to MPI_CART_CREATE.
  • xyzL
    • MD domain size.
  • xyz_orig
    • MD origin.
  • density
    • Density of molecules in MD code.
Parameters:
  • nsteps [integer,inout]
  • initialstep [integer,inout]
  • dt [real,in]
  • icomm_grid [integer,in]
  • xyzl (3) [real,in]
  • xyz_orig (3) [real,in]
  • density [real,in]
subroutine cpl_setup_cfd(nsteps, dt, icomm_grid, xyzl, xyz_orig, ncxyz, density)

Initialisation routine for coupler module - Every variable is sent and stored to ensure both md and cfd region have an identical list of parameters

Remarks

Assumes CPL has been initialised CPL_init and communicator MD_REALM exists

Synopsis

coupler_cfd_init(
                nsteps,
                dt_cfd,
                icomm_grid,
                xyzL,
                xyz_orig,
                ncxyz,
                density
                )

Inputs

  • nsteps (inout)
    • Number of steps in CFD simulation.
  • dt_cfd (inout)
    • Timestep in CFD simulation.
  • icomm_grid
    • Communicator based on CFD processor topology returned from a call to MPI_CART_CREATE.
  • xyzL
    • CFD domain size.
  • xyz_orig
    • CFD origin.
  • ncxyz
    • Number of CFD cells in global domain.
  • density
    • Density used in CFD code (still required when working with non-dimensionalised units in CFD as MD has an actual value of density based on domain.).
Parameters:
  • nsteps [integer,in]
  • dt [real,in]
  • icomm_grid [integer,in]
  • xyzl (3) [real,in]
  • xyz_orig (3) [real,in]
  • ncxyz (3) [integer,in]
  • density [real,in]
subroutine cpl_send(asend, limits[, send_flag])

Send four dimensional array asend of data from all processors in the current realm with data between global cell array limits to the corresponding processors from the other realm.

Remarks

Assumes the coupler has been initialised with CPL_init and topological mapping has been setup using either CPL_setup_md or CPL_setup_cfd as appropriate.

Synopsis

CPL_send(
         asend,
         limits,
         send_flag
         )

Inputs

  • asend
    • Array of data to send. Should be a four dimensional array allocated using the number of cells on the current processor between the limits. Size should be be obtained from CPL_my_proc_portion(limits, portion).
  • limits
    • Limits in global cell coordinates, must be the same as corresponding recieve

Outputs

  • send_flag
    • Returned flag which indicates success or failure of send process

Example

call CPL_get_olap_limits(limits)
call CPL_my_proc_portion(limits, portion)
call CPL_get_no_cells(portion, Ncells)

!Coupled Send array
allocate(A(3, Ncells(1), Ncells(2), Ncells(3)))

do i =portion(1),portion(2)
do j =portion(3),portion(4)
do k =portion(5),portion(6)
   ii = i-portion(1)+1; jj = j-portion(3)+1; kk = k-portion(5)+1
   A(1,ii,jj,kk) = dble(i)
   A(2,ii,jj,kk) = dble(j)
   A(3,ii,jj,kk) = dble(k)
enddo
enddo
enddo
call CPL_send(A, limits, send_flag)
Parameters:
  • asend (*,*,*,*) [real,in] :: Array containing data to send
  • limits (6) [integer,in] :: Global cell indices with minimum and maximum values to send
Options:

send_flag [logical,out,optional] :: Flag set if processor has passed data

subroutine cpl_recv(arecv, limits[, recv_flag])

Receive data from to local grid from the associated ranks from the other realm

Remarks

Assumes the coupler has been initialised with CPL_init and topological mapping has been setup using either CPL_setup_md or CPL_setup_cfd as appropriate.

Synopsis

CPL_send(
         arecv,
         limits,
         recv_flag
         )

Inputs

  • arecv
    • Array of data to recv. Should be a four dimensional array allocated using the number of cells on the current processor between the limits. Size should be be obtained from CPL_my_proc_portion(limits, portion).
  • limits
    • Limits in global cell coordinates, must be the same as corresponding send

Outputs

  • recv_flag
    • Returned flag which indicates success or failure of recv process

Example

call CPL_get_olap_limits(limits)
call CPL_my_proc_portion(limits, portion)
call CPL_get_no_cells(portion, Ncells)

!Coupled Recieve
allocate(A(3, Ncells(1), Ncells(2), Ncells(3)))
call CPL_recv(A, limits, recv_flag)
Parameters:
  • arecv (*,*,*,*) [real,inout] :: Pre allocated array that recieves data
  • limits (6) [integer,in] :: Global cell indices with minimum and maximum values to recv
Options:

recv_flag [logical,out,optional] :: Flag set if processor has received data

subroutine cpl_proc_extents(coord, realm, extents[, ncells])
Parameters:
  • coord (3) [integer,in]
  • realm [integer,in]
  • extents (6) [integer,out]
Options:

ncells [integer,out,optional]

subroutine cpl_my_proc_extents(extents)
Parameters:extents (6) [integer,out]
subroutine cpl_proc_portion(coord, realm, limits, portion[, ncells])

Get maximum and minimum cell indices, i.e. the ‘portion’, of the input cell extents ‘limits’ that is contributed by the processor specified by processor coord.

Remarks

Assumes the coupler has been initialised with CPL_init and topological mapping has been setup using either CPL_setup_md or CPL_setup_cfd as appropriate.

  • Note: limits(6) and portion(6) are of the form: (xmin,xmax,ymin,ymax,zmin,zmax)

Synopsis

CPL_proc_portion(
                 coord,
                 realm,
                 limits,
                 portion,
                 ncells
                 )

Inputs

  • coord
    • processor cartesian coordinate (3 x integer)
  • realm
    • cfd_realm (1) or md_realm (2) (integer)
  • limits
    • Array of cell extents that specify the input region.

Outputs

  • portion - Array of cell extents that define the local processor’s

    contribution to the input region ‘limits’.

  • ncells (optional)
    • number of cells in portion (integer)
Parameters:
  • coord (3) [integer,in]
  • realm [integer,in]
  • limits (6) [integer,in]
  • portion (6) [integer,out]
Options:

ncells [integer,out,optional]

subroutine cpl_my_proc_portion(limits, portion)

Get maximum and minimum cell indices, i.e. the ‘portion’, of the input cell extents ‘limits’ that is contributed by calling processor.

Remarks

Assumes the coupler has been initialised with CPL_init and topological mapping has been setup using either CPL_setup_md or CPL_setup_cfd as appropriate.

  • Note: limits(6) and portion(6) are of the form: (xmin,xmax,ymin,ymax,zmin,zmax)

Synopsis

CPL_proc_portion(
                 limits,
                 portion,
                 )

Inputs

  • limits
    • Array of cell extents that specify the input region.

Outputs

  • portion - Array of cell extents that define the local processor’s

    contribution to the input region ‘limits’.

Parameters:
  • limits (6) [integer,in]
  • portion (6) [integer,out]
function cpl_map_coord2cell(x, y, z, cell_ijk)
Parameters:
  • x [real,in]
  • y [real,in]
  • z [real,in]
  • cell_ijk (3) [integer,out]
Return:

ret [logical]

subroutine cpl_map_cell2coord(i, j, k, coord_xyz)
Parameters:
  • i [integer,in]
  • j [integer,in]
  • k [integer,in]
  • coord_xyz (3) [real,out]
subroutine cpl_get_no_cells(limits, no_cells)
Parameters:
  • limits (6) [integer,in]
  • no_cells (3) [integer,out]
function cpl_map_glob2loc_cell(limits, glob_cell, loc_cell)
Parameters:
  • limits (6) [integer,in]
  • glob_cell (3) [integer,in]
  • loc_cell (3) [integer,out]
Return:

ret [logical]

subroutine cpl_get_olap_limits(limits)
Parameters:limits (6) [integer,out]
subroutine cpl_get_cnst_limits(limits)
Parameters:limits (6) [integer,out]
function cpl_map_cfd2md_coord(coord_cfd, coord_md)
Parameters:
  • coord_cfd (3) [real,in]
  • coord_md (3) [real,out]
Return:

valid_coord [logical]

function cpl_map_md2cfd_coord(coord_md, coord_cfd)
Parameters:
  • coord_md (3) [real,in]
  • coord_cfd (3) [real,out]
Return:

valid_coord [logical]

function cpl_overlap()
Return:p [logical]