1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

#![doc(
    html_logo_url = "https://qsym2.dev/assets/logos/qsym2_logo_no_text_no_background.svg",
    html_favicon_url = "https://qsym2.dev/assets/logos/qsym2_icon.png"
)]

//! # QSym²: A Program for Quantum Symbolic Symmetry
//!
//! QSym² is a program for **Q**uantum **Sym**bolic **Sym**metry analysis of
//! quantum-chemical calculations written in Rust with the following capabilities:
//! - on-the-fly generation of symbolic character tables,
//! - analysis of degeneracy and symmetry breaking effects in Abelian and non-Abelian groups,
//! - analysis of symmetry in external magnetic and electric fields,
//! - inclusion of antiunitary symmetry based on corepresentation theory, and
//! - inclusion of double-valued representations and corepresentations via explicit spin rotations
//!
//! for the following targets:
//! - Slater determinants,
//! - molecular orbitals,
//! - multi-determinantal wavefunctions obtained via non-orthogonal configuration interaction,
//! - real-space functions defined on a grid,
//! - electron densities, and
//! - vibrational coordinates.
//!
//! QSym² has been integrated with [QUEST](https://quest.codes/) and its complementary
//! GUI, [QuestView](https://gitlab.com/Bspeake/questview). QSym² can also work with
//! [Q-Chem](https://www.q-chem.com/) HDF5 archive files and
//! [Orca](https://orcaforum.kofo.mpg.de/index.php) output files.
//!
//! The main website for QSym² can be found [here](https://qsym2.dev).
//!
//! QSym² is hosted on [GitLab](https://gitlab.com/bangconghuynh/qsym2). Please submit
//! an issue there if you've encountered anything that is unclear or that you feel needs improving.
//!
//! This documentation details the public API of the `qsym2` crate.
//!
//! ## Help and support
//!
//! Developmental and programming issues with the crate `qsym2` can be reported on
//! [GitLab](https://gitlab.com/bangconghuynh/qsym2). For scientific enquiries such as how to run
//! the program QSym² for a particular quantum-chemical calculation or how to interpret
//! the results of QSym², please join the dedicated [Slack](https://qsym2.slack.com)
//! workspace using this [invite link](https://join.slack.com/t/qsym2/shared_invite/zt-24thj1y1x-JqvLtEA1xfQ9AylNRCDH9w).
//!
//! ## Getting started
//!
//! To use QSym² in your Rust project, simply add this crate to your project's
//! `Cargo.toml`. The available features defined by this crate are:
//!
//! ### Linear algebra backend
//!
//! There are six features defining six different ways a linear algebra backend can be configured
//! for QSym². These are inherited from the
//! [`ndarray-linalg`](https://docs.rs/ndarray-linalg/latest/ndarray_linalg/) crate. One
//! (and only one) of these must be enabled:
//! - `openblas-static`: Downloads, builds OpenBLAS, and links statically
//! - `openblas-system`: Finds and links existing OpenBLAS in the system
//! - `netlib-static`: Downloads, builds LAPACK, and links statically
//! - `netlib-system`: Finds and links existing LAPACK in the system
//! - `intel-mkl-static`: Finds and links existing static Intel MKL in the system, or downloads and
//! links statically if not found
//! - `intel-mkl-system`: Finds and links existing shared Intel MKL in the system
//!
//! If the `*-static` backends give rise to numerical problems, please try installing the linear
//! algebra backends directly (either via your system's package manager or by compiling from source)
//! and then using the corresponding `*-system` backends.
//!
//! ### Interfaces
//! - `qchem`: Enables Q-Chem's HDF5 archive files to be read in and analysed
//! - `python`: Enables the Python bindings for several core functionalities
//!
//! ### Integrals
//! - `integrals`: Enables the computation of $`n`$-centre overlap integrals and $`n`$-centre
//! overlap integral derivatives within QSym²
//!
//! ### Composite
//! - `standard`: Enables the `openblas-static` and `qchem` features
//! - `full`: Enables the `standard` and `integrals` features
//!
//! ### Developmental
//! - `sandbox`: Enables experimental features that are still being actively developed
//!
//! ## Dependencies
//!
//! The compilation of QSym² requires the following:
//! - Common:
//!   * `libssl-dev` (Debian/Ubuntu) or `openssl-devel` (Rocky/Fedora/RHEL)
//!   * `pkg-config` (Debian/Ubuntu) or `pkgconfig` (Rocky/Fedora/RHEL)
//!
//! - Feature-specific:
//!
//! | Feature            | Dependencies                                                                                      | Notes                                                                                                                                                                                        |
//! |--------------------|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
//! | `openblas-static`  | `make`, `gcc`, `gfortran`                                                                         | Builds OpenBLAS and links statically (see [ndarray-linalg documentation](https://github.com/rust-ndarray/ndarray-linalg))                                                                    |
//! | `openblas-system`  | <ul><li>`libopenblas-dev` (Debian/Ubuntu)</li> <li>`openblas-devel` (Rocky/Fedora/RHEL)</li></ul> | Finds and links existing OpenBLAS in the system (see [ndarray-linalg documentation](https://github.com/rust-ndarray/ndarray-linalg))                                                         |
//! | `netlib-static`    | `make`, `gfortran`                                                                                | Builds LAPACK and links statically (see [ndarray-linalg documentation](https://github.com/rust-ndarray/ndarray-linalg))                                                                      |
//! | `netlib-system`    | <ul><li>`liblapack-dev` (Debian/Ubuntu)</li> <li>`lapack-devel` (Rocky/Fedora/RHEL)</li></ul>     | Finds and links existing LAPACK in the system (see  [ndarray-linalg documentation](https://github.com/rust-ndarray/ndarray-linalg))                                                          |
//! | `intel-mkl-static` | <ul><li> `pkg-config` (Debian/Ubuntu)</li> <li>`pkgconfig` (Rocky/Fedora/RHEL)</li></ul>          | Finds and links existing static Intel MKL in the system, or downloads and links statically if not found (see  [ndarray-linalg documentation](https://github.com/rust-ndarray/ndarray-linalg))|
//! | `intel-mkl-system` | <ul><li> `pkg-config` (Debian/Ubuntu)</li> <li>`pkgconfig` (Rocky/Fedora/RHEL)</li></ul>          | Finds and links existing shared Intel MKL in the system (see  [ndarray-linalg documentation](https://github.com/rust-ndarray/ndarray-linalg))                                                |
//! | `qchem`            | `cmake`, `gcc`                                                                                    | Builds the HDF5 C library and links statically                                                                                                                                               |
//! | `integrals`        | <ul><li> `libssl-dev` (Debian/Ubuntu)</li> <li>`openssl-devel` (Rocky/Fedora/RHEL)</li></ul>      | Installs the TLS framework required for [reqwest](https://github.com/seanmonstar/reqwest)                                                                                                    |
//! | `python`           | Python, which is best managed via Anaconda                                                        | Installs the Python bindings for core functionalities of QSym²                                                                                                                               |
//!
//! ## Examples and usage
//!
//! For most items (structs, enums, functions, and traits), their usages are illustrated in test
//! functions. For more explanation, please consult this documentation.
//!
//! For usage of the compiled `qsym2` binary or Python library, please consult the `README.md` file
//! on [GitLab](https://gitlab.com/bangconghuynh/qsym2) and the documentations on
//! [QSym²'s website](https://qsym2.dev).
//!
//! ## License
//!
//! GNU Lesser General Public License v3.0.
//!
//! ## Authors and acknowledgement
//!
//! QSym² has been developed and maintained by
//! Dr [Bang C. Huynh](https://orcid.org/0000-0002-5226-4054) at the University of Nottingham, UK
//! since July 2022 with scientific support from Prof.
//! [Andrew M. Wibowo-Teale](https://orcid.org/0000-0001-9617-1143) and Dr
//! [Meilani Wibowo-Teale](https://orcid.org/0000-0003-2462-3328) and financial support from
//! the ERC grant under the *topDFT* project.
//!
//! The logo for QSym², which is a stylised stellated octahedron, was designed with
//! artistic support from Mr [Thinh Nguyen](https://www.linkedin.com/in/thinh-nguyen-a38b7856/).

macro_rules! count_exprs {
    () => (0);
    ($head:expr) => (1);
    ($head:expr, $($tail:expr),*) => (1 + count_exprs!($($tail),*));
}

macro_rules! replace_expr {
    ($_t:tt $sub:expr) => {
        $sub
    };
}

pub mod analysis;
pub mod angmom;
pub mod auxiliary;
pub mod basis;
pub mod bindings;
pub mod chartab;
pub mod drivers;
pub mod group;
#[cfg(feature = "integrals")]
pub mod integrals;
pub mod interfaces;
pub mod io;
pub mod permutation;
pub mod rotsym;
#[cfg(feature = "sandbox")]
pub mod sandbox;
pub mod symmetry;
pub mod target;