crystod.mol

crystod.mol#

Molecular symmetry, molecular SALCs and MO diagrams (crystod-mol).

The molecular domain of CrystOD, the Python form of the crystod-mol command and the molecular counterpart of the crystalline SALC analysis: the point group of a molecule given as an XYZ file is detected, the symmetry-adapted linear combinations (SALCs) of the atomic orbitals on a set of equivalent sites are projected out per irrep with the same point-group character tables as crystod-group, and molecular-orbital diagrams are drawn as interactive HTML pages, either semi-quantitatively from symmetry and overlap (symmetry-adapted extended Hueckel) or quantitatively from PySCF calculations.

Point group and SALCs (crystod-mol --symmetry, --element/--orbital):

  • load_molecule reads an XYZ file into a centered pymatgen Molecule.

  • get_symmetry returns the Schoenflies symbol and the symmetry operations (pymatgen’s PointGroupAnalyzer).

  • get_permutation_matrices builds the site-permutation matrix of every operation on a set of sites.

  • project_salcs projects the explicit SALCs of one orbital shell out of the permutation x orbital representation, irrep by irrep.

  • format_salc writes one SALC vector as a readable linear combination.

  • SCHOENFLIES_TO_HM maps the Schoenflies symbols of the 32 crystallographic point groups to their Hermann-Mauguin symbols.

MO diagrams (crystod-mol --diagram):

  • MODiagram draws the diagram of a single-center molecule (central atom plus ligands: NH3, CH4, SF6, …) from symmetry and overlap, in the columns ligand AOs, ligand SALCs, MOs and central-atom AOs.

  • EhtFragmentDiagram draws the three-column diagram of a molecule split into two arbitrary fragments by formula (--ao-left/--ao-right), in the same extended-Hueckel AO space.

  • PyscfDiagram makes the fragment diagram quantitative with three PySCF SCF calculations in one AO space (--pyscf; needs the [quantum] extra).

  • AtomicOrbital, build_basis, overlap_matrix, hamiltonian_matrix and EHT_PARAMETERS are the extended-Hueckel building blocks: the single-zeta STO valence basis, its exact two-center overlap matrix and the Wolfsberg-Helmholz Hamiltonian.

Attributes resolve lazily (PEP 562): importing this module is instant, pymatgen is loaded by the first call and PySCF only by PyscfDiagram. Bad input makes the functions raise ValueError (the command-line form of the same code stops with an ERROR: line); the diagram classes raise SystemExit like the command.

class crystod.mol.AtomicOrbital(atom, element, shell, n, l, m, zeta, h_ii)[source]#

Bases: object

One real valence atomic orbital of the extended-Hueckel basis.

build_basis creates one instance per (site, shell, m) from EHT_PARAMETERS; the list of instances indexes the rows and columns of the matrices returned by overlap_matrix and hamiltonian_matrix.

Variables:

  • atom (int) – Site index of the orbital’s atom in the molecule.

  • element (str) – Element symbol of that atom.

  • shell (str) – Shell label, e.g. "1s", "2p", "3d".

  • n (int) – Principal quantum number of the Slater-type orbital.

  • l (int) – Azimuthal quantum number (0 = s, 1 = p, 2 = d, 3 = f).

  • m (int) – Index of the real orbital component within the shell: 0 for s, the position in px, py, pz for p, in dxy, dyz, dz2, dxz, dx2-y2 for d and in fx(x2-3y2), fy(3x2-y2), fz(x2-y2), fxyz, fxz2, fyz2, fz3 for f (the wigner_D_real component order).

  • zeta (float) – Slater exponent in 1/bohr (a single value, or a list of (zeta, coefficient) pairs for a double-zeta d or f shell).

  • h_ii (float) – Diagonal Hamiltonian element (valence-state ionization energy) in eV.

atom: int#
element: str#
h_ii: float#
l: int#
m: int#
n: int#
property orbital_label: str#

Label of the real orbital, e.g. "2s", "2px", "3dz2".

