epsproc.geomFunc package

Submodules

• epsproc.geomFunc.afblmGeom module
  • AFwfExp()
  • afblmXprod()
• epsproc.geomFunc.afblmGeom_bk161020 module
• epsproc.geomFunc.afblmGeom_v1-ref_2020 module
• epsproc.geomFunc.geomCalc module
  • CG()
  • EPR()
  • MFproj()
  • betaTerm()
  • deltaLMKQS()
  • deltalmKQSwf()
  • remapllpL()
  • setPhaseConventions()
  • w3jTable()
• epsproc.geomFunc.geomUtils module
  • degenChecks()
  • genKQSterms()
  • genKQStermsFromTensors()
  • genLmLamKQStermsFromTensors()
  • genllL()
  • genllLList()
  • genllpMatE()
  • selQNsRow()
• epsproc.geomFunc.lfblmGeom module
  • lfblmXprod()
• epsproc.geomFunc.mfblmGeom module
  • mfblmXprod()
• epsproc.geomFunc.w3jVecMethods module
  • Wigner3jQNs()
  • w3jguVecCPU()
  • w3jprange()
• epsproc.geomFunc.wNjSympyWrapper module
  • w3jSympy()

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

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'], eNames=['Ph', 'Th', 'Ch'], phaseConvention='S')

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.

• eNames (optional, list, default = ['Ph','Th','Ch']) –

  Set names for Euler angles in output. Note:

  • eNames = [‘P’,’T’,’C’] matches defaults in epsproc.sphCalcs.setPolGeoms() and epsproc.sphCalcs.wDcalc(), but conflicts with QNs ‘P’.

  • eNames = [‘Phi’,’Theta’,’Chi’] may give issues elsewhere, e.g. when multiplying by Ylms with same dim names.

Notes

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

12/08/22 Added option for Euler angle dim names to avoid conflicts elsewhere.

Examples

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

epsproc.geomFunc.Wigner3jQNs(QNs)

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'}, sqThres=True, dropThres=True, 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)

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.

24/11/22 Added sqThres = True, dropThres = True for use with INITIAL matEleSelector() call only - in some cases may get issues with dim drops here otherwise.

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.

For basic use see the docs: https://epsproc.readthedocs.io/en/dev/demos/ePSproc_class_demo_161020.html#Compute-LF/AF-beta_{LM}-and-PADs

Dev code:

• afblmGeom_v1-ref_2020.py - Messy working v1 for reference, archived 04/05/21. Now working on tidier version.

• 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

Parameters

• matE (Xarray) – Xarray containing matrix elements, with QNs (l,m), as created by readMatEle()

• settings (*** Optional calculation) –

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

SFflagbool, default = False

Multiply input matrix elements by complex scale-factor if true.

SFflagRenormbool, default = False

Renorm output BLMs by complex scale-factor if true.

BLMRenormint, default = 1

Set different BLM renorm conventions. If 1 renorm by B00. See code for further details.

sqThresbool, default = True

Used for initial matrix element threholding call only. Default = True as previous code, but can cause issues in custom cases (usually accidentally dropping singleton mu coord). Added 24/11/22

dropThresbool, default = True

Used for initial matrix element threholding call only. Default = True as previous code, but can cause issues in custom cases (usually accidentally dropping singleton mu coord). Added 24/11/22

squeezebool, 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)

QNsnp.array, optional, default = None

List of QNs as generated by genllpMatE(). Will be generated if not passed.

AKQSXarray, optional, default = None

Alignment parameters, as set by setADMs(). Defaults to isotropic case if not passed.

EPRXXarray, optional, default = None

E-field parameters, as generated by EPR(). Defaults to normalised/unity field, pol = p (below).

plist 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, BLMtableResortXarrays, optional, default = None

Beta calculation parameters, as defined by geomCalc.betaTerm(). BLMtableResort includes phase settings & param renaming as herein.

lambdaTermXarray, optional, default = None

Lambda term parameters, as defined by geomCalc.MFproj()

AFtermXarray, optional, default = None

Alignment term as defined by geomCalc.deltaLMKQS()

polProdXarray, optional, default = None

Polarization tensor as defined by EPRXresort * lambdaTermResort * AFterm

phaseConventionoptional, str, default = ‘E’

Set phase conventions with epsproc.geomCalc.setPhaseConventions(). To use preset phase conventions, pass existing dictionary.

basisReturnoptional, 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.

