epsproc.geomFunc package¶

Submodules¶

Module contents¶

ePSproc geomFunc

Codes for geometric functions:

Wigner 3j
Wigner D
Spherical harmonics
EPR tensors
BLM tensors

etc.

Status¶

In progress Feb. 2020 for MFBLM development. Will eventually supercede/subsume existing functions in sphCalc.py.

epsproc.geomFunc.EPR(QNs=None, p=None, ep=None, nonzeroFlag=True, form='2d', dlist=['l', 'lp', 'P', 'p', 'R-p', 'R'], phaseConvention='S')[source]¶

Define polarization tensor (LF) for 1-photon case.

Define field terms (from QM book, corrected vs. original S&U version - see beta-general-forms\_rewrite\_290917.lyx):

\[\begin{split}\begin{equation} E_{PR}(\hat{e})=[e\otimes e^{*}]_{R}^{P}=[P]^{\frac{1}{2}}\sum_{p}(-1)^{R}\left(\begin{array}{ccc} 1 & 1 & P\\ p & R-p & -R \end{array}\right)e_{p}e_{R-p}^{*} \end{equation}\end{split}\]

Parameters:

QNs (np.array, optional, default = None) – List of QNs [l, lp, P, m, mp, R] to compute 3j terms for. If not supplied all allowed terms for the one-photon case, l=lp=1, will be set.
p (list or array, optional, default = None) – Specify polarization terms p. If set to None, all allowed values for the one-photon case will be set, p=[-1,0,1]
ep (list or array, optional, default = None) – Relative strengths for the fields ep. If set to None, all terms will be set to unity, ep = 1
nonzeroFlag (bool, optional, default = True) – Drop null terms before returning values if true.
form (string, optional, default = '2d') – For options see ep.w3jTable()
phaseConvention (optional, str, default = 'S') –
Set phase conventions:
- ’S’ : Standard derivation.
- ’R’ : Reduced form geometric tensor derivation.
- ’E’ : ePolyScat, may have additional changes in numerics, e.g. conjugate Wigner D.
See setPhaseConventions() for more details.

Examples

# Generate full EPR list with defaults >>> EPRtable = EPR()

# Return as Xarray >>> EPRtable = EPR(form = ‘xarray’)

Note

Currently not handling ep correctly! Should implement as passed Xarray for correct (p,p’) assignment.

epsproc.geomFunc.MFproj(QNs=None, RX=None, nonzeroFlag=True, form='2d', dlist=['l', 'lp', 'P', 'mu', 'mup', 'Rp', 'R'], phaseConvention='S')[source]¶

