pemtk.sym.symHarm module

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.

TODO

  • Data to dicts? Currently have multiple self.coeffXX attribs.

  • Interface/convert to matrix elements for ePSproc use.

class pemtk.sym.symHarm.symHarm(PG='Cs', lmax=4, llist=None, dims=['C', 'h', 'mu', 'l', 'm'])[source]

Bases: object

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

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()
allowedProductsTable()

Compute allowed continuum X dipole terms.

assignMissingSym(dim, values, dataType='matE', multiInd='Sym')

Replace values in dim, for levels of a (Symmetry style) MultiIndex.

Use this to change symmetry labels, e.g. to replace missing symmetries assigned as ‘U’.

Parameters:

  • dim (str) – Dimension to replace, from matE dataType. Can be [‘Cont’,’Targ’,’Total’]

  • values (str, list or array) – If string, all values are replace by this. If list or array must match size of existing coords.

  • dataType (str, optional, default = 'matE') – DataType to use, from self.coeffs[dataType] Must correspond to Xarray variable with multiInd present.

  • multiInd (str, optional, default = 'Sym') – MultiIndex containing levels to replace.

assignMissingSymProd(dim='Total', dataType='matE', multiIndName='Sym')

Assign missing symmetry label as direct product of other existing labels.

For a given dimension, assign values from other dims of the same multiindex set.

Parameters:

  • dim (str, default = 'Total') – Dimension to replace, from matE dataType. For usual matrix elements definition this can be [‘Cont’,’Targ’,’Total’]

  • dataType (str, optional, default = 'matE') – DataType to use, from self.coeffs[dataType] Must correspond to Xarray variable with multiInd present.

  • multiIndName (str, optional, default = 'Sym') – MultiIndex containing levels to replace.

Notes

Default case uses dim = ‘Total’, dataType = ‘matE’, multiIndName = ‘Sym’. Sym contains dims ‘Sym’: [‘Cont’, ‘Targ’, ‘Total’] (See ep.dataTypesList())

assignSymMuTerms(keyDim='Cont', dataType='matE', dimMap=None, dataTypeOut='symAllowed')

Assign matrix elements from dipole-allowed symmetries, and associated mu values.

20/04/23 v2 - use self.continuum instead of basic direct product for assignments 18/04/23 v1

calcSymHarmonics()[source]

Compute symmetrized harmonic coeffs for point group up to lmax.

dipoleTerms(reCartMap={-1: 'y', 0: 'z', 1: 'x'}, dimMap={'C': 'Cont', 'mu': 'it'})

Compute dipole terms from symHarm object.

directProduct(terms)[source]

Compute direct products for a list of terms (symmetries/species/irreps).

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.

directProductDipole(terms)[source]

Compute direct products for a list of terms (symmetries/species/irreps), and include dipole terms.

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.

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

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.).

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.

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

setCharTablePD()[source]

Generate character table & convert to Pandas DataFrame.

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

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&amp;ctx_ver=Z39.88-2004&amp;rfr_id=info%3Asid%2Fzotero.org%3A2&amp;rft_id=info%3Adoi%2F10.1063%2F1.2338040&amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&amp;rft.genre=article&amp;rft.atitle=Simple%20method%20to%20obtain%20symmetry%20harmonics%20of%20point%20groups&amp;rft.jtitle=The%20Journal%20of%20Chemical%20Physics&amp;rft.stitle=J.%20Chem.%20Phys.&amp;rft.volume=125&amp;rft.issue=9&amp;rft.aufirst=D.%20L.&amp;rft.aulast=Boiko&amp;rft.au=D.%20L.%20Boiko&amp;rft.au=P.%20F%C3%A9ron&amp;rft.au=P.%20Besnard&amp;rft.date=2006-09-07&amp;rft.pages=094104&amp;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&amp;ctx_ver=Z39.88-2004&amp;rfr_id=info%3Asid%2Fzotero.org%3A2&amp;rft_id=info%3Adoi%2F10.1088%2F0022-3700%2F20%2F14%2F013&amp;rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&amp;rft.genre=article&amp;rft.atitle=Photoelectron%20spectroscopic%20studies%20of%20polyatomic%20molecules.%20I.%20Theory&amp;rft.jtitle=Journal%20of%20Physics%20B%3A%20Atomic%20and%20Molecular%20Physics&amp;rft.volume=20&amp;rft.issue=14&amp;rft.aufirst=N&amp;rft.aulast=Chandra&amp;rft.au=N%20Chandra&amp;rft.date=1987-07-28&amp;rft.pages=3405-3415&amp;rft.spage=3405&amp;rft.epage=3415&amp;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.

set_basis(element, l, m, n, name)[source]

Set basis function for a given (element, n, l, m,).

set_lm_basis()[source]

Set basis functions for each (element, l, m).

toePSman(scatSym=None, contSym=None)[source]

Wrap toePSman method.

toePSproc(dimMap={'C': 'Cont', 'h': 'it', 'mu': 'muX'}, dataType='BLM')[source]

Wrap toePSproc method.