shell: str#
zeta: float#
class crystod.mol.EhtFragmentDiagram(xyz_path, tolerance=0.3, left_spec=None, right_spec=None)[source]#

Bases: object

Extended-Hueckel MO diagram of a molecule split into two fragments.

The engine behind crystod-mol --diagram --ao-left A --ao-right B without --pyscf: the sibling of MODiagram for molecules without a single center, e.g. benzene as H6 and C6 or methanol as H4 and CO. Constructing the object runs the analysis: the point group is detected and the molecule aligned to the standard frame when it belongs to one of the 32 crystallographic groups; the atoms are partitioned by the two formulas; the extended-Hueckel matrices of the whole molecule are built once, and the pre-bonding levels of each fragment are the generalized eigenstates of its own (H, S) sub-block (in extended Hueckel the sub-block is the isolated fragment, so no ghost basis is needed); the molecular MOs are projected onto the fragment MOs through the shared overlap matrix for the correlation lines and compositions. Levels are labeled by the characters of their eigenvectors (a fragment need not be invariant under the full molecular group; unlabeled levels are numbered plainly), numbered with the core shells counted, and given a COOP bonding character.

Parameters:

  • xyz_path (str) – Path of the molecule file in XYZ format.

  • tolerance (float) – Distance tolerance in Angstrom for the symmetry detection (--tolerance).

  • left_spec (str) – Formula of the left fragment (--ao-left), e.g. "H6": element symbols with optional counts.

  • right_spec (str) – Formula of the right fragment (--ao-right), e.g. "C6". Both formulas are required and together must account for every atom of the molecule.

Variables:

  • xyz_path – The molecule file as given.

  • formula – Hill formula of the molecule ("C6H6").

  • schoenflies – Schoenflies symbol of the point group.

  • hm – Its Hermann-Mauguin symbol, or None for a non-crystallographic group.

  • linear – Whether the molecule is linear.

  • character_table – Character table of the point group, or None.

  • operations – Rotation matrices of the group in the standard frame (empty when hm is None).

  • operation_classes – Class label of every entry of operations.

  • symbols – Element symbol of every atom.

  • coordinates – (n_atoms, 3) Cartesian coordinates in Angstrom.

  • left – Site indices of the left fragment.

  • right – Site indices of the right fragment.

  • left_name – Formula of the left fragment ("H6").

  • right_name – Formula of the right fragment ("C6").

  • orbitals – The AO basis of the whole molecule (AtomicOrbital list).

  • S – AO overlap matrix.

  • H – Extended-Hueckel Hamiltonian in eV.

  • rows – AO indices of each column ("left", "mo", "right").

  • electron_counts – Valence electrons of each column.

  • levels – FragmentLevel lists per column, energy ascending. Each level has energy (eV), degeneracy, irrep, label, electrons, vectors ((n_ao, degeneracy) AO-space coefficients) and composition (pairs of a level id and its weight; for the molecular column the projection onto the fragment levels); the molecular levels also carry bond_character and overlap_population, the fragment levels dominant_spec, their dominant (element, shell).

  • homo – Highest occupied molecular level (None if none).

  • lumo – Lowest unoccupied molecular level (None if none).

Raises:

SystemExit – The file is missing, a fragment formula is absent or cannot be parsed, the two formulas do not partition the molecule, or an element has no extended-Hueckel parameters.

Example

>>> from crystod import mol
>>> from crystod.examples import example_path
>>> diagram = mol.EhtFragmentDiagram(
...     example_path("XYZ_NH3.xyz"), left_spec="H3", right_spec="N")
>>> diagram.left_name, diagram.right_name, diagram.electron_counts
('H3', 'N', {'mo': 8, 'left': 3, 'right': 5})
>>> diagram.homo.label, diagram.lumo.label
('3a1', '2e')
>>> diagram.write_html("MolOD_NH3_fragments.html")
print_report()[source]#

Print the text report of the two-fragment diagram to stdout.