Define MF projection term, \(\Lambda_{R',R}(R_{\hat{n}})\):

\[\begin{split}\begin{equation} \Lambda_{R',R}(R_{\hat{n}})=(-1)^{(R')}\left(\begin{array}{ccc} 1 & 1 & P\\ \mu & -\mu' & R' \end{array}\right)D_{-R',-R}^{P}(R_{\hat{n}}) \end{equation}\end{split}\]

Then…

\[\begin{eqnarray} \beta_{L,-M}^{\mu_{i},\mu_{f}} & = & \sum_{P,R',R}{\color{red}E_{P-R}(\hat{e};\mu_{0})}\sum_{l,m,\mu}\sum_{l',m',\mu'}(-1)^{(\mu'-\mu_{0})}{\color{red}\Lambda_{R',R}(R_{\hat{n}};\mu,P,R,R')B_{L,-M}(l,l',m,m')}I_{l,m,\mu}^{p_{i}\mu_{i},p_{f}\mu_{f}}(E)I_{l',m',\mu'}^{p_{i}\mu_{i},p_{f}\mu_{f}*}(E) \end{eqnarray}\]

Parameters:	phaseConvention (optional, str, default = 'S') – Set phase conventions: - ‘S’ : Standard derivation. - ‘R’ : Reduced form geometric tensor derivation. - ‘E’ : ePolyScat, conjugate Wigner D. See `setPhaseConventions()` for more details.

Notes

This is very similar to \(E_{PR}\) term.

Examples

>>> lTerm, lambdaTable, lambdaD, QNs = MFproj(form = 'xarray')

epsproc.geomFunc.Wigner3jQNs(QNs)[source]¶

epsproc.geomFunc.afblmXprod(matEin, QNs=None, AKQS=None, EPRX=None, p=[0], BLMtable=None, lambdaTerm=None, RX=None, eulerAngs=None, thres=0.01, thresDims='Eke', selDims={'Type': 'L', 'it': 1}, sumDims=['mu', 'mup', 'l', 'lp', 'm', 'mp', 'S-Rp'], sumDimsPol=['P', 'R', 'Rp', 'p'], symSum=True, SFflag=False, SFflagRenorm=False, BLMRenorm=1, squeeze=False, phaseConvention='S')[source]¶

Implement \(\beta_{LM}^{AF}\) calculation as product of tensors.

\[\begin{eqnarray} \beta_{L,-M}^{\mu_{i},\mu_{f}} & =(-1)^{M} & \sum_{P,R',R}{[P]^{\frac{1}{2}}}{E_{P-R}(\hat{e};\mu_{0})}\sum_{l,m,\mu}\sum_{l',m',\mu'}(-1)^{(\mu'-\mu_{0})}{\Lambda_{R'}(\mu,P,R')B_{L,-M}(l,l',m,m')}I_{l,m,\mu}^{p_{i}\mu_{i},p_{f}\mu_{f}}(E)I_{l',m',\mu'}^{p_{i}\mu_{i},p_{f}\mu_{f}*}(E)\sum_{K,Q,S}\Delta_{L,M}(K,Q,S)A_{Q,S}^{K}(t) \end{eqnarray}\]

Where each component is defined by fns. in :py:module:`epsproc.geomFunc.geomCalc` module.

10/09/20 Verified (but messy) version, with updated defaults.

01/09/20 Verified (but messy) version, including correct renormalisation routines.

15/06/20 In progress! Using mfblmXprod() as template, with just modified lambda term, and new alignment term, to change.

Dev code:: geometric_method_dev_pt3_AFBLM_090620.ipynb http://localhost:8888/lab/tree/dev/ePSproc/geometric_method_dev_Betas_090320.ipynb D:codeePSprocpython_devePSproc_MFBLM_Numba_dev_tests_120220.PY

TOTAL MESS AT THE MOMENT>>?>>>>?DFdas<>r ty

Parameters:	phaseConvention (optional, str, default = 'S') – Set phase conventions with `epsproc.geomCalc.setPhaseConventions()`. To use preset phase conventions, pass existing dictionary.

Notes

Cross-section outputs now set as:

XSraw = direct AF calculation output.
XSrescaled = XSraw * SF * sqrt(4pi)
XSiso = direct sum over matrix elements

Where XSrescaled == XSiso == ePS GetCro output for isotropic distribution.

epsproc.geomFunc.betaTerm(QNs=None, Lmin=0, Lmax=10, nonzeroFlag=True, form='2d', dlist=['l', 'lp', 'L', 'm', 'mp', 'M'], phaseConvention='S')[source]¶

Define BLM coupling tensor

Define field terms (from QM book, corrected vs. original S&U version - see beta-general-forms\_rewrite\_290917.lyx):

\[\begin{split}\begin{equation} B_{L,M}=(-1)^{m}\left(\frac{(2l+1)(2l'+1)(2L+1)}{4\pi}\right)^{1/2}\left(\begin{array}{ccc} l & l' & L\\ 0 & 0 & 0 \end{array}\right)\left(\begin{array}{ccc} l & l' & L\\ -m & m' & M \end{array}\right) \end{equation}\end{split}\]

Parameters:

QNs (np.array, optional, default = None) – List of QNs [l, lp, L, m, mp, M] to compute 3j terms for. If not supplied all allowed terms for {Lmin, Lmax} will be set. (If supplied, values for Lmin, Lmax and mFlag are not used.)
Lmax (Lmin,) – Integer values for Lmin and Lmax respectively.
mFlag (bool, optional, default = True) – m, mp take all values -l…+l if mFlag=True, or =0 only if mFlag=False
nonzeroFlag (bool, optional, default = True) – Drop null terms before returning values if true.
form (string, optional, default = '2d') – For options see ep.w3jTable()
dlist (list of labels, optional, default ['l','lp','L','m','mp','M']) – Used to label array for Xarray output case.
phaseConvention (optional, str, default = 'S') – Set phase conventions: - ‘S’ : Standard derivation. - ‘R’ : Reduced form geometric tensor derivation. - ‘E’ : ePolyScat, may have additional changes in numerics, e.g. conjugate Wigner D. See setPhaseConventions() for more details.

Examples

>>> Lmax = 2
>>> BLMtable = betaTerm(Lmax = Lmax, form = 'xds')
>>> BLMtable = betaTerm(Lmax = Lmax, form = 'xdaLM')

epsproc.geomFunc.deltaLMKQS(EPRX, AKQS, phaseConvention='S')[source]¶

Calculate aligned-frame “alignment” term:

\[\begin{equation} \sum_{K,Q,S}\Delta_{L,M}(K,Q,S)A_{Q,S}^{K}(t) \end{equation}\]

\[\begin{split}\begin{equation} \Delta_{L,M}(K,Q,S)=(2K+1)^{1/2}(-1)^{K+Q}\left(\begin{array}{ccc} P & K & L\\ R & -Q & -M \end{array}\right)\left(\begin{array}{ccc} P & K & L\\ R' & -S & S-R' \end{array}\right) \end{equation}\end{split}\]

15/06/20 IN PROGRESS

Parameters:

EPRX (Xarray) – Polarization terms in an Xarray, as set by epsproc.geomCalc.EPR()
AKQS (Xarray) – Alignement terms in an Xarray, as set by epsproc.setADMs()

Returns:

AFterm (Xarray) – Full term, including multiplication and sum over (K,Q,S) (note S-Rp term is retained).
DeltaKQS (Xarray) – Alignment term \(\Delta_{L,M}(K,Q,S)\).
To do
—–
- Add optional inputs.
- Add error checks.
See other similar functions for schemes.

epsproc.geomFunc.genKQSterms(Kmin=0, Kmax=2, mFlag=True)[source]¶

epsproc.geomFunc.genKQStermsFromTensors(EPR, AKQS, uniqueFlag=True, phaseConvention='S')[source]¶

Generate all QNs for \(\Delta_{L,M}(K,Q,S)\) from existing tensors (Xarrays) \(E_{P,R}\) and \(A^K_{Q,S}\).

Cf. epsproc.geomFunc.genllpMatE(), code adapted from there.

Parameters:

matE (Xarray) – Xarray containing matrix elements, with QNs (l,m), as created by readMatEle()
uniqueFlag (bool, default = True) – Check for duplicates and remove (can occur with some forms of matrix elements).
mFlag (bool, optional, default = True) – m, mp take all passed values if mFlag=True, or =0 only if mFlag=False
phaseConvention (optional, str, default = 'S') – Set phase conventions with epsproc.geomCalc.setPhaseConventions(). To use preset phase conventions, pass existing dictionary. If matE.attrs[‘phaseCons’] is already set, this will be used instead of passed args.

Returns:

QNs1, QNs2 (two 2D np.arrays) – Values take all allowed combinations [‘P’,’K’,’L’,’R’,’Q’,’M’] and [‘P’,’K’,’L’,’Rp’,’S’,’S-Rp’] from supplied matE. Note phase conventions not applied to QN lists as yet.
To do
—–
- Implement output options (see dev. function w3jTable).

epsproc.geomFunc.genllL(Lmin=0, Lmax=10, mFlag=True)[source]¶

Generate quantum numbers for angular momentum contractions (l, lp, L)

Parameters:	Lmax (Lmin,) – Integer values for Lmin and Lmax respectively. mFlag (bool, optional, default = True) – m, mp take all values -l…+l if mFlag=True, or =0 only if mFlag=False
Returns:	QNs – Values take all allowed combinations [‘l’,’lp’,’L’,’m’,’mp’,’M’] up to l=lp=Lmax, one set per row.
Return type:	2D np.array

Examples

>>> # Calculate up to Lmax = 2
>>> QNs = genllL(Lmax=2)
>>> # Use with w3jTable function to calculate Wigner 3j terms
>>> w3j = w3jTable(QNs = QNs)

Implement output options (see dev. function w3jTable).

epsproc.geomFunc.genllLList(Llist, uniqueFlag=True, mFlag=True)[source]¶

Generate quantum numbers for angular momentum contractions (l, lp, L) from a passed list, (m, mp, M)=0 or all allowed terms.

Parameters:	Llist (list) – Values [l, lp, L] to use for calculations. uniqueFlag (bool, optional, default = True) – Drop duplicate [l,lp,L] sets from list. mFlag (bool, optional, default = True) – m, mp take all values -l…+l if mFlag=True, or =0 only if mFlag=False
Returns:	QNs – Values take all allowed combinations [‘l’,’lp’,’L’,’m’,’mp’,’M’] up to l=lp=Lmax, one set per row.
Return type:	2D np.array

Examples

>>> # Set from an array
>>> QNs = genllLList(np.array([[1,1,2],[1,3,2],[1,1,2]]), mFlag = True)
>>> # Use with w3jTable function to calculate Wigner 3j terms
>>> w3j = w3jTable(QNs = QNs)

Implement output options (see dev. function w3jTable).

epsproc.geomFunc.genllpMatE(matE, uniqueFlag=True, mFlag=True, phaseConvention='S')[source]¶

Generate quantum numbers for angular momentum contractions (l, lp, L, m, mp, M) from sets of matrix elements.

Parameters:	matE (Xarray) – Xarray containing matrix elements, with QNs (l,m), as created by `readMatEle()` uniqueFlag (bool, default = True) – Check for duplicates and remove (can occur with some forms of matrix elements). mFlag (bool, optional, default = True) – m, mp take all passed values if mFlag=True, or =0 only if mFlag=False phaseConvention (optional, str, default = 'S') – Set phase conventions with `epsproc.geomCalc.setPhaseConventions()`. To use preset phase conventions, pass existing dictionary. If matE.attrs[‘phaseCons’] is already set, this will be used instead of passed args.
Returns:	QNs – Values take all allowed combinations [‘l’,’lp’,’L’,’m’,’mp’,’M’] from supplied matE
Return type:	2D np.array

Examples

>>> # From demo matrix elements
>>> dataFile = os.path.join(dataPath, 'n2_3sg_0.1-50.1eV_A2.inp.out')  # Set for sample N2 data for testing
>>> # Scan data file
>>> dataSet = ep.readMatEle(fileIn = dataFile)
>>> QNs = genllpMatE(dataSet[0])
>>> # Use with w3jTable function to calculate Wigner 3j terms
>>> w3j = w3jTable(QNs = QNs)

Implement output options (see dev. function w3jTable).

epsproc.geomFunc.mfblmXprod(matEin, QNs=None, EPRX=None, p=[0], lambdaTerm=None, BLMtable=None, thres=0.01, thresDims='Eke', selDims={'Type': 'L', 'it': 1}, sumDims=['mu', 'mup', 'l', 'lp', 'm', 'mp'], sumDimsPol=['P', 'R', 'Rp', 'p'], symSum=True, SFflag=True)[source]¶

epsproc.geomFunc.mfblmXprod(matEin, QNs=None, EPRX=None, p=[0], lambdaTerm=None, BLMtable=None, thres=0.01, thresDims='Eke', selDims={'Type': 'L', 'it': 1}, sumDims=['mu', 'mup', 'l', 'lp', 'm', 'mp'], sumDimsPol=['P', 'R', 'Rp', 'p'], symSum=True, SFflag=True)[source]

epsproc.geomFunc.remapllpL(dataIn, QNs, form='dict', method='sel', dlist=['l', 'lp', 'L', 'm', 'mp', 'M'], verbose=0)[source]¶

Remap Wigner 3j table, with QNs (l,lp,L,m,mp,M) > tensor forms.

Tensors are stored by (l,lp,L) triples, with corresponding arrays [m,mp,M], as a dictionary, or Xarray dataarray or dataset.

Parameters:	dataIn (np.array) – Array of data values corresponding to rows (coords) in QNs. QNs (np.array) – List of QNs [l, lp, L, m, mp, M] to compute 3j terms for. If not supplied all allowed terms for {Lmin, Lmax} will be set. (If supplied, values for Lmin, Lmax and mFlag are not used.) form (str, optional, default = 'dict') – Type of output structure. - ‘dict’ : dictionary with keys (l,lp,L), coordinate tables - ‘3d’ : dictionary with keys (l,lp,L), 3D arrays indexed by [l+m, lp+mp, L+M]; this case also sets (0,0,0) term as ‘w3j0’. - ‘xdaLM’ : Xarray dataarray, with stacked dims [‘lSet’,’mSet’] - ‘xds’ : Xarray dataset, with one array per (l,lp,L) - ‘xdalist’ : List of Xarray dataarrays, one per (l,lp,L) method (str, optional, default = 'sel') – Method for selection from input array. - ‘sel’ : use full selection routine, `epsproc.selQNsRow()`, should be most robust. - ‘n’ : sort based on np.unique reindexing. Should be faster, but possibly not robust…? dlist (list, optional, default = ['l','lp','L','m','mp','M']) – Full list of dimension names to use/set.
Returns:	w3j – Wigner3j(l,lp,L,m,mp,M) values corresponding to rows (coords) in QNs, type according to input form. Data structure sorted by (l,lp,L) triples.
Return type:	Xarray, dictionary

epsproc.geomFunc.selQNsRow(QNs, QNmask, fields=None, verbose=1)[source]¶

Basic routine for selecting/filtering valid rows from an input array of QNs.

This is similar to methods used in Matlab version, but likely rather slow.

Parameters:

QNs (np.array) – Values to be filtered.
QNmask (list or np.array) – Values to be matched. Must be same dims as QNs, unless fields is also set. If set to None field will be skipped (i.e. match all values)
fields (list or np.array, optional, default = None) – Which fields to match in QNs.
verbose (int, optional, default = 1) – Print info to terminal.

Returns:

QNs[boolMask] (np.array of selected values.)
boolMask (np.array corresponding to selected values.)

Examples

>>> QNsMask, mask = selQNsRow(QNs,[None, None, None, 0, 0, 0], verbose = False)
>>> # With fields
>>> QNsMask, mask = selQNsRow(QNs,[0, 0, 0], fields = [3,4,5], verbose = False)

epsproc.geomFunc.setPhaseConventions(phaseConvention='S', typeList=False)[source]¶

Set phase convention/choices for geometric functions.

20/03/20 - first attempt. Aim to centralise all phase choices here to keep things clean and easy to debug/change.

Set as dictionary for each term, to be appended to results Xarray.

Parameters:

phaseConvention (optional, str, default = 'S') – Set phase conventions: - ‘S’ : Standard derivation. - ‘R’ : Reduced form geometric tensor derivation. - ‘E’ : ePolyScat, may have additional changes in numerics, e.g. conjugate Wigner D. If a dict of phaseConventions is passed they will simply be returned - this is for transparency/consistency over multiple fns which call setPhaseConventions()… although may be an issue in some cases.
typeList (optional, bool, default = False) – If true, return list of supported options instead of list of phase choices.

Note

If a dict of phaseConventions is passed they will simply be returned - this is for transparency/consistency over multiple fns which call setPhaseConventions()… although may be an issue in some cases.

epsproc.geomFunc.setPhaseConventions(phaseConvention='S', typeList=False)[source]

Set phase convention/choices for geometric functions.

20/03/20 - first attempt. Aim to centralise all phase choices here to keep things clean and easy to debug/change.

Set as dictionary for each term, to be appended to results Xarray.

Parameters:

phaseConvention (optional, str, default = 'S') – Set phase conventions: - ‘S’ : Standard derivation. - ‘R’ : Reduced form geometric tensor derivation. - ‘E’ : ePolyScat, may have additional changes in numerics, e.g. conjugate Wigner D. If a dict of phaseConventions is passed they will simply be returned - this is for transparency/consistency over multiple fns which call setPhaseConventions()… although may be an issue in some cases.
typeList (optional, bool, default = False) – If true, return list of supported options instead of list of phase choices.

Note

If a dict of phaseConventions is passed they will simply be returned - this is for transparency/consistency over multiple fns which call setPhaseConventions()… although may be an issue in some cases.

epsproc.geomFunc.w3jTable(Lmin=0, Lmax=10, QNs=None, mFlag=True, nonzeroFlag=False, form='2d', dlist=['l', 'lp', 'L', 'm', 'mp', 'M'], backend='par', verbose=0)[source]¶

Calculate/tabulate all wigner 3j terms for a given problem/set of QNs.

\[\begin{split}\begin{equation} \begin{array}{ccc} l & l' & L\\ m & m' & M \end{array} \end{equation}\end{split}\]

Where l, l’ take values Lmin…Lmax (default 0…10). \(\l-lp\<=L<=l+lp\) m, mp take values -l…+l if mFlag=True, or =0 only if mFlag=False

Parameters:	Lmax (Lmin,) – Integer values for Lmin and Lmax respectively. QNs (np.array, optional, default = None) – List of QNs [l, lp, L, m, mp, M] to compute 3j terms for. If not supplied all allowed terms for {Lmin, Lmax} will be set. (If supplied, values for Lmin, Lmax and mFlag are not used.) mFlag (bool, optional, default = True) – m, mp take all values -l…+l if mFlag=True, or =0 only if mFlag=False nonzeroFlag (bool, optional, default = False) – Drop null terms before returning values if true. form (string, optional, default = '2d') – Defines return format. Options are: 2d, return 2D np.array, rows [l, lp, L, m, mp, M, 3j] xarray, return xarray This is nice for easy selection/indexing, but may be problematic for large Lmax if unstacked (essentailly similar to nd case). nd, return ND np.array, dims indexed as [l, lp, L, l+m, lp+mp, L+M], with values 3j. This is suitable for direct indexing, but will have a lot of zero entries and may be large. ndsparse, return ND sparse array, dims indexed as [l, lp, L, l+m, lp+mp, L+M], with values 3j. Additional options are set via `remapllpL()`. This additionally sorts values by (l,lp,L) triples, which is useful in some cases. ’dict’ : dictionary with keys (l,lp,L), coordinate tables ‘3d’ : dictionary with keys (l,lp,L), 3D arrays indexed by [l+m, lp+mp, L+M]; this case also sets (0,0,0) term as ‘w3j0’. ’xdaLM’ : Xarray dataarray, with stacked dims [‘lSet’,’mSet’] ’xds’ : Xarray dataset, with one array per (l,lp,L) ’xdalist’ : List of Xarray dataarrays, one per (l,lp,L) dlist (list of labels, optional, default ['l','lp','L','m','mp','M']) – Used to label array for Xarray output case. backend (str, optional, default = 'par') – See Implementation note below.
Returns:	w3j – Wigner3j(l,lp,L,m,mp,M) values corresponding to rows (coords) in QNs, type according to input form.
Return type:	np.array, Xarray, dictionary

Currently set to run:

‘vec’: w3jguVecCPU(), which uses sf.Wigner3j on the back-end, with additional vectorisation over supplied QNs via Numba’s @guvectorize.
‘par’: w3jprange(), which uses sf.Wigner3j on the back-end, with parallelization over QNs via Numba’s @njit with a prange loop.

epsproc.geomFunc.w3jguVecCPU(QNs, w3j_QNs)[source]¶

Wrapper for 3j with vectorization via @numba.guvectorize([“void(int32[:,:], float64[:])”], ‘(n,m)->(n)’, target = ‘parallel’).

Parameters:	QNs (np.array) – Array of QNs to calculated Wigner 3j terms for, columns [l,lp,L,m,mp,M]. w3j_QNs (np.array) – Empty array to hold results (no return from @guvectorize). Create as w3j_QNs = np.zeros(QNs.shape[0])

epsproc.geomFunc.w3jprange(QNs)[source]¶

Wrapper for 3j with @numba.njit(parallel=True), using prange parallel loop.

In testing (Feb 2020) on an AMD Threadripper 1950X (16 core) this was (usually) fastest case, and beat vectorised version.

Parameters:	QNs (np.array) – Array of QNs to calculated Wigner 3j terms for, columns [l,lp,L,m,mp,M].
Returns:	w3j_QNs – Array of Wigner 3j results, one per row of input QNs.
Return type:	np.array