PSMatrixModule Module

A Module For Performing Distributed Sparse Matrix Operations.


Uses


Contents

Interfaces

Derived Types

Functions

Subroutines


Interfaces

public interface ConstructEmptyMatrix

  • private subroutine ConstructEmptyMatrix_ps(this, matrix_dim, process_grid_in, is_complex_in)

    Construct an empty sparse, distributed, matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to be constructed.
    integer, intent(in) :: matrix_dim

    The dimension of the full matrix.
    type(ProcessGrid_t), intent(in), optional, TARGET :: process_grid_in

    A process grid to host the matrix.
    logical, intent(in), optional :: is_complex_in

    True if you want to use complex numbers.

  • private subroutine ConstructEmptyMatrix_ps_cp(this, reference_matrix)

    Construct an empty sparse, distributed, matrix using another matrix to determine the parameters. Note that no data is copied, the matrix will be empty.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to be constructed.
    type(Matrix_ps), intent(in) :: reference_matrix

    The reference matrix to take parameters from.

public interface DestructMatrix

  • private pure subroutine DestructMatrix_ps(this)

    Destruct a distributed sparse matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to destruct.

public interface CopyMatrix

  • private subroutine CopyMatrix_ps(matA, matB)

    Copy a distributed sparse matrix in a safe way.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: matA

    The matrix to copy.
    type(Matrix_ps), intent(inout) :: matB

    matB = matA.

public interface ConstructMatrixFromMatrixMarket

  • private recursive subroutine ConstructMatrixFromMatrixMarket_ps(this, file_name, process_grid_in)

    Construct distributed sparse matrix from a matrix market file in parallel. Read \cite boisvert1996matrix for the details.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The file being constructed.
    character(len=*), intent(in) :: file_name

    The name of the file to read.
    type(ProcessGrid_t), intent(in), optional :: process_grid_in

    Grid to distribute the matrix on.

public interface ConstructMatrixFromBinary

  • private recursive subroutine ConstructMatrixFromBinary_ps(this, file_name, process_grid_in)

    Construct a distributed sparse matrix from a binary file in parallel. Faster than text, so this is good for check pointing.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The file being constructed.
    character(len=*), intent(in) :: file_name

    The name of the file to read.
    type(ProcessGrid_t), intent(in), optional :: process_grid_in

    Grid to distribute the matrix on.

public interface WriteMatrixToMatrixMarket

  • private subroutine WriteMatrixToMatrixMarket_ps(this, file_name)

    Write a distributed sparse matrix to a matrix market file. Read \cite boisvert1996matrix for the details.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The Matrix to write.
    character(len=*), intent(in) :: file_name

    The name of the file to write to.

public interface WriteMatrixToBinary

  • private subroutine WriteMatrixToBinary_ps(this, file_name)

    Save a distributed sparse matrix to a binary file. Faster than text, so this is good for check pointing.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The Matrix to write.
    character(len=*), intent(in) :: file_name

    The name of the file to write to.

public interface FillMatrixFromTripletList

  • private subroutine FillMatrixFromTripletList_psr(this, triplet_list, preduplicated_in, prepartitioned_in)

    This routine fills in a matrix based on local triplet lists. Each process should pass in triplet lists with global coordinates. It does not matter where each triplet is stored, as long as global coordinates are given. However, if you explicitly set prepartitioned_in to True, all data must be on the correct process. In that case, there is no communication required.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to fill.
    type(TripletList_r), intent(in) :: triplet_list

    The triplet list of values.
    logical, intent(in), optional :: preduplicated_in

    If lists are preduplicated across slices set this to true.
    logical, intent(in), optional :: prepartitioned_in

    If all lists only contain local matrix elements set this to true.

  • private subroutine FillMatrixFromTripletList_psc(this, triplet_list, preduplicated_in, prepartitioned_in)

    This routine fills in a matrix based on local triplet lists. Each process should pass in triplet lists with global coordinates. It does not matter where each triplet is stored, as long as global coordinates are given. However, if you explicitly set prepartitioned_in to True, all data must be on the correct process. In that case, there is no communication required.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to fill.
    type(TripletList_c), intent(in) :: triplet_list

    The triplet list of values.
    logical, intent(in), optional :: preduplicated_in

    If lists are preduplicated across slices set this to true.
    logical, intent(in), optional :: prepartitioned_in

    If all lists only contain local matrix elements set this to true.