Sections: molecule and point group, the two fragments with their atoms and valence-electron counts, the molecular orbitals up to 12 eV above the LUMO (energy, occupation, composition in fragment levels), and the electron filling with HOMO, LUMO and gap.

write_html(output_path)[source]#

Write the interactive three-column HTML diagram.

Columns: left-fragment MOs, molecule MOs, right-fragment MOs, with correlation lines weighted by the projections, electron arrows, HOMO/LUMO marks, an adjustable energy window, per-level details and the orbital sketch viewer.

Parameters:

output_path (str) – Path of the HTML file to write (crystod-mol uses MolOD_{molecule}.html by default).

class crystod.mol.MODiagram(xyz_path, tolerance=0.3, center_element=None)[source]#

Bases: object

Symmetry-adapted extended-Hueckel MO diagram of a single-center molecule.

The engine behind crystod-mol --diagram (without --pyscf and without --ao-left/--ao-right). Constructing the object runs the whole analysis: the point group is detected and the molecule rotated into the standard point-group frame; the central atom and the ligand sites are identified; the ligand orbitals of every shell are symmetry-adapted per irrep (project_salcs); the extended-Hueckel matrices of the full valence basis are built (build_basis, overlap_matrix, hamiltonian_matrix); and the generalized eigenproblem is solved irrep by irrep, first for the ligand cage alone (the SALC levels) and then for the ligand SALCs together with the central-atom orbitals (the molecular orbitals). The electrons are filled in, the MOs are numbered in the photoelectron convention (core shells counted, e.g. 2a1 and 1t2 for CH4) and given a COOP bonding character. print_report writes the text report and write_html the interactive four-column diagram (ligand AOs, ligand SALCs, MOs, central-atom AOs).

Parameters:

  • xyz_path (str) – Path of the molecule file in XYZ format.

  • tolerance (float) – Distance tolerance in Angstrom for the symmetry detection (--tolerance).

  • center_element (str | None) – Element of the central atom (--center); by default the atom closest to the molecular center, which must be unambiguous.

Variables:

  • xyz_path – The molecule file as given.

  • formula – Conventional formula, central atom first ("NH3", "SF6"; the group-16 hydrides as "H2O").

  • schoenflies – Schoenflies symbol of the point group ("C3v").

  • hm – Hermann-Mauguin symbol of the point group ("3m").

  • character_table – Character table of the point group, in the format of crystod.group.get_character_table.

  • operations – Rotation matrices of the group in the standard frame.

  • operation_classes – Class label of every entry of operations.

  • symbols – Element symbol of every atom.

  • coordinates – (n_atoms, 3) Cartesian coordinates in Angstrom, in the standard point-group frame and symmetrized over the group.

  • center – Site index of the central atom.

  • ligand_sites – Site indices of the ligand atoms, per element.

  • orbitals – The valence AO basis as a list of AtomicOrbital.

  • ao_index – Map from (atom, shell, m) to the index in orbitals.

  • S – AO overlap matrix.

  • H – Extended-Hueckel Hamiltonian in eV.

  • n_electrons – Number of valence electrons.

  • fragment_shells – FragmentShell records, one per shell of the central atom and of each ligand element, holding the SALCs of that shell per irrep as AO-space vectors.

  • mo_levels – Molecular-orbital Level objects, energy ascending. Each has energy (eV), degeneracy, irrep, label ("3a1"), electrons, composition (pairs of a level id and its weight, over the SALC and central-AO levels), vectors (AO-space coefficients), bond_character ("bonding", "nonbonding" or "antibonding") and overlap_population.

  • salc_levels – Ligand SALC Level objects (the second column).

  • center_levels – Central-atom AO levels (the fourth column).

  • ligand_ao_levels – Isolated ligand AO levels (the first column).

  • levels – All levels keyed by ("ligand-ao", element, shell), ("center-ao", shell) and ("mo", level_id).

  • irrep_blocks – Per-irrep report data (SALC levels, central shells, SALC to central-AO overlap integrals, MO groups).

  • core_counts – Number of core levels per irrep, counted in the MO numbering.

  • core_summary – Text lines describing those core shells ("N 1s -> a1").

  • homo – Highest occupied Level (None if none is occupied).

  • lumo – Lowest unoccupied Level (None if all are occupied).

