epsproc.util.conversion module

ePSproc conversion functions

28/02/24 Added datasetStack(), mainly for use with multiJob class datastructure. 17/07/20 Added orb3DCoordConv(), for orbital file coord conversions. 12/03/20 Added multiDimXrToPD(), function adapted from lmPlot() code.

TODO: consider implementing CCLIB for unit conversions. See also pint library.

epsproc.util.conversion.conv_BL_BLM(data, to='sph', renorm=True)

Convert BL (Legendre Polynomial) <> BLM (Spherical Harmonic), plus parameter renomalisation.

\[ \begin{align}\begin{aligned}\beta^{Sph}_{L,0} = \sqrt{(2L+1)/4\pi}\beta^{Lg}\\Note: other conventions may be used here, see https://shtools.github.io/SHTOOLS/complex-spherical-harmonics.html#supported-normalizations\\Parameters ---------- data : Xarray Values to convert. Currently assumes an Xarray, with dims .L and .M\\to : str, default = 'sph' - 'sph' to convert BL > BLM - 'lg' to convert BL0 > BL\\renorm : bool, optional, default = True If true, additionally renormalise paramters by L=0 term, such that B0 = 1.\\Notes ----- - Should add type to keep track of betas here. - Should generalise to other input structure & add error checking. - Implement SHTOOLS library....!\end{aligned}\end{align} \]

epsproc.util.conversion.conv_ev_atm(data, to='ev')

Convert eV <> Hartree (atomic units)

Parameters:

• data (int, float, np.array) – Values to convert.

• to (str, default = 'ev') –

  • ‘ev’ to convert H > eV

  • ’H’ to convert eV > H

Return type:

data converted in converted units.

epsproc.util.conversion.conv_ev_nm(data)

Convert E(eV) <> lambda(nm).

epsproc.util.conversion.conv_ev_nm_elec(data)

Convert Eke(eV) > lambda(A) for electrons.

epsproc.util.conversion.datasetStack(data, dataType='XS', keys=None, stackDim='Orb', dimLabel=None, swapDims=False, dropDims=False, sortByStacked=True, **kwargs)

General routine for stacking dict of XR.dataArray data to new array.

For use with multiJob class or general data.data[job][dataType] style data. (Cf. TMOdev code…?)

NOTE: that this format doesn’t work for Ehv coords for plotting directly, may need DataSet format for this case. NOTE: additonal options for Eke,Ehv dims, which are (orb,E) dependent. May have better routines for handling this elsewhere.

See also epsproc.util.misc and epsproc.util.xrIO for complementary restacking XR functions.

Pass **kwargs for matEleSelector to subselect data prior to stacking.

Parameters:

• data (dict) – Dictionary of data to stack. Should contain elements of type data[key][dataType], e.g. as used by multijob class.

• dataType (str, default = 'XS') – Data type to stack.

• keys (list, default = None) – List of keys to use. If None, skip routine return empty items only.

• stackDim (str, default = 'Orb') – Dim for concat to new array. Can be an existing or new dim. Default case assumes data[key] correspond to different orb (channels) jobs.

• dimLabel (str, default = None) – Label for array along stackDim. If None, use data[key][dataType].attrs[‘jobLabel’] or integer if missing. If passed try and use data[key][‘jobNotes’][dimLabel].

• swapDims (bool, default = False) – If True swap Eke > Ehv dims.

• dropDims (bool, default = False) – If True, drop secondary Eke or Ehv dim. This is currently required for stacking to DA for dims which are (orb,E) dependent.

• sortByStaked (bool, default = True) – If True, run da.sortby() along stackDim.

• **kwargs (optional) – Additional args for ep.matESelector. No subselection if not passed.

Returns:

XR dataarray of stacked data. XR dataset of stacked data (note this may be None in some cases, when dims are an issue). dataDict contains data subset in dictionary format.

Return type:

xrDA, xrDS, dataDict

v1 28/02/24 Mainly from quick hacks in https://phockett.github.io/ePSdata/OCS-preliminary/OCS_orbs8-11_AFBLMs_VM-ADMs_140122-JAKE_tidy-replot-200722_v5.html

Should check codebase for other complementary routines!

epsproc.util.conversion.multiDimXrFromDict(daDict)

Convert multiDim Xarray to native dictionary format

epsproc.util.conversion.multiDimXrToDict(da)

Convert multiDim Xarray to native dictionary format

epsproc.util.conversion.multiDimXrToPD(da, colDims=None, rowDims=None, thres=None, squeeze=True, dropna=True, fillna=False, colRound=2, verbose=False)

Convert multidim Xarray to stacked Pandas 2D array, (rowDims, colDims)

Parameters:

• da (Xarray) – Array for conversion.

• colDims (list of dims for columns, default = None) –

• rowDims (specifiy both colDims and) –

• NOTE (if xDim is a MultiIndex, pass as a dictionary mapping, otherwise it may be unstacked during data prep.) –

• ordering (For full control over dim stack) –

• rowDims –

• NOTE –

• (L (E.g. for plotting stacked) –

• M) (['L','M']}) –

• {'LM' (set xDim =) –

• thres (float, optional, default = None) – Threshold values in output (pd table only) TODO: generalise this and use matEleSelector() for input?

• squeeze (bool, optional, default = True) – Drop singleton dimensions.

• dropna (bool, optional, default = True) – Drop all NaN dimensions from output pd data frame (columnwise and rowise).

• fillna (bool, optional, default = False) – Fill any NaN values with 0.0. Useful for plotting/making data contiguous.

• colRound (int, optional, default = True) – Round column values to colRound dp. Only applied for Eke, Ehv, Euler or t dimensions.

Returns:

• daRestackpd (pandas data frame (2D) with sorted data.)

• daRestack (Xarray with restacked data.)

Method

Restack Xarray by specified dims, including basic dims checking, then use da.to_pandas().

12/03/20 Function adapted from lmPlot() code.

Note

This might casue epsproc.lmPlot() to fail for singleton x-dimensions if squeeze = True. TO do: add work-around, see lines 114-122.

epsproc.util.conversion.orb3DCoordConv(fileIn, coordMaxLen=50)

Basic coord parse & conversion for volumetric wavefunction files from ePS.

Parameters:

• fileIn (data from a single file) – List of values from a wavefunction file, as returned by epsproc.readOrb3D(). (Note this currently assumes a single file/set of values.)

• coordMaxLen (int, optional, default=50) – Max coord grid size, assumed to demark native Cart (<coordMaxLen) from Spherical (>coordMaxLen) coords.

Returns:

x,y,z

Return type:

np.arrays of Cartesian coords (x,y,z)

epsproc.util.conversion.renormL0(data)

Renormalise passed data (Xarray) by (L,M) = (0,0) term.

Requires input Xarray to have dims (L,M) or (l,m), should be robust over all other dims.

# 26/02/25 - mod to check dims first then add if required. # TODO: should use checkDims or conformDims here… just quick hack for now