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;