Raises:

SystemExit – The file is missing, the point group is not one of the 32 crystallographic groups (linear molecules), no unique central atom can be identified, or an element has no extended-Hueckel parameters.

Example

>>> from crystod import mol
>>> from crystod.examples import example_path
>>> diagram = mol.MODiagram(example_path("XYZ_NH3.xyz"))
>>> diagram.formula, diagram.schoenflies, diagram.n_electrons
('NH3', 'C3v', 8)
>>> [(level.label, level.electrons) for level in diagram.mo_levels]
[('2a1', 2), ('1e', 4), ('3a1', 2), ('2e', 0), ('4a1', 0)]
>>> diagram.homo.label, diagram.lumo.label
('3a1', '2e')
>>> diagram.write_html("MolOD_NH3.html")
print_report()[source]#

Print the text report of crystod-mol --diagram to stdout.

Sections: molecule and point group, fragments, the extended-Hueckel AO parameters, the ligand SALCs per irrep, the ligand SALC to central AO overlap integrals, the molecular orbitals (energy, occupation, composition), the electron filling with HOMO, LUMO and gap, and the method references.

write_html(output_path)[source]#

Write the interactive HTML/SVG diagram.

Four columns (isolated ligand AOs, ligand SALCs, MOs, central-atom AOs) with dashed correlation lines, electron arrows, HOMO/LUMO marks, an adjustable energy window, per-level details on hover and the orbital sketch viewer; the page is self-contained.

Parameters:

output_path (str) – Path of the HTML file to write (crystod-mol uses MolOD_{molecule}.html by default).

class crystod.mol.PyscfDiagram(xyz_path, tolerance=0.3, center_element=None, left_spec=None, right_spec=None, basis='def2-svp', theory='scf', xc='b3lyp', charge=0, spin=None)[source]#

Bases: object

Quantitative MO diagram from three PySCF SCF calculations in one AO space.

The engine behind crystod-mol --diagram --pyscf. Constructing the object runs the analysis: the point group is detected and the molecule aligned to the standard frame (a linear molecule is put along z); the atoms are split into a left and a right fragment, by default the ligand cage and the central atom, or by the two formulas; three SCF calculations are run at the same geometry in the same basis, for the molecule and for each fragment with the removed atoms kept as ghost atoms (counterpoise-consistent), the fragments with fractional occupation of degenerate frontier shells so that they keep the point-group symmetry; the molecular MOs are projected exactly onto the fragment MOs for the correlation lines and compositions; the levels are labeled by the characters of the MOs under the character-table operations (the same labels as MODiagram and crystod-group; sigma/pi/delta from PySCF’s Dooh/Coov symmetry for linear molecules) and given a COOP bonding character. Fragment levels that live mostly on the ghost basis (BSSE artifacts) are dropped from the diagram.

PySCF is an optional dependency (pip install "CrystOD[quantum]"); constructing the object without it raises ImportError.

Parameters:

  • xyz_path (str) – Path of the molecule file in XYZ format.

  • tolerance (float) – Distance tolerance in Angstrom for the symmetry detection (--tolerance).

  • center_element (str) – Element of the central atom (--center) for the default ligand-cage and central-atom split; by default the atom closest to the molecular center.

  • left_spec (str) – Formula of the left fragment (--ao-left), e.g. "H4"; given together with right_spec it replaces the default split.

  • right_spec (str) – Formula of the right fragment (--ao-right), e.g. "CO".

  • basis (str) – PySCF basis set (--basis), e.g. "def2-svp" or "sto-3g".

  • theory (str) – "scf" for Hartree-Fock (RHF/ROHF) or "dft" for Kohn-Sham DFT (RKS/ROKS) (--theory).

  • xc (str) – Exchange-correlation functional for theory="dft" (--xc).

  • charge (int) – Total charge of the molecule (--charge).

  • spin (int) – Molecular spin 2S (--spin); by default 0 or 1 by electron parity (spin=2 for triplet O2).

