(git:27c966b)
Loading...
Searching...
No Matches
topology_symmetry.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 character decomposition and metric-aware inversion representations.
10! **************************************************************************************************
12 USE ieee_arithmetic, ONLY: ieee_is_finite
13 USE kinds, ONLY: dp
14
15 IMPLICIT NONE
16 PRIVATE
19CONTAINS
20
21! **************************************************************************************************
22!> \brief Lift a Cartesian orthogonal operation to the physical spin-1/2 representation.
23!> \param rotation Cartesian polar-vector operation, including improper operations
24!> \param spin SU(2) lift of det(rotation)*rotation; inversion acts trivially on spin
25!> \param tolerance Orthogonality tolerance
26!> \param status Zero on success, negative for invalid geometry
27!> \note The quaternion sign fixes one representative, not a single-valued SO(3) representation.
28!> Products must retain the resulting double-group factor system. Orbital parity is separate.
29! **************************************************************************************************
30 SUBROUTINE spin_rotation(rotation, spin, tolerance, status)
31 REAL(dp), INTENT(IN) :: rotation(3, 3)
32 COMPLEX(dp), INTENT(OUT) :: spin(2, 2)
33 REAL(dp), INTENT(IN) :: tolerance
34 INTEGER, INTENT(OUT) :: status
35
36 INTEGER :: branch, i, j, k
37 REAL(dp) :: candidates(0:3), det, q(0:3), r(3, 3), &
38 scale, work(3, 3)
39
40 spin = 0.0_dp
41 status = -1
42 IF (.NOT. all(ieee_is_finite(rotation)) .OR. .NOT. ieee_is_finite(tolerance)) RETURN
43 IF (tolerance <= 0.0_dp .OR. tolerance >= 1.0_dp) RETURN
44 work = matmul(transpose(rotation), rotation)
45 DO i = 1, 3
46 work(i, i) = work(i, i) - 1.0_dp
47 END DO
48 IF (maxval(abs(work)) > tolerance) RETURN
49 det = rotation(1, 1)*(rotation(2, 2)*rotation(3, 3) - rotation(2, 3)*rotation(3, 2)) &
50 - rotation(1, 2)*(rotation(2, 1)*rotation(3, 3) - rotation(2, 3)*rotation(3, 1)) &
51 + rotation(1, 3)*(rotation(2, 1)*rotation(3, 2) - rotation(2, 2)*rotation(3, 1))
52 IF (abs(abs(det) - 1.0_dp) > 3*tolerance) RETURN
53 r = sign(1.0_dp, det)*rotation
54 candidates(0) = 1.0_dp + r(1, 1) + r(2, 2) + r(3, 3)
55 DO i = 1, 3
56 candidates(i) = 2.0_dp*(1.0_dp + r(i, i)) - candidates(0)
57 END DO
58 branch = maxloc(candidates, dim=1) - 1
59 scale = 2.0_dp*sqrt(max(0.0_dp, candidates(branch)))
60 q(branch) = 0.25_dp*scale
61 IF (branch == 0) THEN
62 q(1) = (r(3, 2) - r(2, 3))/scale
63 q(2) = (r(1, 3) - r(3, 1))/scale
64 q(3) = (r(2, 1) - r(1, 2))/scale
65 ELSE
66 i = branch
67 j = modulo(i, 3) + 1
68 k = modulo(i + 1, 3) + 1
69 q(0) = (r(k, j) - r(j, k))/scale
70 q(j) = (r(j, i) + r(i, j))/scale
71 q(k) = (r(k, i) + r(i, k))/scale
72 END IF
73 q = q/sqrt(sum(q**2))
74 spin(1, 1) = cmplx(q(0), -q(3), dp)
75 spin(2, 2) = conjg(spin(1, 1))
76 spin(1, 2) = cmplx(-q(2), -q(1), dp)
77 spin(2, 1) = -conjg(spin(1, 2))
78 status = 0
79 END SUBROUTINE spin_rotation
80
81! **************************************************************************************************
82!> \brief Compose orbital, Bloch, physical-spin and optional time-reversal transformations.
83!> \param orbital Scalar AO action from the source to the target k, including all lattice phases
84!> \param spin Unitary spin matrix from spin_rotation
85!> \param source Source spin-major frame
86!> \param antiunitary Apply physical Theta=i*sigma_y*K before the spatial operation
87!> \param image Transformed spin-major frame in the target AO basis
88!> \param tolerance Spin unitarity tolerance
89!> \param status Zero on success, negative for malformed data
90!> \note Orbital metric/Hamiltonian covariance and k mapping must be checked by the caller.
91! **************************************************************************************************
92 SUBROUTINE transform_spinor_frame(orbital, spin, source, antiunitary, image, tolerance, status)
93 COMPLEX(dp), INTENT(IN) :: orbital(:, :), spin(2, 2), source(:, :)
94 LOGICAL, INTENT(IN) :: antiunitary
95 COMPLEX(dp), INTENT(OUT) :: image(:, :)
96 REAL(dp), INTENT(IN) :: tolerance
97 INTEGER, INTENT(OUT) :: status
98
99 COMPLEX(dp) :: gram(2, 2)
100 COMPLEX(dp), ALLOCATABLE :: down(:, :), up(:, :)
101 INTEGER :: m, n
102
103 status = -1
104 image = 0.0_dp
105 n = SIZE(orbital, 2)
106 m = SIZE(orbital, 1)
107 IF (n < 1 .OR. m < 1 .OR. SIZE(source, 1) /= 2*n) RETURN
108 IF (any(shape(image) /= [2*m, SIZE(source, 2)])) RETURN
109 IF (.NOT. ieee_is_finite(tolerance) .OR. tolerance <= 0.0_dp .OR. tolerance >= 1.0_dp) RETURN
110 IF (.NOT. all(ieee_is_finite(real(orbital, dp))) .OR. .NOT. all(ieee_is_finite(aimag(orbital)))) RETURN
111 IF (.NOT. all(ieee_is_finite(real(source, dp))) .OR. .NOT. all(ieee_is_finite(aimag(source)))) RETURN
112 IF (.NOT. all(ieee_is_finite(real(spin, dp))) .OR. .NOT. all(ieee_is_finite(aimag(spin)))) RETURN
113 gram = matmul(conjg(transpose(spin)), spin)
114 gram(1, 1) = gram(1, 1) - 1.0_dp
115 gram(2, 2) = gram(2, 2) - 1.0_dp
116 IF (maxval(abs(gram)) > tolerance) RETURN
117 ALLOCATE (up(m, SIZE(source, 2)), down(m, SIZE(source, 2)))
118 IF (antiunitary) THEN
119 up(:, :) = matmul(orbital, conjg(source(n + 1:, :)))
120 down(:, :) = -matmul(orbital, conjg(source(:n, :)))
121 ELSE
122 up(:, :) = matmul(orbital, source(:n, :))
123 down(:, :) = matmul(orbital, source(n + 1:, :))
124 END IF
125 image(:m, :) = spin(1, 1)*up + spin(1, 2)*down
126 image(m + 1:, :) = spin(2, 1)*up + spin(2, 2)*down
127 IF (.NOT. all(ieee_is_finite(real(image, dp))) .OR. .NOT. all(ieee_is_finite(aimag(image)))) RETURN
128 status = 0
129 END SUBROUTINE transform_spinor_frame
130
131! **************************************************************************************************
132!> \brief Decompose a character against a complete unitary character table.
133!> \param CHARACTER One character per group element (not per conjugacy class)
134!> \param table Characters, group element first and irrep second; identity first
135!> \param multiplicities Nonnegative integer multiplicities, invalid unless status=0
136!> \param tolerance Absolute numerical tolerance
137!> \param status Zero on success, negative for invalid/incomplete/nonintegral data
138!> \note All projective irreps must use the same factor system. This kernel does not
139!> infer a space group or certify the supplied character table's provenance.
140! **************************************************************************************************
141 SUBROUTINE character_multiplicities(CHARACTER, table, multiplicities, tolerance, status)
142 COMPLEX(KIND=dp), INTENT(IN) :: character(:), table(:, :)
143 INTEGER, INTENT(OUT) :: multiplicities(:)
144 REAL(kind=dp), INTENT(IN) :: tolerance
145 INTEGER, INTENT(OUT) :: status
146
147 COMPLEX(KIND=dp) :: value
148 INTEGER :: dimension, i, j, nirrep, order, total
149
150 status = -1
151 multiplicities = -1
152 order = SIZE(character)
153 nirrep = SIZE(table, 2)
154 IF (order < 1 .OR. order > 1024 .OR. nirrep < 1 .OR. SIZE(table, 1) /= order) RETURN
155 IF (SIZE(multiplicities) /= nirrep .OR. tolerance <= 0.0_dp) RETURN
156 IF (.NOT. ieee_is_finite(tolerance)) RETURN
157 IF (.NOT. all(ieee_is_finite(real(CHARACTER, dp)))) return
158 IF (.NOT. all(ieee_is_finite(aimag(character)))) RETURN
159 IF (.NOT. all(ieee_is_finite(real(table, dp)))) RETURN
160 IF (.NOT. all(ieee_is_finite(aimag(table)))) RETURN
161 IF (maxval(abs(table)) > real(order, dp) + tolerance) RETURN
162 IF (maxval(abs(character)) > 1.e6_dp) RETURN
163 total = 0
164 DO i = 1, nirrep
165 dimension = nint(real(table(1, i), dp))
166 IF (dimension < 1 .OR. dimension > order) RETURN
167 IF (abs(table(1, i) - dimension) > tolerance) RETURN
168 total = total + dimension**2
169 IF (total > order) RETURN
170 DO j = 1, nirrep
171 value = sum(conjg(table(:, i))*table(:, j))/real(order, dp)
172 IF (i == j) value = value - 1.0_dp
173 IF (abs(value) > tolerance) RETURN
174 END DO
175 END DO
176 IF (total /= order) RETURN
177 status = -2
178 DO i = 1, nirrep
179 value = sum(conjg(table(:, i))*character)/real(order, dp)
180 j = nint(real(value, dp))
181 IF (j < 0 .OR. abs(value - j) > tolerance) RETURN
182 multiplicities(i) = j
183 END DO
184 IF (maxval(abs(matmul(table, cmplx(multiplicities, 0, dp)) - character)) > tolerance) RETURN
185 status = 0
186 END SUBROUTINE character_multiplicities
187
188! **************************************************************************************************
189!> \brief Inversion irreps of an isolated scalar or spinor eigenspace in an AO metric.
190!> \param metric Scalar AO overlap at a TRIM
191!> \param coeff Selected coefficients, spinor components stacked by AO
192!> \param mapping Target AO index under inversion
193!> \param phase Source-AO multiplier, including orbital parity and lattice phase
194!> \param energies Selected eigenvalues in Hartree
195!> \param check_tr Check physical spinful time reversal as well as inversion
196!> \param tolerance Dimensionless metric/subspace/character tolerance
197!> \param energy_tolerance Eigenvalue-commutator tolerance in Hartree
198!> \param counts Multiplicities of even/odd inversion irreps, counting states not pairs
199!> \param error Largest dimensionless residual
200!> \param energy_error Largest projected symmetry/eigenvalue commutator
201!> \param status Zero on success; invalid output for nonzero status
202!> \param diagnostics Optional metric, normalization, inversion and time-reversal residuals
203! **************************************************************************************************
204 SUBROUTINE inversion_representation(metric, coeff, mapping, phase, energies, check_tr, &
205 tolerance, energy_tolerance, counts, error, energy_error, status, diagnostics)
206 COMPLEX(KIND=dp), INTENT(IN) :: metric(:, :), coeff(:, :)
207 INTEGER, INTENT(IN) :: mapping(:)
208 COMPLEX(KIND=dp), INTENT(IN) :: phase(:)
209 REAL(kind=dp), INTENT(IN) :: energies(:)
210 LOGICAL, INTENT(IN) :: check_tr
211 REAL(kind=dp), INTENT(IN) :: tolerance, energy_tolerance
212 INTEGER, INTENT(OUT) :: counts(2)
213 REAL(kind=dp), INTENT(OUT) :: error, energy_error
214 INTEGER, INTENT(OUT) :: status
215 REAL(kind=dp), INTENT(OUT), OPTIONAL :: diagnostics(4)
216
217 COMPLEX(KIND=dp) :: characters(2), table(2, 2)
218 COMPLEX(KIND=dp), ALLOCATABLE :: pc(:, :), projected(:, :), sc(:, :), &
219 trc(:, :), work(:, :)
220 INTEGER :: first, i, j, last, nao, nspin, rank, s
221 REAL(kind=dp) :: metric_scale
222
223 status = -1
224 counts = -1
225 error = huge(1.0_dp)
226 energy_error = huge(1.0_dp)
227 IF (PRESENT(diagnostics)) diagnostics = huge(1.0_dp)
228 nao = SIZE(metric, 1)
229 rank = SIZE(coeff, 2)
230 IF (nao < 1 .OR. rank < 1 .OR. SIZE(metric, 2) /= nao) RETURN
231 IF (mod(SIZE(coeff, 1), nao) /= 0) RETURN
232 nspin = SIZE(coeff, 1)/nao
233 IF (nspin < 1 .OR. nspin > 2) RETURN
234 IF (check_tr .AND. (nspin /= 2 .OR. mod(rank, 2) /= 0)) RETURN
235 IF (SIZE(mapping) /= nao .OR. SIZE(phase) /= nao .OR. SIZE(energies) /= rank) RETURN
236 IF (tolerance <= 0.0_dp .OR. energy_tolerance <= 0.0_dp) RETURN
237 IF (.NOT. ieee_is_finite(tolerance) .OR. .NOT. ieee_is_finite(energy_tolerance)) RETURN
238 IF (.NOT. all(ieee_is_finite(real(metric, dp))) .OR. .NOT. all(ieee_is_finite(aimag(metric)))) RETURN
239 IF (.NOT. all(ieee_is_finite(real(coeff, dp))) .OR. .NOT. all(ieee_is_finite(aimag(coeff)))) RETURN
240 IF (.NOT. all(ieee_is_finite(real(phase, dp))) .OR. .NOT. all(ieee_is_finite(aimag(phase)))) RETURN
241 IF (.NOT. all(ieee_is_finite(energies))) RETURN
242 IF (any(mapping < 1) .OR. any(mapping > nao)) RETURN
243 IF (any(abs(abs(phase) - 1.0_dp) > tolerance)) RETURN
244 DO i = 1, nao
245 IF (mapping(mapping(i)) /= i) RETURN
246 IF (abs(phase(i)*phase(mapping(i)) - 1.0_dp) > tolerance) RETURN
247 END DO
248 metric_scale = max(1.0_dp, maxval(abs(metric)))
249 error = maxval(abs(metric - conjg(transpose(metric))))/metric_scale
250 DO j = 1, nao
251 DO i = 1, nao
252 error = max(error, abs(conjg(phase(i))*metric(mapping(i), mapping(j))*phase(j) - metric(i, j))/ &
253 metric_scale)
254 END DO
255 END DO
256 IF (PRESENT(diagnostics)) diagnostics(1) = error
257 ALLOCATE (sc(nao*nspin, rank), pc(nao*nspin, rank), projected(rank, rank), work(rank, rank))
258 DO s = 1, nspin
259 first = (s - 1)*nao
260 last = s*nao
261 sc(first + 1:last, :) = matmul(metric, coeff(first + 1:last, :))
262 DO i = 1, nao
263 pc(first + mapping(i), :) = phase(i)*coeff(first + i, :)
264 END DO
265 END DO
266 work(:, :) = matmul(conjg(transpose(coeff)), sc)
267 DO i = 1, rank
268 work(i, i) = work(i, i) - 1.0_dp
269 END DO
270 error = max(error, maxval(abs(work)))
271 IF (PRESENT(diagnostics)) diagnostics(2) = maxval(abs(work))
272 projected(:, :) = matmul(conjg(transpose(sc)), pc)
273 IF (.NOT. all(ieee_is_finite(real(projected, dp)))) RETURN
274 IF (.NOT. all(ieee_is_finite(aimag(projected)))) RETURN
275 work(:, :) = matmul(conjg(transpose(projected)), projected)
276 DO i = 1, rank
277 work(i, i) = work(i, i) - 1.0_dp
278 END DO
279 error = max(error, maxval(abs(work)), maxval(abs(projected - conjg(transpose(projected)))))
280 IF (PRESENT(diagnostics)) diagnostics(3) = max(maxval(abs(work)), &
281 maxval(abs(projected - conjg(transpose(projected)))))
282 IF (PRESENT(diagnostics)) THEN
283 IF (.NOT. check_tr) diagnostics(4) = 0.0_dp
284 END IF
285 energy_error = 0.0_dp
286 DO j = 1, rank
287 DO i = 1, rank
288 energy_error = max(energy_error, abs(projected(i, j)*(energies(i) - energies(j))))
289 END DO
290 END DO
291 characters(1) = cmplx(rank, 0, dp)
292 characters(2) = cmplx(0, 0, dp)
293 DO i = 1, rank
294 characters(2) = characters(2) + projected(i, i)
295 END DO
296 table(:, 1) = cmplx([1, 1], 0, dp)
297 table(:, 2) = cmplx([1, -1], 0, dp)
298 CALL character_multiplicities(characters, table, counts, tolerance*rank, status)
299 IF (status /= 0) RETURN
300 status = -3
301 IF (check_tr) THEN
302 ! In a real Gaussian Bloch basis at a TRIM, Theta=(i sigma_y) K.
303 error = max(error, maxval(abs(aimag(metric)))/max(1.0_dp, maxval(abs(metric))))
304 ALLOCATE (trc(2*nao, rank))
305 trc(:nao, :) = conjg(coeff(nao + 1:, :))
306 trc(nao + 1:, :) = -conjg(coeff(:nao, :))
307 projected(:, :) = matmul(conjg(transpose(sc)), trc)
308 work(:, :) = matmul(conjg(transpose(projected)), projected)
309 DO i = 1, rank
310 work(i, i) = work(i, i) - 1.0_dp
311 END DO
312 error = max(error, maxval(abs(work)), maxval(abs(projected + transpose(projected))))
313 IF (PRESENT(diagnostics)) diagnostics(4) = max(maxval(abs(work)), &
314 maxval(abs(projected + transpose(projected))))
315 DO j = 1, rank
316 DO i = 1, rank
317 energy_error = max(energy_error, abs(projected(i, j)*(energies(i) - energies(j))))
318 END DO
319 END DO
320 IF (any(mod(counts, 2) /= 0)) RETURN
321 END IF
322 IF (.NOT. ieee_is_finite(error) .OR. .NOT. ieee_is_finite(energy_error)) RETURN
323 IF (error > tolerance .OR. energy_error > energy_tolerance) RETURN
324 status = 0
325 END SUBROUTINE inversion_representation
326END MODULE topology_symmetry
static GRID_HOST_DEVICE int modulo(int a, int m)
Equivalent of Fortran's MODULO, which always return a positive number. https://gcc....
static GRID_HOST_DEVICE orbital up(const int i, const orbital a)
Increase i'th component of given orbital angular momentum.
static GRID_HOST_DEVICE orbital down(const int i, const orbital a)
Decrease i'th component of given orbital angular momentum.
Defines the basic variable types.
Definition kinds.F:23
integer, parameter, public dp
Definition kinds.F:34
Native character decomposition and metric-aware inversion representations.
subroutine, public inversion_representation(metric, coeff, mapping, phase, energies, check_tr, tolerance, energy_tolerance, counts, error, energy_error, status, diagnostics)
Inversion irreps of an isolated scalar or spinor eigenspace in an AO metric.
subroutine, public transform_spinor_frame(orbital, spin, source, antiunitary, image, tolerance, status)
Compose orbital, Bloch, physical-spin and optional time-reversal transformations.
subroutine, public character_multiplicities(character, table, multiplicities, tolerance, status)
Decompose a character against a complete unitary character table.
subroutine, public spin_rotation(rotation, spin, tolerance, status)
Lift a Cartesian orthogonal operation to the physical spin-1/2 representation.
Orbital angular momentum.