pemtk.sym.symHarm
Class for determining and handling symmetrized harmonics.
23/03/22 v2
Switched to nested dicts for coeffs, now all in self.coeffs[dtype].
24/02/22 v1 in development.
For early dev work see http://localhost:8888/lab/workspaces/symm/tree/python/chem/tools/symmetrized_harmonics_libmsym_tests_160122.ipynb
For class dev see http://localhost:8888/lab/workspaces/symm/tree/python/chem/tools/symmetrized_harmonics_PEMtk-dev_240222.ipynb
TODO
Data to dicts? Currently have multiple self.coeffXX attribs.
Interface/convert to matrix elements for ePSproc use.
Module Contents
Classes
Class to set and manipulate symmetrized harmonics. |
Attributes
- class pemtk.sym.symHarm.symHarm(PG='Cs', lmax=4, llist=None, dims=['C', 'h', 'mu', 'l', 'm'])[source]
Class to set and manipulate symmetrized harmonics.
Main symmetry routine uses [libmsym](https://github.com/mcodev31/libmsym), code adapted from https://github.com/mcodev31/libmsym/issues/21
Background
Symmetrized (or generalised) harmonics, which essentially provide correctly symmetrized functions for a given irreducible representation, $Gamma$, be defined by linear combinations of spherical harmonics cite{Altmann1963a,Altmann1965,Chandra1987}:
begin{equation} X_{hl}^{Gammamu*}(theta,phi)=sum_{lambda}b_{hllambda}^{Gammamu}Y_{l,lambda}(theta,phi)label{eq:symm-harmonics} end{equation}
where:
$Gamma$ is an irreducible representation,
($l$, $lambda$) define the usual spherical harmonic indicies (rank, order)
$b_{hllambda}^{Gammamu}$ are symmetrization coefficients,
index $mu$ allows for indexing of degenerate components,
$h$ indexe cases where multiple components are required with all other quantum numbers identical.
The exact form of these coefficients will depend on the point-group of the system, see, e.g. cite{Chandra1987,Reid1994}.
Method
- Point-groups, character table generation and symmetrization (computing $b_{hllambda}^{Gammamu}$ parameters) is handled by [libmsym](https://github.com/mcodev31/libmsym) (based on https://github.com/mcodev31/libmsym/issues/21).
Supported point groups: Ci, Cs, Cnv, Dn, Dnh, Dnd, Td, O, Oh, I and Ih
Routines have been tested with libmsym v0.2.2, March 2022 (last commit https://github.com/mcodev31/libmsym/commit/c99470376270db4ec4c925b952fa722e011377d6).
- Spherical harmonic expansions and conversions (real, imaginary, normalization etc.) and basic ploting (2D maps) are handled by [pySHtools](https://shtools.oca.eu).
Routines have been tested with v4.5 and 4.9 (current March 2022).
TODO: Interface to PEMtk/ePSproc for other plotters and handling routines.
TODO: some hardcoded labelling to fix, also incorrect in places (“character” instead of “irrep”)
Examples
>>> # Compute params for Td, lmax=4 >>> xlm = symHarm('Td',4)
>>> # Print charater table >>> xlm.printCharacterTable()
>>> # Display table of params >>> xlm.displayXlm()
>>> # Plot functions >>> xlm.plotXlm()
- directProduct(terms)[source]
Compute direct products for a list of terms (symmetries/species/irreps).
- directProductDipole(terms)[source]
Compute direct products for a list of terms (symmetries/species/irreps), and include dipole terms.
- directProductContinuum(terms, disp=True)[source]
Compute direct products for a list of terms (symmetries/species/irreps), and include dipole terms.
Similar to directProductDipole, but additionally loops over all irreps to determine valid photoionization combinations, i.e. allowed continuum symmetries for the given cases.
- scatSym(symIon, pdInput='allowed', disp=True)[source]
Add scattering symmetry column to self.continuum[‘allowed’][‘PD’].
scatSym = continuum x ion (per ePS definition)
19/02/24 v1
- toePSproc(dimMap={'C': 'Cont', 'h': 'it', 'mu': 'muX'}, dataType='BLM')[source]
Wrap toePSproc method.
- getIrreps()[source]
Get irrep labels from libmsym repr.
Quick hack to grab labels from self.ctx.character_table.symmetry_species objects, should be a better way.
For source, see https://github.com/mcodev31/libmsym/blob/c99470376270db4ec4c925b952fa722e011377d6/bindings/python/libmsym/libmsym.py#L65
- getSymOps()[source]
Get symmetry operation labels from libmsym repr.
Quick hack to grab labels from self.ctx.character_table.symmetry_operations objects, should be a better way.
For source, see https://github.com/mcodev31/libmsym/blob/c99470376270db4ec4c925b952fa722e011377d6/bindings/python/libmsym/libmsym.py#L65
- setCoeffsPD(key='libmsym', dtype='real')[source]
Convert raw list output to Pandas DataFrame.
- Parameters:
key (str, optional, default = 'libmsym') – Key for self.coeffs[key]
dtype (str, optional, default = 'real') – Key for self.coeffs[key][dtype]
- setCoeffsSH(absM=True)[source]
Convert symmertrized harmonics to SHtools object, and convert type to complex.
- Parameters:
absM (bool, optional, default = True) – Use absM values from input coeff labels? May need to force abs(M) for libmsym results? Or double up +/-M terms?
Notes
- Are sign convensions consistent?
Looks like +m in libmsym output == symmetric case (same sign for +/-m).
And -m is antisym case.
Now fixed above (hopefully) by setting -m term as mSign*clmC.coeffs[1,l,m]]
Could also be Condon-Shortley phase, have INCLUDED it here (see https://shtools.oca.eu/shtools/public/complex-spherical-harmonics.html#condon-shortley-phase-factor)
Current version seems to match Chandra 1987 & Boiko et. al. 2006 for some tested Td cases, more testing required.
Sources:
<div class=”csl-bib-body” style=”line-height: 1.35; “> <div class=”csl-entry”>Boiko, D.L., Féron, P. and Besnard, P. (2006) ‘Simple method to obtain symmetry harmonics of point groups’, <i>The Journal of Chemical Physics</i>, 125(9), p. 094104. doi:<a href=”https://doi.org/10.1063/1.2338040”>10.1063/1.2338040</a>.</div> <span class=”Z3988” title=”url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=info%3Adoi%2F10.1063%2F1.2338040&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft.genre=article&rft.atitle=Simple%20method%20to%20obtain%20symmetry%20harmonics%20of%20point%20groups&rft.jtitle=The%20Journal%20of%20Chemical%20Physics&rft.stitle=J.%20Chem.%20Phys.&rft.volume=125&rft.issue=9&rft.aufirst=D.%20L.&rft.aulast=Boiko&rft.au=D.%20L.%20Boiko&rft.au=P.%20F%C3%A9ron&rft.au=P.%20Besnard&rft.date=2006-09-07&rft.pages=094104&rft.issn=0021-9606”></span>
</div>
<div class=”csl-bib-body” style=”line-height: 1.35; “> <div class=”csl-entry”>Chandra, N. (1987) ‘Photoelectron spectroscopic studies of polyatomic molecules. I. Theory’, <i>Journal of Physics B: Atomic and Molecular Physics</i>, 20(14), pp. 3405–3415. doi:<a href=”https://doi.org/10.1088/0022-3700/20/14/013”>10.1088/0022-3700/20/14/013</a>.</div> <span class=”Z3988” title=”url_ver=Z39.88-2004&ctx_ver=Z39.88-2004&rfr_id=info%3Asid%2Fzotero.org%3A2&rft_id=info%3Adoi%2F10.1088%2F0022-3700%2F20%2F14%2F013&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft.genre=article&rft.atitle=Photoelectron%20spectroscopic%20studies%20of%20polyatomic%20molecules.%20I.%20Theory&rft.jtitle=Journal%20of%20Physics%20B%3A%20Atomic%20and%20Molecular%20Physics&rft.volume=20&rft.issue=14&rft.aufirst=N&rft.aulast=Chandra&rft.au=N%20Chandra&rft.date=1987-07-28&rft.pages=3405-3415&rft.spage=3405&rft.epage=3415&rft.issn=0022-3700”></span>
</div>
- setCoeffsXR(stack=True)[source]
Convert coeffs from PD DataFrame to Xarray Dataset.
- Parameters:
stack (dict, bool, optional, default = True) – If True, try and use default stacking, {‘inds’:self.dims[1:3], ‘LM’:self.dims[3:]}. If False, don’t stack. If dict, try and stack with specified dict mapping.
- printCharacterTable(returnPD=False)[source]
Print character table with species & degen using Pandas
- Parameters:
returnPD (bool, optional, default = False) – Return PD object instead of display() if True.
- Return type:
Empty unless returnPD = True set.
- displayXlm(names='longnames', YlmType='real', setCols='l', dropLevels=[], returnPD=False, sticky=False, symFilter=False, symFilterChannel='Target')[source]
Print table of values from Pandas Dataframe self.coeffs[‘DF’][‘real’], with specified labels (from self.coeffs[‘DF’][‘real’].attrs[‘indexes’]).
- Parameters:
names (str, optional, default = 'longnames') – Labels to use in printed table, from self.coeffs[‘DF’][‘real’].attrs[‘indexes’]
YlmType (str, optional, default = 'real') –
‘real’ show real harmonic coeffs, from self.coeffs[‘DF’][‘real’]
’comp’ show complex harmonic coeffs, from self.coeffs[‘DF’][‘comp’]
setCols (str, optional, default = 'l') – Set which label to use for display. Set via self.coeffsDF.unstack(level=setCols). Note this level must be in the DataFrame index, and there is currently no error checking.
dropLevels (str or list of strings, default = []) – Drop levels specified from displayed table.
returnPD (bool, optional, default = False) – Return PD object instead of display() if True.
sticky (bool, optional, default = False) – Apply “sticky” index styler to displayed table. (If supported by Pandas version.)
symFilter (bool, optional, default = False) – If True, apply filter from symFilterChannel.
symFilterChannel (str, optional, default = None) –
Try and filter output based on allowed symmetries. This requires self.continuum to be set, and to match a column name for filtering. E.g. ‘Target’ will filter the Xlm table from self.continuum[‘allowed’][‘PD’][‘Target’] symmetries.
TODO: allow use of short names here, currently only filters on output names.
- Return type:
Empty unless returnPD = True set.
- plotXlm(pType='real', gridlmax=20, syms=None, **kwargs)[source]
Quick plot of Xlm by symmetry using SHtools grid.plot().
- pTypestr, optional, default = ‘real’
Plot type as key (for self.coeffs[‘SH’][pType]). Default cases are ‘real’ or ‘comp’ types (complex harmonics)
- gridlmaxint or None, optional, default = 20
Used by SHtools clm.expand() routine to define gridding. Use SHtools defaults if set to None (== lmax of distribution)
- symsstr or list, default = None
Symmetry groups self.coeffs[‘SH’][pType][sym] to plot. Defaults to all syms, as defined by self.coeffs[‘SH’][pType].keys()
**kwargs : optional args passed to SHtools grid.plot(**kwargs)
Gridding is defined automatically by clm.expand() routine, pass lmax=int as a proxy to override defaults
TODO: For more control with subselection etc. needs bridging with other plotting tools (BLMplot etc.).