public interface FillMatrixIdentity

  • private subroutine FillMatrixIdentity_ps(this)

    Fill in the values of a distributed matrix with the identity matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix being filled.

public interface FillMatrixPermutation

  • private subroutine FillMatrixPermutation_ps(this, permutation_vector, permute_rows_in)

    Fill in the values of a distributed matrix with a permutation. If you do not specify permuterows, will default to permuting rows.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix being filled.
    integer, intent(in), DIMENSION(:) :: permutation_vector

    Describes for each row/column, where it goes.
    logical, intent(in), optional :: permute_rows_in

    If true permute rows, false permute columns.

public interface FillMatrixDense

  • private subroutine FillMatrixDense_ps(this)

    This routine will fill a dense matrix so that every element has a given

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix being filled.

public interface GetMatrixActualDimension

  • private pure function GetMatrixActualDimension_ps(this) result(DIMENSION)

    Get the actual dimension of the matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix.

    Return Value integer

    Dimension of the matrix

public interface GetMatrixLogicalDimension

  • private pure function GetMatrixLogicalDimension_ps(this) result(DIMENSION)

    Get the logical dimension of the matrix. Includes padding.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix.

    Return Value integer

    Dimension of the matrix

public interface GetMatrixTripletList

  • private subroutine GetMatrixTripletList_psr(this, triplet_list)

    Extracts a triplet list of the data that is stored on this process. Data is returned with absolute coordinates.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The distributed sparse matrix.
    type(TripletList_r), intent(inout) :: triplet_list

    The list to fill.

  • private subroutine GetMatrixTripletList_psc(this, triplet_list)

    Extracts a triplet list of the data that is stored on this process. Data is returned with absolute coordinates.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The distributed sparse matrix.
    type(TripletList_c), intent(inout) :: triplet_list

    The list to fill.

public interface GetMatrixBlock

  • private subroutine GetMatrixBlock_psr(this, triplet_list, start_row, end_row, start_column, end_column)

    Extract an arbitrary block of a matrix into a triplet list. Block is defined by the row/column start/end values. This is slower than GetMatrixTripletList, because communication is required Data is returned with absolute coordinates.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The distributed sparse matrix.
    type(TripletList_r), intent(inout) :: triplet_list

    The list to fill.
    integer, intent(in) :: start_row

    The starting row for data to store on this process.
    integer, intent(in) :: end_row

    The ending row for data to store on this process.
    integer, intent(in) :: start_column

    The starting col for data to store on this process
    integer, intent(in) :: end_column

    The ending col for data to store on this process

  • private subroutine GetMatrixBlock_psc(this, triplet_list, start_row, end_row, start_column, end_column)

    Extract an arbitrary block of a matrix into a triplet list. Block is defined by the row/column start/end values. This is slower than GetMatrixTripletList, because communication is required Data is returned with absolute coordinates.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The distributed sparse matrix.
    type(TripletList_c), intent(inout) :: triplet_list

    The list to fill.
    integer, intent(in) :: start_row

    The starting row for data to store on this process.
    integer, intent(in) :: end_row

    The ending row for data to store on this process.
    integer, intent(in) :: start_column

    The starting col for data to store on this process
    integer, intent(in) :: end_column

    The ending col for data to store on this process

public interface PrintMatrix

  • private subroutine PrintMatrix_ps(this, file_name_in)

    Print out a distributed sparse matrix. This is a serial print routine, and should probably only be used for debug purposes.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps) :: this

    The matrix to print.
    character(len=*), intent(in), optional :: file_name_in

    Optionally, you can pass a file to print to instead of the console.

public interface PrintMatrixInformation

  • private subroutine PrintMatrixInformation_ps(this)

    Print out information about a distributed sparse matrix. Sparsity, and load balancing information.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    This the matrix to print information about.

