(git:27c966b)
Loading...
Searching...
No Matches
topology_phason_analysis.F
Go to the documentation of this file.
1!--------------------------------------------------------------------------------------------------!
2! CP2K: A general program to perform molecular dynamics simulations !
3! Copyright 2000-2026 CP2K developers group <https://cp2k.org> !
4! !
5! SPDX-License-Identifier: GPL-2.0-or-later !
6!--------------------------------------------------------------------------------------------------!
7
8! **************************************************************************************************
9!> \brief Native streaming mesh analysis with physical endpoint sewing.
10! **************************************************************************************************
12 USE cp_files, ONLY: close_file,&
14 USE ieee_arithmetic, ONLY: ieee_is_finite
15 USE iso_fortran_env, ONLY: int64
16 USE kinds, ONLY: default_path_length,&
17 dp
26#include "./base/base_uses.f90"
27
28 IMPLICIT NONE
29 CHARACTER(len=*), PARAMETER, PRIVATE :: moduleN = 'topology_phason_analysis'
30 PRIVATE
32 INTEGER :: dimension = 0, rank = 0, shape(4) = 0, nat = 0, point = 0
33 REAL(kind=dp) :: value = 0.0_dp, origin(3) = 0.0_dp, directions(3, 4) = 0.0_dp
34 CHARACTER(LEN=default_path_length) :: first_file = ''
35 END TYPE phason_result_type
37
38CONTAINS
39
40! **************************************************************************************************
41!> \brief Flatten a zero-based index with the first coordinate varying fastest.
42!> \param index Zero-based coordinate along each axis
43!> \param shape Number of entries along each axis
44!> \return One-based linear index
45! **************************************************************************************************
46 INTEGER FUNCTION flat(index, shape) RESULT(value)
47 INTEGER, INTENT(IN) :: index(:), shape(:)
48
49 INTEGER :: d, stride
50
51 value = 1
52 stride = 1
53 DO d = 1, SIZE(shape)
54 value = value + index(d)*stride
55 stride = stride*shape(d)
56 END DO
57 END FUNCTION flat
58
59! **************************************************************************************************
60!> \brief Inverse of flat; first coordinate varies fastest.
61!> \param value One-based linear index
62!> \param shape Number of entries along each axis
63!> \param index Zero-based coordinate along each axis
64! **************************************************************************************************
65 SUBROUTINE unflat(value, shape, index)
66 INTEGER, INTENT(IN) :: value, shape(:)
67 INTEGER, INTENT(OUT) :: index(:)
68
69 INTEGER :: d, remainder
70
71 remainder = value - 1
72 DO d = 1, SIZE(shape)
73 index(d) = mod(remainder, shape(d))
74 remainder = remainder/shape(d)
75 END DO
76 END SUBROUTINE unflat
77
78! **************************************************************************************************
79!> \brief Build physical links or read reference links; stream plaquettes through an anonymous file.
80!> \param path Manifest or reference-link filename
81!> \param physical True for physical STATE_EXPORT frames, false for reference links
82!> \param report Mesh metadata and unrounded Chern estimate for refinement comparison
83!> \param io_unit Unit receiving mesh diagnostics
84! **************************************************************************************************
85 SUBROUTINE analyze_mesh(path, physical, report, io_unit)
86 CHARACTER(LEN=*), INTENT(IN) :: path
87 LOGICAL, INTENT(IN) :: physical
88 TYPE(phason_result_type), INTENT(OUT) :: report
89 INTEGER, INTENT(IN) :: io_unit
90 CHARACTER(LEN=256) :: header
91 CHARACTER(LEN=default_path_length), ALLOCATABLE :: files(:)
92 INTEGER :: input, store, stat, dim, rank, nvertex, nframe, nat, vertex, axis, mu, nu, p, i, j, na, nb, nbase, idx
93 INTEGER, ALLOCATABLE :: shape(:), extended(:), index(:), next(:), zero(:), points(:), permutation(:, :)
94 LOGICAL, ALLOCATABLE :: checked(:)
95 REAL(kind=dp), ALLOCATABLE :: offsets(:), directions(:, :)
96 REAL(kind=dp) :: origin(3), ka(3), kb(3), tol_metric, tol_gap, tol_sv, phase_limit, minimum, local_min, &
97 max_metric, min_gap, err, gap, value, contribution, max_phase, local_phase, seam_error, &
98 valence_max, conduction_min, energy_shift, compensation, y, t
99 COMPLEX(KIND=dp), ALLOCATABLE :: raw(:, :), link(:, :), sewing(:, :), u(:, :, :), pqs(:, :, :)
100 TYPE(snapshot_type), ALLOCATABLE :: a, b, base
101 LOGICAL :: common_reference, prefix
102 INTEGER(KIND=int64) :: record_size, record_start, total
103
104 CALL open_file(path, unit_number=input, file_status='OLD', file_action='READ')
105 READ (input, '(A)', iostat=stat) header
106 cpassert(stat == 0)
107 IF (physical) THEN
108 IF (trim(header) /= 'CP2K_PHASON_MESH 1') THEN
109 cpabort('Expected CP2K_PHASON_MESH 1')
110 END IF
111 ELSE
112 IF (trim(header) /= 'CP2K_TOPOLOGY_LINKS 1') THEN
113 cpabort('Expected CP2K_TOPOLOGY_LINKS 1')
114 END IF
115 END IF
116 READ (input, *, iostat=stat) dim, rank
117 cpassert(stat == 0)
118 IF ((dim /= 2 .AND. dim /= 4) .OR. rank < 1) THEN
119 cpabort('Invalid mesh dimension or rank')
120 END IF
121 ALLOCATE (shape(dim), extended(dim), index(dim), next(dim), zero(dim))
122 READ (input, *, iostat=stat) shape
123 cpassert(stat == 0)
124 IF (any(shape < 3)) THEN
125 cpabort('At least three samples per mesh axis are required')
126 END IF
127 total = 1_int64
128 DO axis = 1, dim
129 IF (total > int(huge(1), int64)/int(shape(axis) + 1, int64)) THEN
130 cpabort('Mesh index overflow')
131 END IF
132 total = total*int(shape(axis) + 1, int64)
133 END DO
134 extended(:) = shape + 1
135 nvertex = product(shape)
136 nframe = int(total)
137 report%dimension = dim
138 report%rank = rank
139 report%shape(1:dim) = shape
140 READ (input, *, iostat=stat) tol_metric, tol_gap, tol_sv, phase_limit
141 cpassert(stat == 0)
142 IF (.NOT. all(ieee_is_finite([tol_metric, tol_gap, tol_sv, phase_limit]))) THEN
143 cpabort('Nonfinite tolerances')
144 END IF
145 IF (min(tol_metric, tol_gap, tol_sv, phase_limit) <= 0.0_dp .OR. max(tol_metric, tol_sv) >= 1.0_dp .OR. &
146 phase_limit >= acos(-1.0_dp)) THEN
147 cpabort('Invalid mesh tolerances')
148 END IF
149 ALLOCATE (raw(rank, rank), link(rank, rank), sewing(rank, rank), u(rank, rank, 4), pqs(rank, rank, dim*(dim - 1)/2))
150 ! Anonymous scratch storage avoids persistent, stale link caches.
151 CALL open_file(unit_number=store, file_status='SCRATCH', file_access='STREAM', &
152 file_form='UNFORMATTED', file_action='READWRITE')
153 INQUIRE (unit=store, pos=record_start, iostat=stat)
154 cpassert(stat == 0)
155 minimum = huge(1.0_dp)
156 max_metric = 0.0_dp
157 min_gap = huge(1.0_dp)
158 seam_error = 0.0_dp
159 valence_max = -huge(1.0_dp)
160 conduction_min = huge(1.0_dp)
161 common_reference = .false.
162 prefix = .true.
163 IF (physical) THEN
164 ALLOCATE (a, b, base)
165 ALLOCATE (files(nframe), points(nframe), offsets(nframe), checked(nframe), directions(3, dim))
166 checked(:) = .false.
167 READ (input, *, iostat=stat) origin
168 cpassert(stat == 0)
169 IF (.NOT. all(ieee_is_finite(origin))) THEN
170 cpabort('Nonfinite mesh origin')
171 END IF
172 DO axis = 1, dim
173 READ (input, *, iostat=stat) directions(:, axis)
174 cpassert(stat == 0)
175 END DO
176 IF (.NOT. all(ieee_is_finite(directions))) THEN
177 cpabort('Nonfinite reciprocal periods')
178 END IF
179 IF (maxval(abs(directions - anint(directions))) > 1.e-10_dp) THEN
180 cpabort('Noninteger reciprocal periods')
181 END IF
182 READ (input, *, iostat=stat) nat, common_reference
183 cpassert(stat == 0)
184 IF (nat < 1) THEN
185 cpabort('Invalid mesh atom count')
186 END IF
187 ALLOCATE (permutation(nat, dim))
188 DO axis = 1, dim
189 READ (input, *, iostat=stat) permutation(:, axis)
190 cpassert(stat == 0)
191 IF (any(permutation(:, axis) < 1) .OR. any(permutation(:, axis) > nat)) THEN
192 cpabort('Invalid seam permutation')
193 END IF
194 DO idx = 1, nat
195 IF (count(permutation(:, axis) == idx) /= 1) THEN
196 cpabort('Non-bijective seam map')
197 END IF
198 END DO
199 END DO
200 DO mu = 1, dim
201 DO nu = mu + 1, dim
202 IF (any(permutation(permutation(:, mu), nu) /= permutation(permutation(:, nu), mu))) THEN
203 cpabort('The declared torus atom permutations do not commute')
204 END IF
205 END DO
206 END DO
207 DO idx = 1, nframe
208 READ (input, *, iostat=stat) files(idx), points(idx), offsets(idx)
209 cpassert(stat == 0)
210 IF (points(idx) < 1 .OR. .NOT. ieee_is_finite(offsets(idx))) THEN
211 cpabort('Invalid frame record')
212 END IF
213 END DO
214 report%nat = nat
215 report%origin(:) = origin
216 report%directions(:, 1:dim) = directions
217 report%first_file = files(1)
218 report%point = points(1)
219 END IF
220 DO vertex = 1, nvertex
221 CALL unflat(vertex, shape, index)
222 IF (physical) THEN
223 na = flat(index, extended)
224 CALL frame(na, a)
225 ka(:) = origin + matmul(directions, real(index, dp)/real(shape, dp))
226 END IF
227 DO axis = 1, dim
228 IF (physical) THEN
229 next(:) = index
230 next(axis) = next(axis) + 1
231 nb = flat(next, extended)
232 CALL frame(nb, b)
233 kb(:) = origin + matmul(directions, real(next, dp)/real(shape, dp))
234 CALL snapshot_overlap(a, b, ka, kb, raw)
235 IF (next(axis) == shape(axis)) THEN
236 zero(:) = next
237 zero(axis) = 0
238 nbase = flat(zero, extended)
239 CALL frame(nbase, base)
240 CALL check_snapshot_seam(base, b, permutation(:, axis), tol_metric)
241 CALL snapshot_overlap(b, base, kb, kb, sewing)
242 ! Both endpoint frames must span the same physical subspace, not merely have full rank.
243 link(:, :) = matmul(conjg(transpose(sewing)), sewing)
244 DO idx = 1, rank
245 link(idx, idx) = link(idx, idx) - 1.0_dp
246 END DO
247 err = maxval(abs(link))
248 seam_error = max(seam_error, err)
249 IF (err > tol_metric) THEN
250 cpabort('Endpoint selected subspaces do not close')
251 END IF
252 CALL polar_link(sewing, link, local_min, stat, tol_sv)
253 IF (stat /= 0) THEN
254 cpabort('Invalid endpoint sewing link')
255 END IF
256 raw(:, :) = matmul(raw, link)
257 END IF
258 ELSE
259 DO j = 1, rank
260 DO i = 1, rank
261 READ (input, *, iostat=stat) ka(1:2)
262 cpassert(stat == 0)
263 raw(i, j) = cmplx(ka(1), ka(2), dp)
264 END DO
265 END DO
266 END IF
267 CALL polar_link(raw, link, local_min, stat, tol_sv)
268 IF (stat /= 0) THEN
269 cpabort('Singular/nonfinite mesh link; refine or check the subspace')
270 END IF
271 minimum = min(minimum, local_min)
272 WRITE (store, iostat=stat) link
273 cpassert(stat == 0)
274 IF (vertex == 1 .AND. axis == 1) THEN
275 ! Measure the stride in stream-position units; IOLENGTH may use different units.
276 INQUIRE (unit=store, pos=record_size, iostat=stat)
277 cpassert(stat == 0)
278 record_size = record_size - record_start
279 END IF
280 END DO
281 END DO
282 DO
283 READ (input, '(A)', iostat=stat) header
284 IF (stat < 0) EXIT
285 IF (stat /= 0 .OR. len_trim(header) /= 0) THEN
286 cpabort('Unexpected trailing mesh data')
287 END IF
288 END DO
289 CALL close_file(input)
290 value = 0.0_dp
291 compensation = 0.0_dp
292 max_phase = 0.0_dp
293 DO vertex = 1, nvertex
294 CALL unflat(vertex, shape, index)
295 p = 0
296 DO mu = 1, dim
297 DO nu = mu + 1, dim
298 p = p + 1
299 CALL read_link(vertex, mu, u(:, :, 1))
300 next(:) = index
301 next(mu) = mod(next(mu) + 1, shape(mu))
302 CALL read_link(flat(next, shape), nu, u(:, :, 2))
303 next(:) = index
304 next(nu) = mod(next(nu) + 1, shape(nu))
305 CALL read_link(flat(next, shape), mu, u(:, :, 3))
306 CALL read_link(vertex, nu, u(:, :, 4))
307 CALL link_plaquette(u(:, :, 1), u(:, :, 2), u(:, :, 3), u(:, :, 4), pqs(:, :, p))
308 END DO
309 END DO
310 CALL curvature_density(pqs, dim, phase_limit, contribution, local_phase, stat)
311 IF (stat /= 0) THEN
312 cpabort('Unresolved/nonunitary plaquette; refine the mesh')
313 END IF
314 max_phase = max(max_phase, local_phase)
315 y = contribution - compensation
316 t = value + y
317 compensation = (t - value) - y
318 value = t
319 END DO
320 CALL close_file(store)
321 report%value = value
322 WRITE (io_unit, '(A,I0)') 'PARAMETER_DIMENSION ', dim
323 WRITE (io_unit, '(A,*(I0,1X))') 'MESH ', shape
324 WRITE (io_unit, '(A,ES26.17)') 'CHERN_RAW ', value
325 WRITE (io_unit, '(A,ES26.17)') 'MINIMUM_LINK_SINGULAR_VALUE ', minimum
326 WRITE (io_unit, '(A,ES26.17)') 'MAXIMUM_PLAQUETTE_PHASE ', max_phase
327 IF (physical) THEN
328 WRITE (io_unit, '(A,ES26.17)') 'MAXIMUM_METRIC_ERROR ', max_metric
329 WRITE (io_unit, '(A,ES26.17)') 'MAXIMUM_SEAM_ERROR ', seam_error
330 WRITE (io_unit, '(A,ES26.17)') 'MINIMUM_DIRECT_GAP_HA ', min_gap
331 IF (common_reference .AND. prefix) THEN
332 WRITE (io_unit, '(A,ES26.17)') 'SAMPLED_INDIRECT_GAP_HA ', conduction_min - valence_max
333 ELSE
334 WRITE (io_unit, '(A)') 'INDIRECT_GAP_NOT_EVALUATED: no asserted common energy reference or not a lowest-band prefix'
335 END IF
336 END IF
337 WRITE (io_unit, '(A)') 'MESH_CONVERGENCE_NOT_ESTABLISHED: repeat on finer meshes; retain unrounded C2 values.'
338 CONTAINS
339! **************************************************************************************************
340!> \brief Read one frame and update validation diagnostics on its first use.
341!> \param number One-based frame index in the extended mesh
342!> \param state Physical frame with selected coefficients
343! **************************************************************************************************
344 SUBROUTINE frame(number, state)
345 INTEGER, INTENT(IN) :: number
346 TYPE(snapshot_type), INTENT(OUT) :: state
347
348 INTEGER :: iband
349
350 CALL read_snapshot(trim(files(number)), points(number), state)
351 IF (state%rank /= rank .OR. SIZE(state%atoms) /= nat) THEN
352 cpabort('Frame rank/atom count differs from manifest')
353 END IF
354 IF (.NOT. checked(number)) THEN
355 CALL check_snapshot(state, tol_metric, tol_gap, err, gap)
356 max_metric = max(max_metric, err)
357 min_gap = min(min_gap, gap)
358 checked(number) = .true.
359 DO iband = 1, rank
360 IF (state%bands(iband) /= iband) prefix = .false.
361 END DO
362 IF (rank >= SIZE(state%energies)) prefix = .false.
363 IF (prefix) THEN
364 energy_shift = offsets(number)
365 valence_max = max(valence_max, state%energies(rank) + energy_shift)
366 conduction_min = min(conduction_min, state%energies(rank + 1) + energy_shift)
367 END IF
368 END IF
369 END SUBROUTINE frame
370! **************************************************************************************************
371!> \brief Read a previously validated link from the scratch stream.
372!> \param vertex_index One-based mesh vertex
373!> \param direction One-based parameter axis
374!> \param matrix Unitary selected-state link
375! **************************************************************************************************
376 SUBROUTINE read_link(vertex_index, direction, matrix)
377 INTEGER, INTENT(IN) :: vertex_index, direction
378 COMPLEX(KIND=dp), INTENT(OUT) :: matrix(:, :)
379
380 INTEGER(KIND=int64) :: position
381
382 position = (int(vertex_index - 1, int64)*int(dim, int64) + int(direction - 1, int64))*record_size + 1_int64
383 READ (store, pos=position, iostat=stat) matrix
384 cpassert(stat == 0)
385 END SUBROUTINE read_link
386 END SUBROUTINE analyze_mesh
387
388! **************************************************************************************************
389!> \brief Compare two jointly refined meshes of the same declared family; never round the estimate.
390!> \param coarse Coarser mesh report
391!> \param fine Finer mesh report
392!> \param tolerance Maximum inter-mesh difference and distance to an integer
393!> \param io_unit Unit receiving convergence diagnostics
394! **************************************************************************************************
395 SUBROUTINE compare_refinements(coarse, fine, tolerance, io_unit)
396 TYPE(phason_result_type), INTENT(IN) :: coarse, fine
397 REAL(kind=dp), INTENT(IN) :: tolerance
398 INTEGER, INTENT(IN) :: io_unit
399 TYPE(snapshot_type), ALLOCATABLE :: a, b
400 COMPLEX(KIND=dp), ALLOCATABLE :: m(:, :), metric(:, :)
401 INTEGER :: dim, i
402 REAL(kind=dp) :: difference, residual
403 IF (.NOT. ieee_is_finite(tolerance)) THEN
404 cpabort('Nonfinite convergence tolerance')
405 END IF
406 IF (tolerance <= 0.0_dp .OR. tolerance >= 0.5_dp) THEN
407 cpabort('Invalid convergence tolerance')
408 END IF
409 dim = coarse%dimension
410 IF (fine%dimension /= dim .OR. fine%rank /= coarse%rank .OR. fine%nat /= coarse%nat) THEN
411 cpabort('Incompatible refinement reports')
412 END IF
413 DO i = 1, dim
414 IF (fine%shape(i) < 2*coarse%shape(i) .OR. mod(fine%shape(i), coarse%shape(i)) /= 0) THEN
415 cpabort('Refine every mesh axis by an integer factor of at least two')
416 END IF
417 END DO
418 IF (maxval(abs(coarse%origin - fine%origin)) > 1.e-10_dp .OR. &
419 maxval(abs(coarse%directions - fine%directions)) > 1.e-10_dp) THEN
420 cpabort('Refinement changes the parameter origin or reciprocal periods')
421 END IF
422 IF (coarse%nat > 0) THEN
423 ALLOCATE (a, b)
424 CALL read_snapshot(trim(coarse%first_file), coarse%point, a)
425 CALL read_snapshot(trim(fine%first_file), fine%point, b)
426 ALLOCATE (m(a%rank, a%rank), metric(a%rank, a%rank))
427 CALL snapshot_overlap(a, b, a%k, a%k, m)
428 metric(:, :) = matmul(conjg(transpose(m)), m)
429 DO i = 1, a%rank
430 metric(i, i) = metric(i, i) - 1.0_dp
431 END DO
432 IF (maxval(abs(metric)) > 1.e-7_dp) THEN
433 cpabort('Refinement changes the initial physical subspace')
434 END IF
435 END IF
436 difference = abs(fine%value - coarse%value)
437 residual = abs(fine%value - anint(fine%value))
438 WRITE (io_unit, '(A,ES26.17)') 'REFINEMENT_CHANGE ', difference
439 WRITE (io_unit, '(A,ES26.17)') 'INTEGER_RESIDUAL ', residual
440 IF (difference > tolerance .OR. residual > tolerance) THEN
441 cpabort('Chern mesh refinement has not converged to the requested tolerance')
442 END IF
443 WRITE (io_unit, '(A)') 'REFINEMENT_CHECK_PASSED: numerical check, not a certificate of a bulk gap.'
444 END SUBROUTINE compare_refinements
static GRID_HOST_DEVICE int idx(const orbital a)
Return coset index of given orbital angular momentum.
Utility routines to open and close files.
Definition cp_files.F:22
subroutine, public open_file(file_name, unit_number, file_status, file_form, file_action, file_position, file_pad, file_access, debug)
Opens a file and returns its logical unit number.
Definition cp_files.F:197
subroutine, public close_file(unit_number, file_status)
Closes an open file given by its logical unit number.
Definition cp_files.F:64
Defines the basic variable types.
Definition kinds.F:23
integer, parameter, public dp
Definition kinds.F:34
integer, parameter, public default_path_length
Definition kinds.F:58
Gauge-covariant C1/C2 plaquette kernels, independent of the state representation.
subroutine, public polar_link(overlap, link, minimum, status, tolerance)
Polar-unitarize a physical link, retaining its minimum singular value.
subroutine, public link_plaquette(u_mu, u_nu_at_mu, u_mu_at_nu, u_nu, p)
Oriented plaquette U_mu(x) U_nu(x+mu) U_mu(x+nu)^dagger U_nu(x)^dagger.
subroutine, public curvature_density(plaquettes, ndim, phase_limit, value, maximum, status)
Local contribution to C1 or C2. Report unrounded values and reject unresolved phases.
Native streaming mesh analysis with physical endpoint sewing.
subroutine, public analyze_mesh(path, physical, report, io_unit)
Build physical links or read reference links; stream plaquettes through an anonymous file.
integer function flat(index, shape)
Flatten a zero-based index with the first coordinate varying fastest.
subroutine, public compare_refinements(coarse, fine, tolerance, io_unit)
Compare two jointly refined meshes of the same declared family; never round the estimate.
Reader and physical moving-basis links for version-1 topology snapshots.
subroutine, public check_snapshot_seam(a, b, permutation, tolerance)
Check explicitly prescribed atom permutation, periodic translations and basis at a seam.
subroutine, public snapshot_overlap(a, b, ka, kb, overlap)
Apply screened Gaussian cross-geometry operator by atom blocks, without a dense AO matrix.
subroutine, public check_snapshot(a, metric_tol, gap_tol, metric_error, gap)
Check AO-metric normalization and separation at every selected/excluded boundary.
subroutine, public read_snapshot(filename, point, state)
Read a single point, retaining only its states; reject malformed/truncated exports.