Variables:

  • xyz_path – The molecule file as given.

  • formula – Conventional formula (central atom first, or the Hill formula for an explicit split).

  • schoenflies – Schoenflies symbol of the point group.

  • hm – Its Hermann-Mauguin symbol, or None for a non-crystallographic group.

  • linear – Whether the molecule is linear.

  • character_table – Character table of the point group, or None.

  • operations – Rotation matrices of the group in the standard frame (empty when hm is None).

  • operation_classes – Class label of every entry of operations.

  • symbols – Element symbol of every atom.

  • coordinates – (n_atoms, 3) Cartesian coordinates in Angstrom.

  • center – Site index of the central atom, or None for an explicit split.

  • left – Site indices of the left fragment.

  • right – Site indices of the right fragment.

  • left_name – Formula of the left fragment ("H3").

  • right_name – Formula of the right fragment ("N").

  • basis – The PySCF basis set; theory, xc, charge and spin hold the other settings as used.

  • n_electrons – Number of electrons of the molecule (all electrons).

  • calculations – One dict per column ("left", "mo", "right") with the PySCF mol and mean-field object mf, spin, charge, converged, the total energy in Hartree, mo_energy in eV, mo_occ, mo_coeff and the real_sites (the non-ghost atoms).

  • levels – PyscfLevel lists per column, energy ascending. Each level has energy (eV), degeneracy, irrep, label, electrons, orbital_indices (columns of mo_coeff), composition (pairs of a level id and its weight; for the molecular column the projection onto the fragment levels) and real_fraction (Mulliken population on the real atoms); the molecular levels also carry bond_character and overlap_population, the fragment levels dominant_spec.

  • homo – Highest occupied molecular level (None if none).

  • lumo – Lowest unoccupied molecular level (None if none).

Raises:

  • ImportError – PySCF is not installed.

  • SystemExit – The file is missing, the fragment formulas cannot be parsed or do not partition the molecule, no unique central atom can be identified, or spin is inconsistent with the electron count.

Example

Ammonia in a minimal basis (three Hartree-Fock calculations, a few seconds):

from crystod import mol
from crystod.examples import example_path

diagram = mol.PyscfDiagram(example_path("XYZ_NH3.xyz"), basis="sto-3g")
diagram.print_report()
print(diagram.left_name, diagram.right_name)   # H3 N
print(diagram.homo.label, diagram.lumo.label)  # 3a1 4a1
diagram.write_html("MolOD_NH3_pyscf.html")
print_report()[source]#

Print the text report of crystod-mol --diagram --pyscf to stdout.

Sections: molecule and point group, the two fragments with their spins, the three SCF calculations (method, basis, total energies, convergence) and the counterpoise-consistent interaction energy, the molecular orbitals up to 12 eV above the LUMO (energy, occupation, composition in fragment levels), the electron filling with HOMO, LUMO and gap, and the PySCF references.

write_html(output_path)[source]#

Write the interactive three-column HTML diagram.

Columns: left-fragment MOs, molecule MOs, right-fragment MOs, with correlation lines weighted by the projections, electron arrows, HOMO/LUMO marks, an adjustable energy window (core levels reachable by panning), per-level details and the orbital sketch viewer.

Parameters:

output_path (str) – Path of the HTML file to write (crystod-mol uses MolOD_{molecule}_pyscf.html by default).

crystod.mol.build_basis(symbols, site_indices)[source]#

Assemble the extended-Hueckel valence AO basis of a set of atoms.

For every selected site, every valence shell of its element listed in EHT_PARAMETERS contributes its 2 l + 1 real orbitals, in the order of the table and of the wigner_D_real components. This is the AO space of MODiagram and EhtFragmentDiagram (all atoms of the molecule).

Parameters:

  • symbols (list[str]) – Element symbol of every atom of the molecule.

  • site_indices (list[int]) – Indices into symbols of the atoms to include (a fragment, or range(len(symbols)) for the whole molecule).

