# epsproc.geomFunc package¶

## 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}$$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{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}$$\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{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, BLMtableResort=None, lambdaTerm=None, polProd=None, AFterm=None, thres=0.01, thresDims='Eke', selDims={'Type': 'L'}, sumDims=['mu', 'mup', 'l', 'lp', 'm', 'mp', 'S-Rp'], sumDimsPol=['P', 'R', 'Rp', 'p'], symSum=True, degenDrop=True, SFflag=False, SFflagRenorm=False, BLMRenorm=1, squeeze=False, phaseConvention='E', basisReturn='BLM', verbose=0, **kwargs)[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.

04/05/22 Added **kwargs, unused but allows for arb basis dict unpack and passing from other functions. May want to pipe back to Full basis return however.

06/08/21 Added basic handling for degenerate states, including degenDrop option.
Updated docs, but still rather messy!
27/07/21 Removed eulerAngs & RX input options, since these are redundant (and lead to confusion here!).
For cases where E-field and alignment distribution are rotated, set AKQS in rotated frame, see https://epsproc.readthedocs.io/en/latest/tests/ePSproc_frame_rotation_tests_Dec2019.html Also removed selDims={‘it’:1}, which can result in issues! In current code, adding ‘it’ to sumDims doesn’t work (dim issues somewhere), so may be best to treat independently…?

03/05/21 Tidying up a bit & improving/wrapping for fitting use (inc. basis function reuse).

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:

Parameters: matE (Xarray) – Xarray containing matrix elements, with QNs (l,m), as created by readMatEle() Optional calculation settings (***) – selDims (dict, default = {'Type':'L'}) – Selection parameters for calculations, may be be checked and appened herein. sumDims (list, default = ['mu', 'mup', 'l','lp','m','mp','S-Rp']) – Main summation dims, will be checked herein. sumDimsPol (list, default = ['P','R','Rp','p']) – Additional polarization summation dims. symSum (bool, default = True) – Sum over symmetries sets (=={Cont, Targ, Total}) if true. degenDrop (bool) – Flag to set dropping of degenerate components. thres (float, default = 1e-2) – Set threshold value, used to set input matrix elements and again for outputs. thresDims (str, default = 'Eke') – Set threshold dimension (set to be contiguous). verbose (bool or int) – Print output?

*** Optional renormalisation settings (mainly for testing only)

SFflag : bool, default = False
Multiply input matrix elements by complex scale-factor if true.
SFflagRenorm : bool, default = False
Renorm output BLMs by complex scale-factor if true.
BLMRenorm : int, default = 1
Set different BLM renorm conventions. If 1 renorm by B00. See code for further details.
squeeze : bool, default = False
Squeeze output array after thresholding? Note: this may cause dim issues if True.

*** Optional input data/basis functions (mainly for fitting routine use)

QNs : np.array, optional, default = None
List of QNs as generated by genllpMatE(). Will be generated if not passed.
AKQS : Xarray, optional, default = None
Alignment parameters, as set by setADMs(). Defaults to isotropic case if not passed.
EPRX : Xarray, optional, default = None
E-field parameters, as generated by EPR(). Defaults to normalised/unity field, pol = p (below).
p : list or array, optional, default = [0]
Specify polarization terms p. Possibly currently only valid for p=0, TBC See https://epsproc.readthedocs.io/en/latest/methods/geometric_method_dev_260220_090420_tidy.html#E_{P,R}-tensor
BLMtable, BLMtableResort : Xarrays, optional, default = None
Beta calculation parameters, as defined by geomCalc.betaTerm(). BLMtableResort includes phase settings & param renaming as herein.
lambdaTerm : Xarray, optional, default = None
Lambda term parameters, as defined by geomCalc.MFproj()
AFterm : Xarray, optional, default = None
Alignment term as defined by geomCalc.deltaLMKQS()
polProd : Xarray, optional, default = None
Polarization tensor as defined by EPRXresort * lambdaTermResort * AFterm
phaseConvention : optional, str, default = ‘E’
Set phase conventions with epsproc.geomCalc.setPhaseConventions(). To use preset phase conventions, pass existing dictionary.
basisReturn : optional, str, default = “BLM”
• ‘BLM’ return Xarray of results only.
• ‘Full’ return Xarray of results + basis set dictionary as set during the run.
• ‘Product’, as full, but minimal basis set with products only.
• ‘Results’ or ‘Legacy’ direct return of various calc. results Xarrays.
Returns: Xarray – Set of AFBLM calculation results dict – Dictionary of basis functions, only if basisReturn != ‘BLM’ (see basisReturn paramter notes).

Notes

Cross-section outputs now set as:

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

Where XSrescaled == XSiso == ePS GetCro output for isotropic distribution. Optionally set SFflag = True to multiply by (complex) scale-factor.

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}$$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{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:

$$$\sum_{K,Q,S}\Delta_{L,M}(K,Q,S)A_{Q,S}^{K}(t)$$$
$\begin{split}$$\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{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() 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. 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 QNs – Values take all allowed combinations [‘l’,’lp’,’L’,’m’,’mp’,’M’] up to l=lp=Lmax, one set per row. 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. Note this needs to be 2D array in current form of function, i.e. defined as np.array([[L1,L2,L3],…]) 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 QNs – Values take all allowed combinations [‘l’,’lp’,’L’,’m’,’mp’,’M’] up to l=lp=Lmax, one set per row. 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. QNs – Values take all allowed combinations [‘l’,’lp’,’L’,’m’,’mp’,’M’] from supplied matE 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], 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'], sumDimsPol=['P', 'R', 'Rp', 'p'], symSum=True, SFflag=False, squeeze=False, phaseConvention='E', basisReturn='BLM', verbose=1)[source]

Implement $$\beta_{LM}^{MF}$$ calculation as product of tensors.

$\begin{split}\begin{eqnarray} \beta_{L,-M}^{\mu_{i},\mu_{f}} & = & \sum_{l,m,\mu}\sum_{l',m',\mu'}(-1)^{(\mu'-\mu_{0})}{B_{L,-M}}\nonumber \\ & \times & \sum_{P,R',R}{E_{P-R}(\hat{e})\Lambda_{R',R}(R_{\hat{n}})}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}\end{split}$

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

16/03/20 In progress! Dev code:

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.
epsproc.geomFunc.mfblmXprod(matEin, QNs=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'], sumDimsPol=['P', 'R', 'Rp', 'p'], symSum=True, SFflag=False, squeeze=False, phaseConvention='E', basisReturn='BLM', verbose=1)[source]

Implement $$\beta_{LM}^{MF}$$ calculation as product of tensors.

$\begin{split}\begin{eqnarray} \beta_{L,-M}^{\mu_{i},\mu_{f}} & = & \sum_{l,m,\mu}\sum_{l',m',\mu'}(-1)^{(\mu'-\mu_{0})}{B_{L,-M}}\nonumber \\ & \times & \sum_{P,R',R}{E_{P-R}(\hat{e})\Lambda_{R',R}(R_{\hat{n}})}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}\end{split}$

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

16/03/20 In progress! Dev code:

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.
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. 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. 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. 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{array}{ccc} l & l' & L\\ m & m' & M \end{array}$$\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.) NOTE: some return types will convert QNs to int when constructing Xarray output, unless half-int values present. Functions using epsproc.geomFunc.geomCalc.remapllpL() support half-int values in Xarray. 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. w3j – Wigner3j(l,lp,L,m,mp,M) values corresponding to rows (coords) in QNs, type according to input form. 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]. w3j_QNs – Array of Wigner 3j results, one per row of input QNs. np.array