pm_parallelism Module Reference

This module contains procedures and generic interfaces for facilitating parallel computations or computing the performance of the parallel Coarray/MPI/OpenMP algorithms. More...

Data Types
type	image_type
	This is the image_type type for generating objects that contain information about the current image/processor/thread and facilitate its synchronization with other processes, or the global finalization of all inter-process parallel communications (e.g., as is done in MPI applications). More...
type	imageis_type
	This is the imageis_type type for generating objects with components of type logical of default kind LK that contain information about the current image/processor/thread. More...
interface	setForkJoinScaling
	Return the predicted parallel Fork-Join speedup scaling behavior for simulations whose image contributions are stochastically accepted only from the first successful image starting from image ID 1. More...

Functions/Subroutines
type(image_type) function	image_typer ()
	Generate and return an object of class image_type containing information and statistics of the parallel images/processes/threads available, depending on the type of parallelism requested. More...
subroutine	setImageSynced ()
	Synchronize all existing parallel images and return nothing. More...
subroutine	setImageFinalized ()
	Finalize the current parallel simulation and return nothing. More...
integer(IK) function	getImageID ()
	Generate and return the ID of the current Coarray image / MPI process / OpenMP thread, all starting with 1. More...
integer(IK) function	getImageCount ()
	Generate and return the number of available processes in the current parallel world communication. More...
integer(IK) integer(IK) function	getImageCountMPI ()
	Generate and return the number of available processes in the current MPI-parallel world communication. More...
integer(IK) integer(IK) function	getImageCountOMP ()
	Generate and return the number of available processes in the current OpenMP-parallel world communication. More...
subroutine	setImageCount (count)
	Set the number the parallel threads for an OpenMP-enabled application. More...
logical(LK) function	isFailedImage (failed)
	Broadcast the error condition from all images/processes to all images/processes. More...

Variables
character(*, SK), parameter	MODULE_NAME = SK_"@pm_parallelism"
character(*, SK), parameter	PARALLELIZATION_MODE = SK_"parallel"
	The scalar constant of type character of default kind SK, whose value is set to parallel if the ParaMonte library is built with the preprocessor macro -DCAF_ENABLED=1 -DMPI_ENABLED=1, otherwise, it is set to "serial". More...

Detailed Description

This module contains procedures and generic interfaces for facilitating parallel computations or computing the performance of the parallel Coarray/MPI/OpenMP algorithms.

A primary goal for the design of this type and the associated procedures is to facilitate parallelism-agnostic coding within a codebase.
As such, the attributes and procedures within this module are guaranteed to also work in serial applications.
However, the procedures of this module typically do nothing when the application is serial or the parallelism is not recognized.

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Function/Subroutine Documentation

getImageCount()

integer(IK) function pm_parallelism::getImageCount

Generate and return the number of available processes in the current parallel world communication.

Returns

imageCount : The output scalar integer of default kind IK representing the number of available processes in the current world communication.
The output imageCount is set to,

1. the value returned by the Fortran intrinsic num_images() in Coarray parallel applications,
2. the value returned by mpi_comm_size() subroutine in MPI parallel applications,
3. the value returned by omp_get_num_threads() in OpenMP parallel applications,
4. the value 1 in serial applications,

Warning

For OpenMP-enabled ParaMonte library builds, this routine return the value of the OpenMP-intrinsic omp_get_num_threads() routine, that is, the number of threads in the team that is executing the parallel region to which the routine region binds.
If this generic interface is called from the sequential part of an OpenMP-enabled program, this routine returns 1.
To return a value larger than 1, this routine must be called from within an OpenMP-enabled parallel region.
The desired number of OpenMP threads can be set at runtime via setImageCount(), or directly via the OpenMP intrinsic subroutine omp_set_num_threads().

Possible calling interfaces ⛓

use pm_kind, only: IK
use pm_parallelism, only: getImageCount
integer(IK) :: imageCount
 
imageCount = getImageCount()

Warning

See the warnings associated with getImageCountMPI.

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 4:13 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 599 of file pm_parallelism.F90.

References getImageCountMPI(), and getImageCountOMP().

Referenced by image_typer().

Here is the call graph for this function:

Here is the caller graph for this function:

getImageCountMPI()

integer(IK) integer(IK) function pm_parallelism::getImageCountMPI

Generate and return the number of available processes in the current MPI-parallel world communication.

Returns

imageCount : The output scalar integer of default kind IK representing the number of available processes in the current MPI-parallel world communication.
The output imageCount is set to,

1. the value returned by mpi_comm_size() subroutine in MPI parallel applications,
2. the value 0 if the ParaMonte library build is not for MPI applications,