Returns:

List of AtomicOrbital objects; its order is the AO index used by overlap_matrix and hamiltonian_matrix.

Raises:

SystemExit – An element has no extended-Hueckel parameters; the message lists the supported elements (ValueError when called through crystod.mol).

Return type:

list[AtomicOrbital]

Example

>>> from crystod import mol
>>> [ao.orbital_label for ao in mol.build_basis(["N", "H"], [0, 1])]
['2s', '2px', '2py', '2pz', '1s']
crystod.mol.format_salc(vector, term_labels)[source]#

Write one SALC vector as a readable linear combination of its terms.

Produces the A1: [s(H1) + s(H2) + s(H3)] lines of the crystod-mol report. The vector is scaled to the smallest integer coefficients that reproduce it (to the precision of a typical XYZ geometry); when no integer form exists the coefficients are printed with three decimals. Zero components are dropped and the first nonzero coefficient is made positive.

Parameters:

  • vector – SALC coefficients, one per term (any sequence of numbers).

  • term_labels – Names of the terms, parallel to vector, e.g. ["s(H1)", "s(H2)", "s(H3)"] or ["px(N1)", "py(N1)", "pz(N1)"].

Returns:

The combination as one string, e.g. "2 s(H1) - s(H2) - s(H3)".

Return type:

str

Example

>>> from crystod import mol
>>> mol.format_salc([1, 1, 1], ["s(H1)", "s(H2)", "s(H3)"])
's(H1) + s(H2) + s(H3)'
>>> mol.format_salc([2, -1, -1], ["s(H1)", "s(H2)", "s(H3)"])
'2 s(H1) - s(H2) - s(H3)'
>>> mol.format_salc([0.7071, -0.7071, 0.0], ["s(H1)", "s(H2)", "s(H3)"])
's(H1) - s(H2)'
crystod.mol.get_permutation_matrices(operations, coordinates, tolerance)[source]#

Site-permutation matrix of every symmetry operation on a set of sites.

Builds the permutation representation of the selected sites (the --element sites of crystod-mol; --show-matrix prints it): P[i, j] = 1 when the operation maps site j onto site i. The traces are the characters chi(perm) of the reducible representation, and the matrices are the site factor of the permutation x orbital representation reduced by project_salcs.

Parameters:

  • operations – Rotation matrices (3x3 arrays) acting on the Cartesian coordinates, e.g. from get_symmetry.

  • coordinates – (n_sites, 3) Cartesian coordinates of the sites, in the same frame as operations.

  • tolerance (float) – Largest distance in Angstrom between a mapped site and the site it is identified with.

Returns:

List of (n_sites, n_sites) permutation matrices, one per operation and in the same order.

Raises:

SystemExit – An operation does not map the sites onto themselves within tolerance, or the mapping is not one-to-one (ValueError when called through crystod.mol).

Example

>>> import numpy as np
>>> from crystod import mol
>>> c4 = np.array([[0.0, -1.0, 0.0], [1.0, 0.0, 0.0], [0.0, 0.0, 1.0]])
>>> square = np.array([[1, 0, 0], [0, 1, 0], [-1, 0, 0], [0, -1, 0]], float)
>>> mol.get_permutation_matrices([c4], square, 0.1)[0].astype(int)
array([[0, 0, 0, 1],
       [1, 0, 0, 0],
       [0, 1, 0, 0],
       [0, 0, 1, 0]])
crystod.mol.get_symmetry(molecule, tolerance)[source]#

Detect the point group of a molecule and collect its symmetry operations.

The crystod-mol --symmetry analysis: pymatgen’s PointGroupAnalyzer finds the point group (the molecular analogue of phonopy --symmetry for crystals), and the rotation matrices of the operations it reports are deduplicated so that every group element appears once. The matrices act on Cartesian coordinates in the frame of molecule, not yet in the standard orientation of the character tables.