public interface GetMatrixLoadBalance

  • private subroutine GetMatrixLoadBalance_ps(this, min_size, max_size)

    Get a measure of how load balanced this matrix is. For each process, the number of non-zero entries is calculated. Then, this function returns the max and min of those values.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix to compute the measure on.
    integer, intent(out) :: min_size

    The minimum entries contained on a single process.
    integer, intent(out) :: max_size

    The maximum entries contained on a single process.

public interface GetMatrixSize

  • private function GetMatrixSize_ps(this) result(total_size)

    Get the total number of non-zero entries in the distributed sparse matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix to calculate the number of non-zero entries of.

    Return Value integer(kind=NTLONG)

    The number of non-zero entries in the matrix.

public interface FilterMatrix

  • private subroutine FilterMatrix_ps(this, threshold)

    A utility routine that filters a sparse matrix. All (absolute) values below the threshold are set to zero.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to filter.
    real(kind=NTREAL), intent(in) :: threshold

    Threshold (absolute) values below this are filtered

public interface MergeMatrixLocalBlocks

  • private pure subroutine MergeMatrixLocalBlocks_psr(this, merged_matrix)

    Merge together the local matrix blocks into one big matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The distributed sparse matrix to merge from.
    type(Matrix_lsr), intent(inout) :: merged_matrix

    The merged matrix.

  • private pure subroutine MergeMatrixLocalBlocks_psc(this, merged_matrix)

    Merge together the local matrix blocks into one big matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The distributed sparse matrix to merge from.
    type(Matrix_lsc), intent(inout) :: merged_matrix

    The merged matrix.

public interface SplitMatrixToLocalBlocks

  • private pure subroutine SplitMatrixToLocalBlocks_psr(this, matrix_to_split)

    Take a local matrix, and use it to fill the local block matrix structure.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The distributed sparse matrix to split into.
    type(Matrix_lsr), intent(in) :: matrix_to_split

    The matrix to split up.

  • private pure subroutine SplitMatrixToLocalBlocks_psc(this, matrix_to_split)

    Take a local matrix, and use it to fill the local block matrix structure.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The distributed sparse matrix to split into.
    type(Matrix_lsc), intent(in) :: matrix_to_split

    The matrix to split up.

public interface TransposeMatrix

  • private subroutine TransposeMatrix_ps(AMat, TransMat)

    Transpose a sparse matrix. Note that this is a pure transpose, there is no complex conjugate performed.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: AMat

    The matrix to transpose.
    type(Matrix_ps), intent(inout) :: TransMat

    TransMat = A^T .

public interface ConjugateMatrix

  • private pure subroutine ConjugateMatrix_ps(this)

    Every value in the matrix is changed into its complex conjugate.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to compute the complex conjugate of.

public interface CommSplitMatrix

  • private subroutine CommSplitMatrix_ps(this, split_mat, my_color, split_slice)

    Split the current communicator, and give each group a complete copy of this

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(inout) :: this

    The matrix to split.
    type(Matrix_ps), intent(inout) :: split_mat

    A copy of the matrix hosted on a small process grid.
    integer, intent(out) :: my_color

    Distinguishes between the two groups.
    logical, intent(out) :: split_slice

    If we split along the slice direction, this is True

public interface GatherMatrixToProcess

  • private subroutine GatherMatrixToProcess_psr_id(this, local_mat, within_slice_id)

    This subroutine gathers the entire matrix into a local matrix on the given process. The process id is a within_slice id, so the data will still be replicated across slices.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix to gather.
    type(Matrix_lsr), intent(inout) :: local_mat

    The full matrix, stored in a local matrix.
    integer, intent(in) :: within_slice_id

    Which process to gather on.

  • private subroutine GatherMatrixToProcess_psr_all(this, local_mat)

    This subroutine gathers the entire matrix into a local matrix on to every process.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix to gather.
    type(Matrix_lsr), intent(inout) :: local_mat

    The full matrix, stored in a local matrix.

  • private subroutine GatherMatrixToProcess_psc_id(this, local_mat, within_slice_id)

    This subroutine gathers the entire matrix into a local matrix on the given process. The process id is a within_slice id, so the data will still be replicated across slices.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix to gather.
    type(Matrix_lsc), intent(inout) :: local_mat

    The full matrix, stored in a local matrix.
    integer, intent(in) :: within_slice_id

    Which process to gather on.

  • private subroutine GatherMatrixToProcess_psc_all(this, local_mat)

    This subroutine gathers the entire matrix into a local matrix on to every process.

    Arguments

    Type IntentOptional Attributes Name
    type(Matrix_ps), intent(in) :: this

    The matrix to gather.
    type(Matrix_lsc), intent(inout) :: local_mat

    The full matrix, stored in a local matrix.

