Basic usage¶

There are two main ways of running QSym²:

• via the command-line interface provided by the binary qsym2, or
• via the exposed Python bindings provided by the Python library qsym2.

Command-line interface¶

Scope¶

This method is currently able to perform symmetry analysis of:

• Slater determinants,
• Hartree–Fock or Kohn–Sham molecular orbitals, and
• vibrational coordinates

that have been exported by Q-Chem 6 to a HDF5 file named qarchive.h5 saved in the job's scratch directory,

or

• Slater determinants, and
• Hartree–Fock or Kohn–Sham molecular orbitals

that have been stored in binary files, together with other basis-set-related data.

Instructions¶

The command-line interface supports several subcommands and options:

qsym2 -h

A program for Quantum Symbolic Symmetry

Usage: qsym2 <COMMAND>

Commands:
  template
          Generates a template YAML configuration file and exits
  run
          Runs an analysis calculation and exits
  help
          Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help
  -V, --version
          Print version

The subcommand template, runnable as

qsym2 template

The subcommand run, runnable as

qsym2 run -c path/to/config -o output_name

Examples of symmetry analysis performed by QSym² for several Q-Chem calculations can be found in the User guide.

Python interface¶

Scope¶

This method is currently able to perform symmetry representation and composition analysis of:

• Slater determinants,
• Hartree–Fock or Kohn–Sham molecular orbitals,
• multi-determinantal wavefunctions obtained via non-orthogonal configuration interaction,
• real-space functions defined on a grid (sandbox feature required),
• vibrational coordinates, and
• one-electron densities

that can be computed directly in Python or read into Python from calculation files of quantum-chemistry packages, such as by the use of cclib. The main driver functions of QSym² are all exposed to Python, which means that they can be used and integrated into existing workflows flexibly.

This method is also able to perform symmetry projection for:

• Slater determinants, giving multi-determinantal wavefunctions, and
• one-electron densities, giving other one-electron densities.

Instructions¶

The documentation for the Python API is available here, or by executing the following Python commands inside the qsym2-python conda environment (see Python-library compilation), either interactively or in a Python script:

import qsym2
help(qsym2)

An example Python script that performs symmetry analysis for self-consistent-field calculations from ORCA output files (parsed by cclib) can be found at utils/qsym2-orca.py. This script requires the Python packages mendeleev, cclib, and numpy to run.

Another example Python script that performs symmetry analysis for self-consistent-field calculations from ORCA json files (generated by orca_2json) can be found at utils/qsym2-orca-json.py.

Many other examples where the Python bindings of QSym² are used extensively for the analysis of unitary and magnetic symmetry in the presence of external fields can be found in QUEST and its complementary GUI, QuestView.