 |
(git:6344619)
|
|
(git:6344619)
|
Assembly of real and complex k-point operators from real-space DBCSR matrices. Outputs use the distribution of the k-point group; real operators transfer one part only. The module splits this work into a start step and a finish step. One process can start many operators before it finishes any of them. The STANDARD k-point driver uses this order. The routines start, finish and get are collective over the environment-wide communicator. Every rank must call the same sequence of service calls. A context references its host kpoint environment without owning it, so it must not outlive that environment. An explicitly prepared, immutable operator batch can instead be built from bounded context-owned real-space snapshots inside each group. The public round and output-ownership contracts stay the same. Start/finish/get/prepare are not thread safe: serialize them, because their collective communication tolerates no concurrent service call. A separate context per thread only keeps the scratch from aliasing. More...
Data Types | |
| type | kpoint_operator_context_type |
| Caller-owned assembly context for one driver call. Created and released in the same driver routine and passed to helpers as an argument; never stored on the host kpoint_type. Components are private and touched only by this module. More... | |
Functions/Subroutines | |
| subroutine | kpoint_operator_densify (ctx, rsmat, matrix_row, ik, grid, use_grid) |
| Transform and densify one operator using the context-owned workspaces and routing plans. | |
| subroutine, public | kpoint_operator_context_create (ctx, kpoints, ao_ao_fm, nspin) |
| Create an empty operator context. The context owns no buffers after this call; they are created on first use and released with the context. | |
| subroutine, public | kpoint_operator_context_release (ctx) |
| Release the context together with every buffer it created. Call once, at the exit of the routine that created the context. Every started instance must be idle at this point. The call aborts when a transfer is still in flight, because nothing would ever wait for its MPI requests. | |
| subroutine, public | kpoint_operator_prepare (ctx, rsmat, slot, prepared, matrix_row, target) |
| Prepare an immutable operator slot for group-local assembly. Refresh after the source values change, with every instance idle. Other prepared slots and structural routing remain valid. Without matrix_row, capture one row per instance spin; with matrix_row, store one row shared by all instance spins. Failure clears this slot on all ranks and retains the existing transfer fallback. | |
| subroutine, public | kpoint_operator_work_size (ctx, nentry) |
| Size per-worker phase scratch for direct assembly into a solver matrix. | |
| subroutine, public | kpoint_operator_evaluate (ctx, ispin, slot, ik, phase, target, fm_re, fm_im) |
| Evaluate an immutable prepared operator with exclusively caller-owned output and scratch. Prepare/refresh/release remain collective and serialized. Evaluate contains no MPI, DBCSR lookup, window update or nested OpenMP region. Source blocks must stay unchanged. | |
| subroutine, public | kpoint_operator_start (ctx, ikp, ispin, rsmat, slot, grid, use_grid, matrix_row) |
| Start one operator for one global round and spin. The service walks all groups with a k point in this round; groups without one still participate in the transfers. Every rank must iterate through the maximum local k-point count. Finish every started instance with kpoint_operator_finish. The first start also creates the slot bookkeeping of the context. Collective over the environment-wide communicator: every rank must call the same sequence of service calls. | |
| subroutine, public | kpoint_operator_finish (ctx, ikp, ispin, slot, cmat, fm_re) |
| Finish one started instance: build its prepared group-local operator, or merge received parts into cmat (real part first, overwrite then add) and reclaim the send side on every group. The slot returns to idle. Collective over the environment-wide communicator: every rank must call the same sequence of service calls. | |
| subroutine, public | kpoint_operator_get (ctx, ikp, ispin, rsmat, cmat, fm_re, fm_im, mat_re, mat_im, matrix_row, slot, grid) |
| Assemble one operator for one global round and spin in one call: run the single-group transfer of the service for every group and finish it immediately, through transfer states local to this call. The persistent slot machinery stays with start and finish. Exactly one output flavor must be present: cmat receives the complex operator (real part overwrites, imaginary part adds) through the context buffer; the fm pair receives the two parts separately, transferred directly into fm_re and fm_im on the owning group (any distribution: the general copy redistributes); or the dbcsr pair receives the two parts as block-cyclic matrices built by the service, replacing the caller-side copy_fm_to_dbcsr_bc detour. The dbcsr matrices must be freshly initialized (dbcsr_init_p) and the cmat flavor must share the distribution of the k-point group. Collective over the environment-wide communicator: every rank must call the same sequence of service calls. | |
| subroutine, public | kpoint_operator_get_local (matrix_rs, kpoints, kp, ispin, cache_re, cache_im, matrix_re, matrix_im) |
| Read an operator inside a group-local OT loop, after collective cache preparation. One group retains the sparse transform and distribution required by OT's DBCSR kernels. Multiple groups read their owned cache; no world collective may occur in this loop. | |
| subroutine, public | kpoint_operator_get_all (kpoints, ao_ao_fm, rsmat, slot, cmat, matrix_row) |
| Fill caller-owned matrices for one operator row, including independent history snapshots. Prepare and fallback transfers are collective. Prepared one-rank groups evaluate k points concurrently, with no MPI or matrix allocation/refcounts inside the worker loop. | |
| subroutine, public | kpoint_operator_store (kpoints, ao_ao_fm, matrix_ks, matrix_s, matrix_t) |
| Prepare owned split-FM operators for OT without entering an SCF eigensolver. H (or the initialization density) retains all source spins; S/T are built only once. Outputs survive the transient context. Compatible cache storage is reused, values refreshed. | |
Variables | |
| integer, parameter, public | kpoint_slot_ks = 1 |
| integer, parameter, public | kpoint_slot_s = 2 |
| integer, parameter, public | kpoint_slot_t = 3 |
| integer, parameter, public | kpoint_spin_free = 1 |
| Row of rsmat that carries the spin-free operator image. S and T carry no spin copies: drivers launch one instance per spin of their loop and read this same row in every instance. | |
| integer, parameter | rs_batch_size = 4 |
Assembly of real and complex k-point operators from real-space DBCSR matrices. Outputs use the distribution of the k-point group; real operators transfer one part only. The module splits this work into a start step and a finish step. One process can start many operators before it finishes any of them. The STANDARD k-point driver uses this order. The routines start, finish and get are collective over the environment-wide communicator. Every rank must call the same sequence of service calls. A context references its host kpoint environment without owning it, so it must not outlive that environment. An explicitly prepared, immutable operator batch can instead be built from bounded context-owned real-space snapshots inside each group. The public round and output-ownership contracts stay the same. Start/finish/get/prepare are not thread safe: serialize them, because their collective communication tolerates no concurrent service call. A separate context per thread only keeps the scratch from aliasing.
| subroutine qs_kpoint_operators::kpoint_operator_densify | ( | type(kpoint_operator_context_type), intent(inout) | ctx, |
| type(dbcsr_p_type), dimension(:, :), pointer | rsmat, | ||
| integer, intent(in) | matrix_row, | ||
| integer, intent(in) | ik, | ||
| type(rskp_grid_type), intent(in), optional | grid, | ||
| logical, intent(in) | use_grid ) |
Transform and densify one operator using the context-owned workspaces and routing plans.
| ctx | initialized transfer context |
| rsmat | real-space operator images |
| matrix_row | operator row, independent of the instance spin |
| ik | global k-point index |
| grid | caller-owned reciprocal-grid cache |
| use_grid | extract from grid instead of a direct phase sum |
Definition at line 203 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_context_create | ( | type(kpoint_operator_context_type), intent(out) | ctx, |
| type(kpoint_type), pointer | kpoints, | ||
| type(cp_fm_type), intent(in) | ao_ao_fm, | ||
| integer, intent(in) | nspin ) |
Create an empty operator context. The context owns no buffers after this call; they are created on first use and released with the context.
| ctx | context to initialize |
| kpoints | host k-point environment, referenced, not copied |
| ao_ao_fm | any square full matrix on the environment-wide communicator; its matrix struct is the template for the context work buffers, which densify on the source side of transfers that cross into the k-point groups |
| nspin | instance spin space of the owning driver call: the bound of the spin loop its start and finish calls iterate. Fixed for the lifetime of the context |
Definition at line 377 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_context_release | ( | type(kpoint_operator_context_type), intent(inout) | ctx | ) |
Release the context together with every buffer it created. Call once, at the exit of the routine that created the context. Every started instance must be idle at this point. The call aborts when a transfer is still in flight, because nothing would ever wait for its MPI requests.
| ctx | context to release |
Definition at line 414 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_prepare | ( | type(kpoint_operator_context_type), intent(inout) | ctx, |
| type(dbcsr_p_type), dimension(:, :), pointer | rsmat, | ||
| integer, intent(in) | slot, | ||
| logical, intent(out), optional | prepared, | ||
| integer, intent(in), optional | matrix_row, | ||
| type(cp_fm_type), intent(in), optional | target ) |
Prepare an immutable operator slot for group-local assembly. Refresh after the source values change, with every instance idle. Other prepared slots and structural routing remain valid. Without matrix_row, capture one row per instance spin; with matrix_row, store one row shared by all instance spins. Failure clears this slot on all ranks and retains the existing transfer fallback.
| ctx | context spanning the current initialized k-point environment |
| rsmat | current real-space operator images |
| slot | slot to replace (KS, S or T) |
| prepared | optional collective success flag |
| matrix_row | optional explicit spin-free operator row |
| TARGET | optional group-local FM layout for prepared get outputs; otherwise use the host AO/AO pool layout. One layout per context |
Definition at line 561 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_work_size | ( | type(kpoint_operator_context_type), intent(in) | ctx, |
| integer, intent(out) | nentry ) |
Size per-worker phase scratch for direct assembly into a solver matrix.
| ctx | prepared context |
| nentry | number of route entries |
Definition at line 1334 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_evaluate | ( | type(kpoint_operator_context_type), intent(in) | ctx, |
| integer, intent(in) | ispin, | ||
| integer, intent(in) | slot, | ||
| integer, intent(in) | ik, | ||
| complex(kind=dp), dimension(:, :), intent(inout), target | phase, | ||
| type(cp_cfm_type), intent(inout), optional | target, | ||
| type(cp_fm_type), intent(inout), optional | fm_re, | ||
| type(cp_fm_type), intent(inout), optional | fm_im ) |
Evaluate an immutable prepared operator with exclusively caller-owned output and scratch. Prepare/refresh/release remain collective and serialized. Evaluate contains no MPI, DBCSR lookup, window update or nested OpenMP region. Source blocks must stay unchanged.
| ctx | prepared read-only context |
| ispin | instance spin |
| slot | operator slot |
| ik | global k index owned by this group |
| phase | private phase scratch, sized with work_size |
| TARGET | optional private complex singleton output |
| fm_re | optional private real output instead of TARGET |
| fm_im | optional private imaginary output, accompanying fm_re for a complex operator |
Definition at line 1355 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_start | ( | type(kpoint_operator_context_type), intent(inout) | ctx, |
| integer, intent(in) | ikp, | ||
| integer, intent(in) | ispin, | ||
| type(dbcsr_p_type), dimension(:, :), pointer | rsmat, | ||
| integer, intent(in) | slot, | ||
| type(rskp_grid_type), intent(in), optional | grid, | ||
| logical, intent(in) | use_grid, | ||
| integer, intent(in) | matrix_row ) |
Start one operator for one global round and spin. The service walks all groups with a k point in this round; groups without one still participate in the transfers. Every rank must iterate through the maximum local k-point count. Finish every started instance with kpoint_operator_finish. The first start also creates the slot bookkeeping of the context. Collective over the environment-wide communicator: every rank must call the same sequence of service calls.
| ctx | context created by kpoint_operator_context_create |
| ikp | global round, up to the maximum k-point count across groups |
| ispin | instance spin: keys the bookkeeping |
| rsmat | real-space image matrices of the operator. A prepared operator batch uses the values captured by prepare; otherwise start reads the current values. The matching finish never reads rsmat |
| slot | instance slot, optionally backed by a prepared snapshot |
| grid | prepared reciprocal-grid cache of the caller |
| use_grid | extract from grid instead of a direct phase sum |
| matrix_row | row of rsmat to transform. Spin-free operators such as S and T must pass kpoint_spin_free: their first matrix dimension counts derivatives, not spins. A spin index is out of bounds in plain SCF, but with derivatives stored it reads another valid row silently |
Definition at line 1404 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_finish | ( | type(kpoint_operator_context_type), intent(inout) | ctx, |
| integer, intent(in) | ikp, | ||
| integer, intent(in) | ispin, | ||
| integer, intent(in) | slot, | ||
| type(cp_cfm_type), optional | cmat, | ||
| type(cp_fm_type), optional | fm_re ) |
Finish one started instance: build its prepared group-local operator, or merge received parts into cmat (real part first, overwrite then add) and reclaim the send side on every group. The slot returns to idle. Collective over the environment-wide communicator: every rank must call the same sequence of service calls.
| ctx | context that started the instance |
| ikp | global round of the start call |
| ispin | spin component of the start call |
| slot | slot of the start call; the slot must be in flight |
| cmat | caller-allocated complex matrix that receives the operator. It must share the distribution of the k-point group. Unchanged on groups without a k point in this round |
| fm_re | optional real FM output instead of cmat for real wavefunctions, on the group layout |
Definition at line 1490 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_get | ( | type(kpoint_operator_context_type), intent(inout) | ctx, |
| integer, intent(in) | ikp, | ||
| integer, intent(in) | ispin, | ||
| type(dbcsr_p_type), dimension(:, :), pointer | rsmat, | ||
| type(cp_cfm_type), optional | cmat, | ||
| type(cp_fm_type), optional | fm_re, | ||
| type(cp_fm_type), optional | fm_im, | ||
| type(dbcsr_type), intent(inout), optional | mat_re, | ||
| type(dbcsr_type), intent(inout), optional | mat_im, | ||
| integer, intent(in) | matrix_row, | ||
| integer, intent(in), optional | slot, | ||
| type(rskp_grid_type), intent(in), optional | grid ) |
Assemble one operator for one global round and spin in one call: run the single-group transfer of the service for every group and finish it immediately, through transfer states local to this call. The persistent slot machinery stays with start and finish. Exactly one output flavor must be present: cmat receives the complex operator (real part overwrites, imaginary part adds) through the context buffer; the fm pair receives the two parts separately, transferred directly into fm_re and fm_im on the owning group (any distribution: the general copy redistributes); or the dbcsr pair receives the two parts as block-cyclic matrices built by the service, replacing the caller-side copy_fm_to_dbcsr_bc detour. The dbcsr matrices must be freshly initialized (dbcsr_init_p) and the cmat flavor must share the distribution of the k-point group. Collective over the environment-wide communicator: every rank must call the same sequence of service calls.
| ctx | context created by kpoint_operator_context_create |
| ikp | global round, up to the maximum k-point count across groups |
| ispin | instance spin: bounds-checked against the context spin space |
| rsmat | real-space image matrices of the operator |
| cmat | complex matrix output |
| fm_re | real-part matrix output |
| fm_im | imaginary-part output; may be omitted for real wavefunctions |
| mat_re | real-part block-cyclic dbcsr output |
| mat_im | imaginary-part block-cyclic dbcsr output |
| matrix_row | row of rsmat to transform. Spin-free operators such as S and T must pass kpoint_spin_free: their first matrix dimension counts derivatives, not spins. A spin index is out of bounds in plain SCF, but with derivatives stored it reads another valid row silently |
| slot | optional prepared slot: opt in to its immutable snapshot. Without slot, get always reads current source values. A missing or mismatched snapshot retains the original transfer path. Prepared FM targets must match the layout selected at prepare; inactive groups do not inspect or modify their output arguments. |
| grid | optional lattice-FFT grid, overriding a prepared snapshot for this request |
Definition at line 1587 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_get_local | ( | type(dbcsr_p_type), dimension(:, :), pointer | matrix_rs, |
| type(kpoint_type), pointer | kpoints, | ||
| type(kpoint_env_type), pointer | kp, | ||
| integer, intent(in) | ispin, | ||
| type(cp_fm_type), intent(in) | cache_re, | ||
| type(cp_fm_type), intent(in) | cache_im, | ||
| type(dbcsr_type), pointer | matrix_re, | ||
| type(dbcsr_type), pointer | matrix_im ) |
Read an operator inside a group-local OT loop, after collective cache preparation. One group retains the sparse transform and distribution required by OT's DBCSR kernels. Multiple groups read their owned cache; no world collective may occur in this loop.
| matrix_rs | current real-space operator |
| kpoints | host environment |
| kp | local k-point state |
| ispin | source row (one for spin-free S/T) |
| cache_re | owned real part, used with multiple groups |
| cache_im | owned imaginary part, used with multiple groups |
| matrix_re | newly initialized sparse real output |
| matrix_im | newly initialized sparse imaginary output |
Definition at line 1684 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_get_all | ( | type(kpoint_type), pointer | kpoints, |
| type(cp_fm_type), intent(in) | ao_ao_fm, | ||
| type(dbcsr_p_type), dimension(:, :), pointer | rsmat, | ||
| integer, intent(in) | slot, | ||
| type(cp_cfm_type), dimension(:), intent(inout) | cmat, | ||
| integer, intent(in) | matrix_row ) |
Fill caller-owned matrices for one operator row, including independent history snapshots. Prepare and fallback transfers are collective. Prepared one-rank groups evaluate k points concurrently, with no MPI or matrix allocation/refcounts inside the worker loop.
| kpoints | host environment |
| ao_ao_fm | global-layout template |
| rsmat | current real-space images |
| slot | operator slot |
| cmat | allocated group-local outputs, one per locally owned k point |
| matrix_row | source row; S/T use kpoint_spin_free |
Definition at line 1742 of file qs_kpoint_operators.F.
| subroutine, public qs_kpoint_operators::kpoint_operator_store | ( | type(kpoint_type), pointer | kpoints, |
| type(cp_fm_type), intent(in) | ao_ao_fm, | ||
| type(dbcsr_p_type), dimension(:, :), pointer | matrix_ks, | ||
| type(dbcsr_p_type), dimension(:, :), pointer | matrix_s, | ||
| type(dbcsr_p_type), dimension(:, :), optional, pointer | matrix_t ) |
Prepare owned split-FM operators for OT without entering an SCF eigensolver. H (or the initialization density) retains all source spins; S/T are built only once. Outputs survive the transient context. Compatible cache storage is reused, values refreshed.
| kpoints | host environment and owned OT caches |
| ao_ao_fm | global-layout template |
| matrix_ks | Hamiltonian or initialization density |
| matrix_s | spin-free overlap |
| matrix_t | optional spin-free kinetic operator; absent leaves the existing kinetic cache alone |
Definition at line 1803 of file qs_kpoint_operators.F.
| integer, parameter, public qs_kpoint_operators::kpoint_slot_ks = 1 |
Definition at line 88 of file qs_kpoint_operators.F.
| integer, parameter, public qs_kpoint_operators::kpoint_slot_s = 2 |
Definition at line 88 of file qs_kpoint_operators.F.
| integer, parameter, public qs_kpoint_operators::kpoint_slot_t = 3 |
Definition at line 88 of file qs_kpoint_operators.F.
| integer, parameter, public qs_kpoint_operators::kpoint_spin_free = 1 |
Row of rsmat that carries the spin-free operator image. S and T carry no spin copies: drivers launch one instance per spin of their loop and read this same row in every instance.
Definition at line 95 of file qs_kpoint_operators.F.
| integer, parameter qs_kpoint_operators::rs_batch_size = 4 |
Definition at line 146 of file qs_kpoint_operators.F.
1.15.0