Derived Types

type, public ::  Matrix_ps

A datatype for a distributed blocked CSR matrix.

Components

Type Visibility Attributes Name Initial
integer, public :: logical_matrix_dimension

Number of matrix rows/columns for full matrix, scaled for process grid.
integer, public :: actual_matrix_dimension

Number of matrix rows/columns for the full matrix, unscaled.
type(Matrix_lsr), public, DIMENSION(:,:), ALLOCATABLE :: local_data_r

A 2D array of local CSR matrices.
type(Matrix_lsc), public, DIMENSION(:,:), ALLOCATABLE :: local_data_c

A 2D array of local CSC matrices.
integer, public :: start_column

first column stored locally.
integer, public :: end_column

last column stored locally is less than this.
integer, public :: start_row

first row stored locally.
integer, public :: end_row

last row stored locally is less than this.
integer, public :: local_columns

number of local columns.
integer, public :: local_rows

number of local rows.
type(ProcessGrid_t), public, POINTER :: process_grid

process grid to operate on
logical, public :: is_complex

true if the matrix data is true.

Functions

public function IsIdentity(this) result(is_identity)

Determine if this is the identity matrix.

Arguments

Type IntentOptional Attributes Name
type(Matrix_ps), intent(in) :: this

The matrix being filled.

Return Value logical

Result stored here.


Subroutines

public subroutine SetMatrixProcessGrid(this, grid)

When you want to change the process grid of a matrix, you can call this routine with the new process grid value. Data will be automatically redistributed.

Arguments

Type IntentOptional Attributes Name
type(Matrix_ps), intent(inout) :: this

The matrix to set the grid of.
type(ProcessGrid_t), intent(in) :: grid

The grid to set it to.

public subroutine GetMatrixSlice(this, submatrix, start_row, end_row, start_column, end_column)

Copy an arbitrary slice from a matrix into a new smaller matrix. NTPoly only works with square matrices, so if the number of rows and columns is different the matrix is resized to the maximum size.

Arguments

Type IntentOptional Attributes Name
type(Matrix_ps), intent(in) :: this

The distributed sparse matrix.
type(Matrix_ps), intent(inout) :: submatrix

The slice to fill.
integer, intent(in) :: start_row

The starting row to include in this matrix.
integer, intent(in) :: end_row

The ending row to include in this matrix.
integer, intent(in) :: start_column

The starting column to include in this matrix.
integer, intent(in) :: end_column

The last column to include in this matrix.

public subroutine ConvertMatrixToReal(in, out)

Converts the current matrix to a real type matrix.

Arguments

Type IntentOptional Attributes Name
type(Matrix_ps), intent(in) :: in

The matrix to convert.
type(Matrix_ps), intent(inout) :: out

Real version of the matrix.

public subroutine ConvertMatrixToComplex(in, out)

Converts the current matrix to a complex type matrix.

Arguments

Type IntentOptional Attributes Name
type(Matrix_ps), intent(in) :: in

The matrix to convert.
type(Matrix_ps), intent(inout) :: out

Complex version of the matrix.

public subroutine ResizeMatrix(this, new_size)

Change the size of a matrix. If the new size is smaller, then values outside that range are deleted. IF the new size is bigger, zero padding is applied. Warning: this requires a full data redistribution.

Arguments

Type IntentOptional Attributes Name
type(Matrix_ps), intent(inout) :: this

The matrix to resize.
integer, intent(in) :: new_size

The new size of the matrix.