1use std::fmt;
4use std::ops::Mul;
5
6use anyhow::{self, bail, format_err};
7use derive_builder::Builder;
8use duplicate::duplicate_item;
9use nalgebra::Point3;
10use ndarray::Array1;
11use ndarray_linalg::types::Lapack;
12use num_complex::{Complex, ComplexFloat};
13use num_traits::Float;
14use serde::{Deserialize, Serialize};
15
16use crate::analysis::{
17 EigenvalueComparisonMode, Orbit, Overlap, ProjectionDecomposition, RepAnalysis,
18 log_overlap_eigenvalues,
19};
20use crate::chartab::SubspaceDecomposable;
21use crate::chartab::chartab_group::CharacterProperties;
22use crate::drivers::QSym2Driver;
23use crate::drivers::representation_analysis::angular_function::{
24 AngularFunctionRepAnalysisParams, find_angular_function_representation,
25 find_spinor_function_representation,
26};
27use crate::drivers::representation_analysis::{
28 CharacterTableDisplay, MagneticSymmetryAnalysisKind, fn_construct_magnetic_group,
29 fn_construct_unitary_group, log_cc_transversal,
30};
31use crate::drivers::symmetry_group_detection::SymmetryGroupDetectionResult;
32use crate::group::{GroupProperties, MagneticRepresentedGroup, UnitaryRepresentedGroup};
33use crate::io::format::{
34 QSym2Output, log_subtitle, nice_bool, qsym2_output, write_subtitle, write_title,
35};
36use crate::sandbox::target::real_space_function::RealSpaceFunction;
37use crate::sandbox::target::real_space_function::real_space_function_analysis::RealSpaceFunctionSymmetryOrbit;
38use crate::symmetry::symmetry_group::{
39 MagneticRepresentedSymmetryGroup, SymmetryGroupProperties, UnitaryRepresentedSymmetryGroup,
40};
41use crate::symmetry::symmetry_transformation::SymmetryTransformationKind;
42
43#[cfg(test)]
44#[path = "real_space_function_tests.rs"]
45mod real_space_function_tests;
46
47const fn default_true() -> bool {
56 true
57}
58const fn default_symbolic() -> Option<CharacterTableDisplay> {
59 Some(CharacterTableDisplay::Symbolic)
60}
61
62#[derive(Clone, Builder, Debug, Serialize, Deserialize)]
64pub struct RealSpaceFunctionRepAnalysisParams<T: From<f64>> {
65 pub integrality_threshold: T,
67
68 pub linear_independence_threshold: T,
70
71 pub orbit_overlap_symmetry_threshold: T,
73
74 #[builder(default = "None")]
77 #[serde(default)]
78 pub use_magnetic_group: Option<MagneticSymmetryAnalysisKind>,
79
80 #[builder(default = "false")]
82 #[serde(default)]
83 pub use_double_group: bool,
84
85 #[builder(default = "true")]
88 #[serde(default = "default_true")]
89 pub use_cayley_table: bool,
90
91 #[builder(default = "SymmetryTransformationKind::Spatial")]
94 #[serde(default)]
95 pub symmetry_transformation_kind: SymmetryTransformationKind,
96
97 #[builder(default = "Some(CharacterTableDisplay::Symbolic)")]
100 #[serde(default = "default_symbolic")]
101 pub write_character_table: Option<CharacterTableDisplay>,
102
103 #[builder(default = "true")]
105 #[serde(default = "default_true")]
106 pub write_overlap_eigenvalues: bool,
107
108 #[builder(default = "EigenvalueComparisonMode::Modulus")]
110 #[serde(default)]
111 pub eigenvalue_comparison_mode: EigenvalueComparisonMode,
112
113 #[builder(default = "None")]
116 #[serde(default)]
117 pub infinite_order_to_finite: Option<u32>,
118}
119
120impl<T> RealSpaceFunctionRepAnalysisParams<T>
121where
122 T: Float + From<f64>,
123{
124 pub fn builder() -> RealSpaceFunctionRepAnalysisParamsBuilder<T> {
126 RealSpaceFunctionRepAnalysisParamsBuilder::default()
127 }
128}
129
130impl Default for RealSpaceFunctionRepAnalysisParams<f64> {
131 fn default() -> Self {
132 Self::builder()
133 .integrality_threshold(1e-7)
134 .linear_independence_threshold(1e-7)
135 .build()
136 .expect("Unable to construct a default `RealSpaceFunctionRepAnalysisParams<f64>`.")
137 }
138}
139
140impl<T> fmt::Display for RealSpaceFunctionRepAnalysisParams<T>
141where
142 T: From<f64> + fmt::LowerExp + fmt::Debug,
143{
144 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
145 writeln!(
146 f,
147 "Integrality threshold: {:.3e}",
148 self.integrality_threshold
149 )?;
150 writeln!(
151 f,
152 "Linear independence threshold: {:.3e}",
153 self.linear_independence_threshold
154 )?;
155 writeln!(
156 f,
157 "Orbit eigenvalue comparison mode: {}",
158 self.eigenvalue_comparison_mode
159 )?;
160 writeln!(
161 f,
162 "Write overlap eigenvalues: {}",
163 nice_bool(self.write_overlap_eigenvalues)
164 )?;
165 writeln!(f)?;
166 writeln!(
167 f,
168 "Use magnetic group for analysis: {}",
169 match self.use_magnetic_group {
170 None => "no",
171 Some(MagneticSymmetryAnalysisKind::Representation) =>
172 "yes, using unitary representations",
173 Some(MagneticSymmetryAnalysisKind::Corepresentation) =>
174 "yes, using magnetic corepresentations",
175 }
176 )?;
177 writeln!(
178 f,
179 "Use double group for analysis: {}",
180 nice_bool(self.use_double_group)
181 )?;
182 writeln!(
183 f,
184 "Use Cayley table for orbit overlap matrices: {}",
185 nice_bool(self.use_cayley_table)
186 )?;
187 if let Some(finite_order) = self.infinite_order_to_finite {
188 writeln!(f, "Infinite order to finite: {finite_order}")?;
189 }
190 writeln!(
191 f,
192 "Symmetry transformation kind: {}",
193 self.symmetry_transformation_kind
194 )?;
195 writeln!(f)?;
196 writeln!(
197 f,
198 "Write character table: {}",
199 if let Some(chartab_display) = self.write_character_table.as_ref() {
200 format!("yes, {}", chartab_display.to_string().to_lowercase())
201 } else {
202 "no".to_string()
203 }
204 )?;
205
206 Ok(())
207 }
208}
209
210#[derive(Clone, Builder)]
216pub struct RealSpaceFunctionRepAnalysisResult<'a, G, T, F>
217where
218 G: SymmetryGroupProperties + Clone,
219 G::CharTab: SubspaceDecomposable<T>,
220 T: ComplexFloat + Lapack,
221 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
222 F: Clone + Fn(&Point3<f64>) -> T,
223{
224 parameters: &'a RealSpaceFunctionRepAnalysisParams<<T as ComplexFloat>::Real>,
227
228 real_space_function: &'a RealSpaceFunction<T, F>,
230
231 group: G,
233
234 real_space_function_symmetry:
236 Result<<G::CharTab as SubspaceDecomposable<T>>::Decomposition, String>,
237}
238
239impl<'a, G, T, F> RealSpaceFunctionRepAnalysisResult<'a, G, T, F>
240where
241 G: SymmetryGroupProperties + Clone,
242 G::CharTab: SubspaceDecomposable<T>,
243 T: ComplexFloat + Lapack,
244 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
245 F: Clone + Fn(&Point3<f64>) -> T,
246{
247 pub fn builder() -> RealSpaceFunctionRepAnalysisResultBuilder<'a, G, T, F> {
249 RealSpaceFunctionRepAnalysisResultBuilder::default()
250 }
251}
252
253impl<'a, G, T, F> fmt::Display for RealSpaceFunctionRepAnalysisResult<'a, G, T, F>
254where
255 G: SymmetryGroupProperties + Clone,
256 G::CharTab: SubspaceDecomposable<T>,
257 T: ComplexFloat + Lapack,
258 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug + fmt::Display,
259 F: Clone + Fn(&Point3<f64>) -> T,
260{
261 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
262 write_subtitle(f, "Orbit-based symmetry analysis results")?;
263 writeln!(f)?;
264 writeln!(
265 f,
266 "> Group: {} ({})",
267 self.group
268 .finite_subgroup_name()
269 .map(|subgroup_name| format!("{} > {}", self.group.name(), subgroup_name))
270 .unwrap_or(self.group.name()),
271 self.group.group_type().to_string().to_lowercase()
272 )?;
273 writeln!(f)?;
274 writeln!(f, "> Overall real-space function result")?;
275 writeln!(
276 f,
277 " Grid size: {} {}",
278 self.real_space_function.grid_points().len(),
279 if self.real_space_function.grid_points().len() == 1 {
280 "point"
281 } else {
282 "points"
283 }
284 )?;
285 writeln!(
286 f,
287 " Symmetry: {}",
288 self.real_space_function_symmetry
289 .as_ref()
290 .map(|s| s.to_string())
291 .unwrap_or_else(|err| format!("-- ({err})"))
292 )?;
293 writeln!(f)?;
294
295 Ok(())
296 }
297}
298
299impl<'a, G, T, F> fmt::Debug for RealSpaceFunctionRepAnalysisResult<'a, G, T, F>
300where
301 G: SymmetryGroupProperties + Clone,
302 G::CharTab: SubspaceDecomposable<T>,
303 T: ComplexFloat + Lapack,
304 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug + fmt::Display,
305 F: Clone + Fn(&Point3<f64>) -> T,
306{
307 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
308 writeln!(f, "{self}")
309 }
310}
311
312impl<'a, G, T, F> RealSpaceFunctionRepAnalysisResult<'a, G, T, F>
313where
314 G: SymmetryGroupProperties + Clone,
315 G::CharTab: SubspaceDecomposable<T>,
316 T: ComplexFloat + Lapack,
317 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug + fmt::Display,
318 F: Clone + Fn(&Point3<f64>) -> T,
319{
320 pub fn real_space_function_symmetry(
322 &self,
323 ) -> &Result<<G::CharTab as SubspaceDecomposable<T>>::Decomposition, String> {
324 &self.real_space_function_symmetry
325 }
326
327 pub fn parameters(&self) -> &RealSpaceFunctionRepAnalysisParams<<T as ComplexFloat>::Real> {
329 self.parameters
330 }
331}
332
333#[derive(Clone, Builder)]
343#[builder(build_fn(validate = "Self::validate"))]
344pub struct RealSpaceFunctionRepAnalysisDriver<'a, G, T, F>
345where
346 G: SymmetryGroupProperties + Clone,
347 G::CharTab: SubspaceDecomposable<T>,
348 T: ComplexFloat + Lapack,
349 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
350 F: Clone + Fn(&Point3<f64>) -> T,
351{
352 parameters: &'a RealSpaceFunctionRepAnalysisParams<<T as ComplexFloat>::Real>,
354
355 real_space_function: &'a RealSpaceFunction<T, F>,
357
358 symmetry_group: &'a SymmetryGroupDetectionResult,
361
362 weight: &'a Array1<T>,
364
365 angular_function_parameters: &'a AngularFunctionRepAnalysisParams,
367
368 #[builder(setter(skip), default = "None")]
370 result: Option<RealSpaceFunctionRepAnalysisResult<'a, G, T, F>>,
371}
372
373impl<'a, G, T, F> RealSpaceFunctionRepAnalysisDriverBuilder<'a, G, T, F>
374where
375 G: SymmetryGroupProperties + Clone,
376 G::CharTab: SubspaceDecomposable<T>,
377 T: ComplexFloat + Lapack,
378 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
379 F: Clone + Fn(&Point3<f64>) -> T,
380{
381 fn validate(&self) -> Result<(), String> {
382 let _ = self
383 .real_space_function
384 .ok_or("No real-space function specified.".to_string())?;
385
386 let params = self.parameters.ok_or(
387 "No real-space function representation analysis parameters found.".to_string(),
388 )?;
389
390 let sym_res = self
391 .symmetry_group
392 .ok_or("No symmetry group information found.".to_string())?;
393
394 let sym = if params.use_magnetic_group.is_some() {
395 sym_res
396 .magnetic_symmetry
397 .as_ref()
398 .ok_or("Magnetic symmetry requested for representation analysis, but no magnetic symmetry found.")?
399 } else {
400 &sym_res.unitary_symmetry
401 };
402
403 if sym.is_infinite() && params.infinite_order_to_finite.is_none() {
404 Err(format!(
405 "Representation analysis cannot be performed using the entirety of the infinite group `{}`. \
406 Consider setting the parameter `infinite_order_to_finite` to restrict to a finite subgroup instead.",
407 sym.group_name
408 .as_ref()
409 .expect("No symmetry group name found.")
410 ))
411 } else {
412 Ok(())
413 }
414 }
415}
416
417impl<'a, G, T, F> RealSpaceFunctionRepAnalysisDriver<'a, G, T, F>
425where
426 G: SymmetryGroupProperties + Clone,
427 G::CharTab: SubspaceDecomposable<T>,
428 T: ComplexFloat + Lapack,
429 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
430 F: Clone + Fn(&Point3<f64>) -> T,
431{
432 pub fn builder() -> RealSpaceFunctionRepAnalysisDriverBuilder<'a, G, T, F> {
434 RealSpaceFunctionRepAnalysisDriverBuilder::default()
435 }
436}
437
438impl<'a, T, F> RealSpaceFunctionRepAnalysisDriver<'a, UnitaryRepresentedSymmetryGroup, T, F>
442where
443 T: ComplexFloat + Lapack + Sync + Send,
444 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug + Sync + Send,
445 for<'b> Complex<f64>: Mul<&'b T, Output = Complex<f64>>,
446 F: Clone + Fn(&Point3<f64>) -> T,
447{
448 fn_construct_unitary_group!(
449 construct_unitary_group
452 );
453}
454
455impl<'a, T, F> RealSpaceFunctionRepAnalysisDriver<'a, MagneticRepresentedSymmetryGroup, T, F>
459where
460 T: ComplexFloat + Lapack + Sync + Send,
461 <T as ComplexFloat>::Real: From<f64> + Sync + Send + fmt::LowerExp + fmt::Debug,
462 for<'b> Complex<f64>: Mul<&'b T, Output = Complex<f64>>,
463 F: Clone + Fn(&Point3<f64>) -> T,
464{
465 fn_construct_magnetic_group!(
466 construct_magnetic_group
469 );
470}
471
472#[duplicate_item(
476 duplicate!{
477 [ dtype_nested; [f64]; [Complex<f64>] ]
478 [
479 gtype_ [ UnitaryRepresentedSymmetryGroup ]
480 dtype_ [ dtype_nested ]
481 doc_sub_ [ "Performs representation analysis using a unitary-represented group and stores the result." ]
482 analyse_fn_ [ analyse_representation ]
483 construct_group_ [ self.construct_unitary_group()? ]
484 calc_projections_ [
485 log_subtitle("Real-space function projection decompositions");
486 qsym2_output!("");
487 qsym2_output!(" Projections are defined w.r.t. the following inner product:");
488 qsym2_output!(" {}", real_space_function_orbit.origin().overlap_definition());
489 qsym2_output!("");
490 real_space_function_orbit
491 .projections_to_string(
492 &real_space_function_orbit.calc_projection_compositions()?,
493 params.integrality_threshold,
494 )
495 .log_output_display();
496 qsym2_output!("");
497 ]
498 ]
499 }
500 duplicate!{
501 [ dtype_nested; [f64]; [Complex<f64>] ]
502 [
503 gtype_ [ MagneticRepresentedSymmetryGroup ]
504 dtype_ [ dtype_nested ]
505 doc_sub_ [ "Performs corepresentation analysis using a magnetic-represented group and stores the result." ]
506 analyse_fn_ [ analyse_corepresentation ]
507 construct_group_ [ self.construct_magnetic_group()? ]
508 calc_projections_ [ ]
509 ]
510 }
511)]
512impl<'a, F> RealSpaceFunctionRepAnalysisDriver<'a, gtype_, dtype_, F>
513where
514 F: Clone + Sync + Send + Fn(&Point3<f64>) -> dtype_,
515{
516 #[doc = doc_sub_]
517 fn analyse_fn_(&mut self) -> Result<(), anyhow::Error> {
518 let params = self.parameters;
519 let group = construct_group_;
520 log_cc_transversal(&group);
521 let _ = find_angular_function_representation(&group, self.angular_function_parameters);
522 if group.is_double_group() {
523 let _ = find_spinor_function_representation(&group, self.angular_function_parameters);
524 }
525
526 let mut real_space_function_orbit = RealSpaceFunctionSymmetryOrbit::builder()
527 .origin(self.real_space_function)
528 .group(&group)
529 .integrality_threshold(params.integrality_threshold)
530 .linear_independence_threshold(params.linear_independence_threshold)
531 .orbit_overlap_symmetry_threshold(params.orbit_overlap_symmetry_threshold)
532 .symmetry_transformation_kind(params.symmetry_transformation_kind.clone())
533 .eigenvalue_comparison_mode(params.eigenvalue_comparison_mode.clone())
534 .build()?;
535 let real_space_function_symmetry = real_space_function_orbit
536 .calc_smat(Some(self.weight), None, params.use_cayley_table)
537 .and_then(|real_space_function_orb| real_space_function_orb.normalise_smat())
538 .map_err(|err| err.to_string())
539 .and_then(|real_space_function_orb| {
540 real_space_function_orb
541 .calc_xmat(false)
542 .map_err(|err| err.to_string())?;
543 if params.write_overlap_eigenvalues
544 && let Some(smat_eigvals) = real_space_function_orb.smat_eigvals.as_ref()
545 {
546 log_overlap_eigenvalues(
547 "Real-space function orbit overlap eigenvalues",
548 smat_eigvals,
549 params.linear_independence_threshold,
550 ¶ms.eigenvalue_comparison_mode,
551 );
552 qsym2_output!("");
553 }
554 real_space_function_orb
555 .analyse_rep()
556 .map_err(|err| err.to_string())
557 });
558
559 {
560 calc_projections_
561 }
562
563 let result = RealSpaceFunctionRepAnalysisResult::builder()
564 .parameters(params)
565 .real_space_function(self.real_space_function)
566 .group(group)
567 .real_space_function_symmetry(real_space_function_symmetry)
568 .build()?;
569 self.result = Some(result);
570
571 Ok(())
572 }
573}
574
575impl<'a, G, T, F> fmt::Display for RealSpaceFunctionRepAnalysisDriver<'a, G, T, F>
583where
584 G: SymmetryGroupProperties + Clone,
585 G::CharTab: SubspaceDecomposable<T>,
586 T: ComplexFloat + Lapack,
587 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
588 F: Clone + Fn(&Point3<f64>) -> T,
589{
590 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
591 write_title(f, "Real-Space Function Symmetry Analysis")?;
592 writeln!(f)?;
593 writeln!(f, "{}", self.parameters)?;
594 Ok(())
595 }
596}
597
598impl<'a, G, T, F> fmt::Debug for RealSpaceFunctionRepAnalysisDriver<'a, G, T, F>
599where
600 G: SymmetryGroupProperties + Clone,
601 G::CharTab: SubspaceDecomposable<T>,
602 T: ComplexFloat + Lapack,
603 <T as ComplexFloat>::Real: From<f64> + fmt::LowerExp + fmt::Debug,
604 F: Clone + Fn(&Point3<f64>) -> T,
605{
606 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
607 writeln!(f, "{self}")
608 }
609}
610
611#[duplicate_item(
615 duplicate!{
616 [ dtype_nested; [f64]; [Complex<f64>] ]
617 [
618 gtype_ [ UnitaryRepresentedSymmetryGroup ]
619 dtype_ [ dtype_nested ]
620 analyse_fn_ [ analyse_representation ]
621 ]
622 }
623 duplicate!{
624 [ dtype_nested; [f64]; [Complex<f64>] ]
625 [
626 gtype_ [ MagneticRepresentedSymmetryGroup ]
627 dtype_ [ dtype_nested ]
628 analyse_fn_ [ analyse_corepresentation ]
629 ]
630 }
631)]
632impl<'a, F> QSym2Driver for RealSpaceFunctionRepAnalysisDriver<'a, gtype_, dtype_, F>
633where
634 F: Clone + Sync + Send + Fn(&Point3<f64>) -> dtype_,
635{
636 type Params = RealSpaceFunctionRepAnalysisParams<f64>;
637
638 type Outcome = RealSpaceFunctionRepAnalysisResult<'a, gtype_, dtype_, F>;
639
640 fn result(&self) -> Result<&Self::Outcome, anyhow::Error> {
641 self.result
642 .as_ref()
643 .ok_or_else(|| format_err!("No real-space function analysis results found."))
644 }
645
646 fn run(&mut self) -> Result<(), anyhow::Error> {
647 self.log_output_display();
648 self.analyse_fn_()?;
649 self.result()?.log_output_display();
650 Ok(())
651 }
652}