Parameters:

  • molecule – pymatgen Molecule, e.g. from load_molecule.

  • tolerance (float) – Distance tolerance in Angstrom for the symmetry detection (--tolerance; 0.3 is pymatgen’s default).

Returns:

Tuple (schoenflies, operations) of the Schoenflies symbol as a string ("C3v", "Td", "D*h" for a linear molecule, …) and the list of unique 3x3 rotation matrices (numpy.ndarray).

Example

>>> from crystod import mol
>>> from crystod.examples import example_path
>>> molecule = mol.load_molecule(example_path("XYZ_NH3.xyz"))
>>> schoenflies, operations = mol.get_symmetry(molecule, 0.3)
>>> schoenflies, len(operations), mol.SCHOENFLIES_TO_HM[schoenflies]
('C3v', 6, '3m')
crystod.mol.hamiltonian_matrix(orbitals, S)[source]#

Extended-Hueckel Hamiltonian from the overlap matrix.

The Wolfsberg-Helmholz prescription: the diagonal H_ii is the valence-state ionization energy of the orbital and the off-diagonal H_ij = K S_ij (H_ii + H_jj) / 2 with K = 1.75 (WOLFSBERG_HELMHOLZ_K), so a large overlap integral produces a large bonding/antibonding splitting. H and S define the generalized eigenproblem H C = S C E solved by the MO diagrams.

Parameters:

  • orbitals (list[AtomicOrbital]) – AO basis from build_basis (supplies H_ii).

  • S (ndarray) – Overlap matrix of the same basis from overlap_matrix.

Returns:

Symmetric (n_ao, n_ao) array in eV.

Return type:

ndarray

Example

>>> import numpy as np
>>> from crystod import mol
>>> orbitals = mol.build_basis(["H", "H"], [0, 1])
>>> S = mol.overlap_matrix(orbitals, np.array([[0, 0, 0], [0, 0, 0.74]]))
>>> H = mol.hamiltonian_matrix(orbitals, S)
>>> print(f"{H[0, 0]:.1f} {H[0, 1]:.3f}")
-13.6 -15.146
crystod.mol.load_molecule(path)[source]#

Read a molecule from an XYZ file and center it at its center of mass.

First step of every crystod-mol run (the --xyz FILE argument). The molecule is returned as a pymatgen Molecule translated so that its center of mass is at the origin, the frame in which the point-group detection and the SALC projection work.

Parameters:

path (str) – Path of the molecule file in XYZ format (a string or any path-like object).

Returns:

pymatgen Molecule centered at its center of mass.

Raises:

SystemExit – The file does not exist, or pymatgen is not installed (ValueError when called through crystod.mol).

Example

>>> from crystod import mol
>>> from crystod.examples import example_path
>>> molecule = mol.load_molecule(example_path("XYZ_NH3.xyz"))
>>> molecule.composition.reduced_formula, len(molecule)
('H3N', 4)
crystod.mol.overlap_matrix(orbitals, coordinates)[source]#

AO overlap matrix S of an extended-Hueckel basis.

Every two-center overlap between Slater-type orbitals (single-zeta, or the contracted double-zeta d and f shells) is evaluated exactly by numerical quadrature in prolate-spheroidal coordinates for the aligned sigma/pi/delta/phi channels and assembled for the actual bond direction by Slater-Koster rotation (wigner_D_real), so ligand-ligand overlaps are never neglected. Orbitals on the same atom are orthonormal.

Parameters:

  • orbitals (list[AtomicOrbital]) – AO basis from build_basis.

  • coordinates (ndarray) – (n_atoms, 3) Cartesian coordinates in Angstrom, indexed by AtomicOrbital.atom.

Returns:

Symmetric (n_ao, n_ao) array with unit diagonal.

Return type:

ndarray

Example

>>> import numpy as np
>>> from crystod import mol
>>> orbitals = mol.build_basis(["H", "H"], [0, 1])
>>> S = mol.overlap_matrix(orbitals, np.array([[0, 0, 0], [0, 0, 0.74]]))
>>> print(f"{S[0, 1]:.4f}")
0.6364
crystod.mol.project_salcs(operations, operation_classes, permutations, azimuthal, character_table)[source]#

