dbcsr_t_contract Subroutine

public subroutine dbcsr_t_contract(alpha, tensor_1, tensor_2, beta, tensor_3, contract_1, notcontract_1, contract_2, notcontract_2, map_1, map_2, bounds_1, bounds_2, bounds_3, optimize_dist, pgrid_opt_1, pgrid_opt_2, pgrid_opt_3, filter_eps, flop, move_data, retain_sparsity, unit_nr, log_verbose)

Contract tensors by multiplying matrix representations. tensor_3(map_1, map_2) := alpha * tensor_1(notcontract_1, contract_1) * tensor_2(contract_2, notcontract_2) + beta * tensor_3(map_1, map_2)


note 1: block sizes of the corresponding indices need to be the same in all tensors.

note 2: for best performance the tensors should have been created in matrix layouts compatible with the contraction, e.g. tensor_1 should have been created with either map1_2d == contract_1 and map2_2d == notcontract_1 or map1_2d == notcontract_1 and map2_2d == contract_1 (the same with tensor_2 and contract_2 / notcontract_2 and with tensor_3 and map_1 / map_2). Furthermore the two largest tensors involved in the contraction should map both to either tall or short matrices: the largest matrix dimension should be "on the same side" and should have identical distribution (which is always the case if the distributions were obtained with dbcsr_t_default_distvec).

note 3: if the same tensor occurs in multiple contractions, a different tensor object should be created for each contraction and the data should be copied between the tensors by use of dbcsr_t_copy. If the same tensor object is used in multiple contractions, matrix layouts are not compatible for all contractions (see note 2).

note 4: automatic optimizations are enabled by using the feature of batched contraction, see dbcsr_t_batched_contract_init, dbcsr_t_batched_contract_finalize. The arguments bounds_1, bounds_2, bounds_3 give the index ranges of the batches.


Type IntentOptional Attributes Name
type(dbcsr_scalar_type), intent(in) :: alpha
type(dbcsr_t_type), intent(inout), TARGET :: tensor_1

first tensor (in)

type(dbcsr_t_type), intent(inout), TARGET :: tensor_2

second tensor (in)

type(dbcsr_scalar_type), intent(in) :: beta
type(dbcsr_t_type), intent(inout), TARGET :: tensor_3

contracted tensor (out)

integer, intent(in), DIMENSION(:) :: contract_1

indices of tensor_1 to contract

integer, intent(in), DIMENSION(:) :: notcontract_1

indices of tensor_1 not to contract

integer, intent(in), DIMENSION(:) :: contract_2

indices of tensor_2 to contract (1:1 with contract_1)

integer, intent(in), DIMENSION(:) :: notcontract_2

indices of tensor_2 not to contract

integer, intent(in), DIMENSION(:) :: map_1

which indices of tensor_3 map to non-contracted indices of tensor_1 (1:1 with notcontract_1)

integer, intent(in), DIMENSION(:) :: map_2

which indices of tensor_3 map to non-contracted indices of tensor_2 (1:1 with notcontract_2)

integer, intent(in), optional, DIMENSION(2, SIZE(contract_1)) :: bounds_1

bounds corresponding to contract_1 AKA contract_2: start and end index of an index range over which to contract. For use in batched contraction.

integer, intent(in), optional, DIMENSION(2, SIZE(notcontract_1)) :: bounds_2

bounds corresponding to notcontract_1: start and end index of an index range. For use in batched contraction.

integer, intent(in), optional, DIMENSION(2, SIZE(notcontract_2)) :: bounds_3

bounds corresponding to notcontract_2: start and end index of an index range. For use in batched contraction.

logical, intent(in), optional :: optimize_dist

Whether distribution should be optimized internally. In the current implementation this guarantees optimal parameters only for dense matrices.

type(dbcsr_t_pgrid_type), intent(out), optional, POINTER :: pgrid_opt_1

Optionally return optimal process grid for tensor_1. This can be used to choose optimal process grids for subsequent tensor contractions with tensors of similar shape and sparsity. Under some conditions, pgrid_opt_1 can not be returned, in this case the pointer is not associated.

type(dbcsr_t_pgrid_type), intent(out), optional, POINTER :: pgrid_opt_2

Optionally return optimal process grid for tensor_2.

type(dbcsr_t_pgrid_type), intent(out), optional, POINTER :: pgrid_opt_3

Optionally return optimal process grid for tensor_3.

real(kind=real_8), intent(in), optional :: filter_eps

As in DBCSR mm

integer(kind=int_8), intent(out), optional :: flop

As in DBCSR mm

logical, intent(in), optional :: move_data

memory optimization: transfer data such that tensor_1 and tensor_2 are empty on return

logical, intent(in), optional :: retain_sparsity

enforce the sparsity pattern of the existing tensor_3; default is no

integer, intent(in), optional :: unit_nr

output unit for logging set it to -1 on ranks that should not write (and any valid unit number on ranks that should write output) if 0 on ALL ranks, no output is written

logical, intent(in), optional :: log_verbose

verbose logging (for testing only)