Possible calling interfaces ⛓

use pm_kind, only: IK
use pm_parallelism, only: getImageCountMPI
integer(IK) :: imageCount
 
imageCount = getImageCountMPI()

Warning

The MPI library must be initialized and not finalized prior to calling this routine for MPI-parallel applications.
Otherwise, the MPI library will automatically be initialized, which may fail if it has been already finalized.

Note

Th C-binding of this routine is required for automatic detection of the use of mpiexec launcher in dynamic programming languages.

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 4:13 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 654 of file pm_parallelism.F90.

Referenced by getImageCount().

Here is the caller graph for this function:

getImageCountOMP()

integer(IK) integer(IK) function pm_parallelism::getImageCountOMP

Generate and return the number of available processes in the current OpenMP-parallel world communication.

Returns

imageCount : The output scalar integer of default kind IK representing the number of available processes in the current OpenMP-parallel world communication.
The output imageCount is set to,

1. the value returned by mpi_comm_size() subroutine in OpenMP parallel applications,
2. the value 0 if the ParaMonte library build is not for OpenMP applications,

Possible calling interfaces ⛓

use pm_kind, only: IK
use pm_parallelism, only: getImageCountOMP
integer(IK) :: imageCount
 
imageCount = getImageCountOMP()

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 4:13 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 712 of file pm_parallelism.F90.

Referenced by getImageCount().

Here is the caller graph for this function:

getImageID()

integer(IK) function pm_parallelism::getImageID

Generate and return the ID of the current Coarray image / MPI process / OpenMP thread, all starting with 1.

Returns

imageID : The output scalar integer of default kind IK representing the ID of the current image/process/thread.
The output imageID is set to,

1. The value returned by this_image() in Coarray applications,
2. The value returned by mpi_comm_rank() + 1 in MPI applications,
3. The value returned by omp_get_thread_num() + 1 in OpenMP applications,
4. The value 1 in serial applications,

Possible calling interfaces ⛓

use pm_parallelism, only: getImageID
use pm_kind, only: IK
integer(IK) :: id
 
id = getImageID() ! The ID (starting at 1) of the current Coarray image, MPI process, or OpenMP thread.
!

Warning

The MPI library must be initialized and not finalized prior to calling this routine for MPI-parallel applications.
Otherwise, the MPI library will automatically be initialized, which may fail if it has been already finalized.

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 4:13 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 523 of file pm_parallelism.F90.

Referenced by image_typer().

Here is the caller graph for this function:

image_typer()

type(image_type) function pm_parallelism::image_typer

Generate and return an object of class image_type containing information and statistics of the parallel images/processes/threads available, depending on the type of parallelism requested.

This procedure is the constructor of the type image_type.
See the documentation of image_type for further details and example usage.

Returns

image : The output scalar of type image_type.

Possible calling interfaces ⛓

use pm_parallelism, only: image_type
type(image_type) :: image
 
image = image_type()

Warning

Even when the application is MPI/OpenMP-parallel, the id assigned to the zeroth process is 1 in this type.
This convention follows the rules of the Fortran Coarray parallel programming language.

For OpenMP-enabled ParaMonte library builds, this routine return the value of the OpenMP-intrinsic omp_get_num_threads() routine, that is, the number of threads in the team that is executing the parallel region to which the routine region binds.
If this constructor is called from the sequential part of an OpenMP-enabled program, this routine returns 1.
To return a value larger than 1, this routine must be called from within an OpenMP-enabled parallel region.
The desired number of OpenMP threads can be set at runtime via setImageCount(), or directly via the OpenMP intrinsic subroutine omp_set_num_threads().

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 363 of file pm_parallelism.F90.

References getImageCount(), and getImageID().

Here is the call graph for this function:

isFailedImage()

logical(LK) function pm_parallelism::isFailedImage

(

logical(LK), intent(in)

failed

)

Broadcast the error condition from all images/processes to all images/processes.

This procedure exists primarily to aid the detection and graceful handling of runtime errors during the testing of ParaMonte library samplers or less frequently, when calling the samplers from dynamic programming languages or interactive environments such as Jupyter which require graceful handling of any errors to avoid environment shutdown.
The use of this procedure is essential to avoid runtime parallel deadlocks.

Parameters

[in]

failed

: The input scalar logical of default kind LK that should be .true. if and only if a fatal error has occurred. The value of failed is typically the occurred component of an object of type err_type. On input, the specified value for failed is broadcast to all other active processes in the program.

Returns

failedParallelism : The output scalar of type logical of default kind LK that is .true. if and only if the input argument failed on any image/process in the current parallel simulation is .true..