Project the explicit SALCs of one orbital shell out of the site basis.

The core of the crystod-mol --element/--orbital analysis (and of the ligand SALCs of MODiagram). The representation Gamma(g) = P(g) (x) D(g) of the site permutations times the real orbital Wigner-D matrices of angular momentum l is reduced with the projection operator of every irrep of the character table, (d/h) sum_g chi(g) Gamma(g) with real characters chi; the eigenvectors of eigenvalue one of each projector are returned in a canonical orthonormal form (reduced row echelon form followed by Gram-Schmidt), so the coefficients are the small integers of the textbooks whenever such a form exists.

The operations must be given in the frame of the character table (the standard point-group orientation) so that operation_classes can name the class of every one of them; crystod-mol matches the detected operations onto the table and rotates the molecule (--align) or the operations before calling this function.

Parameters:

  • operations – Rotation matrices (3x3 arrays), one per group element.

  • operation_classes – Class label of every operation ("E", "C3", "sgv", …), keys of the character table, parallel to operations.

  • permutations – Site-permutation matrices from get_permutation_matrices, parallel to operations.

  • azimuthal – Azimuthal quantum number l of the orbital shell (0 = s, 1 = p, 2 = d, 3 = f).

  • character_table – Point-group character table as returned by crystod.group.get_character_table (Hermann-Mauguin key).

Returns:

Dict mapping each irrep label ("A1", "E", "T2", …) to the list of its SALC vectors; an irrep that does not occur is absent. Each vector has n_sites * (2 l + 1) components in site-major order (all orbital components of site 1, then of site 2, …), the orbital components ordered px, py, pz for p, dxy, dyz, dz2, dxz, dx2-y2 for d and fx(x2-3y2), fy(3x2-y2), fz(x2-y2), fxyz, fxz2, fyz2, fz3 for f.

Example

Four s orbitals on a square (D4h, table key 4/mmm); the table operations of the tetragonal, orthorhombic, monoclinic and cubic groups are already Cartesian:

import numpy as np
from crystod import group, mol

table = group.get_character_table("4/mmm")
operations, classes = [], []
for name in table["rotation_list"]:
    for matrix in table["mapping_table"][name]:
        operations.append(np.asarray(matrix, dtype=float))
        classes.append(name)
square = np.array([[1, 0, 0], [0, 1, 0], [-1, 0, 0], [0, -1, 0]], float)
permutations = mol.get_permutation_matrices(operations, square, 0.1)
salcs = mol.project_salcs(operations, classes, permutations, 0, table)
labels = [f"s(H{i + 1})" for i in range(4)]
for irrep, vectors in salcs.items():
    print(irrep, [mol.format_salc(v, labels) for v in vectors])
# A1g ['s(H1) + s(H2) + s(H3) + s(H4)']
# B1g ['s(H1) - s(H2) + s(H3) - s(H4)']
# Eu ['s(H1) - s(H3)', 's(H2) - s(H4)']
crystod.mol.SCHOENFLIES_TO_HM#

Schoenflies -> Hermann-Mauguin symbol for the 32 crystallographic point groups ("C3v" -> "3m", "Td" -> "-43m"; "S6" and "C3i" both give "-3"). The Hermann-Mauguin symbol is the key of the point-group character tables shared with crystod-group. A Schoenflies symbol that is not a key (D*h of a linear molecule, C5v, Ih, …) has no SALC or MO-diagram support.

crystod.mol.EHT_PARAMETERS#

Standard extended-Hueckel valence parameters (Hoffmann and successors): element -> list of (shell, n, l, zeta, H_ii) tuples, one per valence shell, with the shell label ("2s", "3d", …), the principal and azimuthal quantum numbers, the Slater exponent zeta in 1/bohr (a single value, or a list of (zeta, coefficient) pairs for the double-zeta d and f shells) and the diagonal energy H_ii (valence-state ionization energy) in eV. The keys are the elements build_basis accepts.