**kwargs, unused but allows for arb basis dict unpack and passing from other functions.

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

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

• Lmin (int, optional, default 0, 10) – Integer values for Lmin and Lmax respectively.

• Lmax (int, optional, default 0, 10) – 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')

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)

epsproc.geomFunc.genKQStermsFromTensors(EPR, AKQS, uniqueFlag=True, phaseConvention='S')

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)

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

Parameters

• Lmin (int, optional, default 0, 10) – Integer values for Lmin and Lmax respectively.

• Lmax (int, optional, default 0, 10) – 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)

To do

• Implement output options (see dev. function w3jTable).

epsproc.geomFunc.genllLList(Llist, uniqueFlag=True, mFlag=True)

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

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)

To do

• Implement output options (see dev. function w3jTable).

epsproc.geomFunc.genllpMatE(matE, uniqueFlag=True, mFlag=True, phaseConvention='S')

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)

To do

• Implement output options (see dev. function w3jTable).

epsproc.geomFunc.mfblmXprod(matEin, QNs=None, EPRX=None, p=[0], BLMtable=None, BLMtableResort=None, lambdaTerm=None, RX=None, eulerAngs=None, polProd=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=0, **kwargs)

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.

12/08/22 Updating from afblmXprod routine for use with fitting functions.

Added ProductBasis return as per afblmGeom case, for use in fitting. 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. Updated docs as per afblmXprod. TODO: still needs a tidy up and update, including BLM renorm options, again see afblmGeom code.

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

Parameters

• matE (Xarray) – Xarray containing matrix elements, with QNs (l,m), as created by readMatEle()

• settings (*** Optional calculation) –

• selDims (dict, default = {'it':1, 'Type':'L'}) – Selection parameters for calculations, may be be checked and appened herein.

• sumDims (list, default = ['mu', 'mup', 'l','lp','m','mp']) – 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. NOT IMPLEMENTED FOR MF CASE - see afblmXprod.

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

SFflagbool, default = False

Multiply input matrix elements by complex scale-factor if true.

SFflagRenormbool, default = False

Renorm output BLMs by complex scale-factor if true. NOT IMPLEMENTED FOR MF CASE - see afblmXprod.

BLMRenormint, default = 1

Set different BLM renorm conventions. If 1 renorm by B00. See code for further details. NOT IMPLEMENTED FOR MF CASE - see afblmXprod.

squeezebool, 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)

QNsnp.array, optional, default = None

List of QNs as generated by genllpMatE(). Will be generated if not passed.

EPRXXarray, optional, default = None

E-field parameters, as generated by EPR(). Defaults to normalised/unity field, pol = p (below).

plist 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, BLMtableResortXarrays, optional, default = None

Beta calculation parameters, as defined by geomCalc.betaTerm(). BLMtableResort includes phase settings & param renaming as herein.

lambdaTermXarray, optional, default = None

Lambda term parameters, as defined by geomCalc.MFproj()

RXXarray, optional, default = None

Polarization geometries as defined by epsproc.sphCalc.setPolGeoms(). If not set, defaults are used by epsproc.geomFunc.geomCalc.MFproj(). If not set, but Euler angles are set, then these will be used.

eulerAngslist or np.array of Euler angles (p(hi), t(heta), c(hi)), optional.

Alternative definition for polarization geometries, as used by epsproc.sphCalc.setPolGeoms(). List or array [p,t,c…], shape (Nx3). List or array including set labels, [label,p,t,c…], shape (Nx4)

polProdXarray, optional, default = None

Polarization tensor as defined by EPRXresort * lambdaTermResort

phaseConventionoptional, str, default = ‘E’

Set phase conventions with epsproc.geomCalc.setPhaseConventions(). To use preset phase conventions, pass existing dictionary.

basisReturnoptional, 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.

**kwargs, unused but allows for arb basis dict unpack and passing from other functions.

Returns

• Xarray – Set of AFBLM calculation results

• dict – Dictionary of basis functions, only if basisReturn != ‘BLM’ (see basisReturn paramter notes).

Notes

Cross-section outputs currently defined as XS = direct MF calculation output.

Optionally set SFflag = True to multiply by (complex) scale-factor.

OTHER RENORM options not implemented as yet, see afblmXprod for details.

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

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)

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)

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)

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

• Lmin (int, optional, default 0, 10) – Integer values for Lmin and Lmax respectively.

• Lmax (int, optional, default 0, 10) – 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.

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

Implementation

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)

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)

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