Possible calling interfaces ⛓

use pm_kind, only: LK
use pm_parallelism, only: isFailedImage
logical(LK) :: failedParallelism
logical(LK) :: failed
 
failedParallelism = isFailedImage(failed)

Warning

This subroutine must be called in parallel by all images or none.

This function primarily exists for soft handling of fatal errors in parallel testing mode and should therefore ideally not be used in production builds.
If it is used repeatedly within an application, it can significantly degrade the parallel performance.

Remarks

The procedures under discussion are impure.

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, 9:49 PM Friday, March 1, 2013, Institute for Fusion Studies, The University of Texas at Austin

Definition at line 828 of file pm_parallelism.F90.

setImageCount()

subroutine pm_parallelism::setImageCount

(

integer(IK), intent(in), optional

count

)

Set the number the parallel threads for an OpenMP-enabled application.

This generic interface is exclusively relevant to the OpenMP-enabled ParaMonte library builds and applications.
This interface offers a convenient consistent cross-platform method of setting the number of runtime OpenMP threads for a parallel code section.
It does so by calling the OpenMP intrinsic

Parameters

[in]

count

: The input scalar of type integer of default kind IK containing the requested number of OpenMP threads. This argument is relevant only if the OpenMP parallelism is enabled at the time of building the ParaMonte library. Unlike Coarray or MPI parallelism paradigms, the number of images (threads) can be (re)set at runtime in OpenMP applications, hence the need for this argument. If the input count is non-positive, this generic interface uses the output of OpenMP intrinsic omp_get_num_procs() as the number of threads. This is unlike the default behavior of Intel and GNU OpenMP libraries which set the number of threads to max(count, 1). (optional, default = omp_get_num_procs())

Developer Remark:

Although this procedure exists for all parallelism builds of the ParaMonte library, it does nothing for non OpenMP-enabled library builds.
Note that the number of images/processes for Coarray/MPI -enabled applications must be set by the user at the time of running the parallel application.
This is unlike the OpenMP parallel applications where the number of threads can be (re)set at runtime during the program execution.

Possible calling interfaces ⛓

use pm_parallelism, only: setImageCount
 
call setImageCount(count = count)

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 3:50 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 761 of file pm_parallelism.F90.

setImageFinalized()

subroutine pm_parallelism::setImageFinalized

Finalize the current parallel simulation and return nothing.

This is a static member of the image_type class.

1. This procedure facilitates a parallelism-agnostic way of finalizing serial and parallel applications by hiding the finalization step within this procedure.
   
2. This procedure is primarily relevant to MPI applications where MPI needs to be finalized before the simulation stop.
   
3. This procedure performs a sync all for Coarray applications and returns.
   
4. This procedure performs nothing for other all applications (e.g., serial, OpenMP, ...).
   

Possible calling interfaces ⛓

use pm_parallelism, only: setImageFinalized
 
call setImageFinalized()
!

Warning

The MPI library must be initialized and not finalized prior to calling this routine for MPI-parallel applications.

The MPI communications will be shut down upon calling this routine and further inter-process communications will be impossible.

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 4:13 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 465 of file pm_parallelism.F90.

setImageSynced()

subroutine pm_parallelism::setImageSynced

Synchronize all existing parallel images and return nothing.

This is a static member of the image_type class.
This procedure synchronizes all images in the current communication world by,

1. calling sync all in Coarray applications.
2. calling mpi_barrier() in MPI applications.
3. calling nothing in all other (including serial) applications.

Warning

This routine contains global Coarray and MPI synchronization barriers and therefore, must be called by all processes in the current simulation.

The MPI library must be initialized and not finalized prior to calling this routine for MPI-parallel applications.

Possible calling interfaces ⛓

use pm_parallelism, only: setImageSynced()
 
call setImageSynced()

Test:

test_pm_parallelism

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Tuesday March 7, 2017, 4:13 AM, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin

Definition at line 412 of file pm_parallelism.F90.

Variable Documentation

MODULE_NAME

character(*, SK), parameter pm_parallelism::MODULE_NAME = SK_"@pm_parallelism"

Definition at line 42 of file pm_parallelism.F90.

PARALLELIZATION_MODE

character(*) SK parameter pm_parallelism::PARALLELIZATION_MODE = SK_"parallel"

The scalar constant of type character of default kind SK, whose value is set to parallel if the ParaMonte library is built with the preprocessor macro -DCAF_ENABLED=1 -DMPI_ENABLED=1, otherwise, it is set to "serial".

Definition at line 49 of file pm_parallelism.F90.