PowerExpansion

PowerExpansion:

The PowerExpansion module defines the Taylor3D class, which is for 3-dimensional (xyz) Taylor expansions of functions. It’s primary purpose is to be used in the calculation of the vacancy Green function, as it allows fairly straightforward block evaluation of the small k (large distance) transition matrix, and its inverse. This is key to removing the pole in the Green function evaluation.

Power expansion class

Class to store and manipulate 3-dimensional Taylor (power) expansions of functions Particularly useful for inverting the FT of the evolution matrix, and subtracting off analytically calculated IFT for the Green function.

Really designed to get used by other code.

class PowerExpansion.Taylor2D(coefflist=[], Lmax=4, nodeepcopy=False)

Class that stores a Taylor expansion of a function in 2D, and defines some arithmetic

classmethod __initTaylor2Dindexing__(Lmax)

This calls all the class methods defined above, and stores them for the class. This is intended to be done once

Parameters:

Lmax – maximum power / orbital angular momentum

__init__(coefflist=[], Lmax=4, nodeepcopy=False)

Initializes a Taylor3D object, with coefflist (default = empty)

Parameters:

• coefflist – list((n, lmax, powexpansion)). No type checking; default empty

• Lmax – maximum power / orbital angular momentum; can be set only once the first time a Taylor expansion is constructed, and is set for all objects

• nodeepcopy – true if we don’t want to copy the matrices on creation of object (i.e., deep copy, which is the default) Note: deep copy is strongly preferred. The only real reason to use nodeepcopy is when returning slices / indexing in arrays, but even then we have to be careful about doing things like reductions, etc., that modify matrices in place. We always copy the list, but that doesn’t make copies of the underlying matrices.

__str__()

Human readable string representation

classmethod checkinternalsHDF5(HDF5group)

Reads the power expansion internals into an HDF5group, and performs sanity check

Parameters:

HDF5group – HDF5 group

dumpinternalsHDF5(HDF5group)

Adds the initialized power expansion internals into an HDF5group–should be stored for a sanity check

Parameters:

HDF5group – HDF5 group

classmethod makeFCpow()

Construct the expansion of the FC’s in powers of x,y. Done via brute force.

Return FCpow[l, p]:

expansion of each FC in powers

classmethod makeLprojections()

Constructs a series of projection matrices for each l component in our power series

Returns:

projL[l][p][p’] projection of powers containing only l component. -1 component = sum(l=0..Lmax, projL[l]) = simplification projection

classmethod makedirectmult()

Return direcmult[p][p’]:

index that corresponds to the multiplication of power indices p and p’

static makeindexPowerFC(Lmax)

Analyzes the Fourier coefficients and powers for a given Lmax; returns a series of index functions.

Parameters:

Lmax – maximum l value to consider; equal to the sum of powers

Return NFC:

number of Fourier coefficients

Return Npower:

number of power coefficients

Return pow2ind[n1][n2]:

powers to index

Return ind2pow[n]:

powers for a given index

Return FC2ind[l]:

12. to index

Return ind2FC[lind]:

12. for a given index

Return powlrange[l]:

upper limit of power indices for a given l value; note: [-1] = 0

classmethod makepowFC()

Construct the expansion of the powers in FC’s. Done using brute force

Return powFC[p, l]:

expansion of powers in FC; uses indexing scheme above

classmethod makepowercoeff()

Make our power coefficients for our construct expansion method

Return powercoeff[n][p]:

vector we multiply by our power expansion to get the n’th coefficients

classmethod powexp(u, normalize=True)

Given a vector u, normalize it and return the power expansion of uvec

Parameters:

• u[2] – vector to apply

• normalize – do we normalize u first?

Return upow[Npower]:

ux uy uz products of powers

Return umagn:

magnitude of u (if normalized)

classmethod rotatedirections(qptrans)

Takes a transformation matrix qptrans, where q[i] = sum_j qptrans[i][j] p[j], and returns the Npow x Npow transformation matrix for the new components in terms of the old. NOTE: This is more complex than one might first realize. If we only work with cases where all of the entries for a given power n have those same n (that is, not reduced), then this is straightforward. However, we run into problems with reductions: e.g., for n=2, the power \(x^0 y^0 z^0\) is, in reality, \(x^2+y^2+z^2\), and hence it must be transformed because we allow non-orthogonal transformation matrices.

Parameters:

qptrans – 3x3 matrix

Return npowtrans:

[Lmax +1][Npow][Npow] transformation matrix [n][original pow][new pow] for each n from 0 up to Lmax

class PowerExpansion.Taylor3D(coefflist=[], Lmax=4, nodeepcopy=False)

Class that stores a Taylor expansion of a function in 3D, and defines some arithmetic

__add__(other)

Add a set of Taylor expansions

__call__(u, fnu=None)

Method for evaluating our 3D Taylor expansion. We have two approaches: if we are passed a dictionary in fnu that will map (n,l) tuple pairs to either (a) values or (b) functions of a single parameter umagn, then we will compute and return the function value. Otherwise, we return a dictionary mapping (n,l) tuple pairs into values, and leave it at that.

Parameters:

• u – three vector to evaluate; may (or may not) be normalized

• fnu – dictionary of (n,l): value or function pairs.

Return value or dictionary:

depending on fnu; default is dictionary

__getitem__(key)

Indexes (or even slices) into our Taylor expansion.

Parameters:

key – indices for our Taylor expansion

Return Taylor3D:

Taylor expansion after indexing

__iadd__(other)

Add a set of Taylor expansions

classmethod __initTaylor3Dindexing__(Lmax)

This calls all the class methods defined above, and stores them for the class. This is intended to be done once

Parameters:

Lmax – maximum power / orbital angular momentum

__init__(coefflist=[], Lmax=4, nodeepcopy=False)

Initializes a Taylor3D object, with coefflist (default = empty)

Parameters:

• coefflist – list((n, lmax, powexpansion)). No type checking; default empty

• Lmax – maximum power / orbital angular momentum; can be set only once the first time a Taylor expansion is constructed, and is set for all objects

• nodeepcopy – true if we don’t want to copy the matrices on creation of object (i.e., deep copy, which is the default) Note: deep copy is strongly preferred. The only real reason to use nodeepcopy is when returning slices / indexing in arrays, but even then we have to be careful about doing things like reductions, etc., that modify matrices in place. We always copy the list, but that doesn’t make copies of the underlying matrices.

__isub__(other)

Subtract a set of Taylor expansions

__mul__(other)

Multiply our expansion

Parameters:

other

Return Taylor3D:

expansion of product

__neg__()

Return -T3D

__pos__()

Return +T3D

__radd__(other)

Add a set of Taylor expansions

__rmul__(other)

Multiply our expansion

Parameters:

other

Return Taylor3D:

expansion of product

__rsub__(other)

Subtract a set of Taylor expansions

__setitem__(key, value)

Indexes (or even slices) into our Taylor expansion and “sets”; really only intended to work with another Taylor expansion

Parameters:

• key – indices for our Taylor expansion

• value – assignment value; really, should be

Returns:

Taylor expansion after indexing

__str__()

Human readable string representation

__sub__(other)

Subtract a set of Taylor expansions

__weakref__

list of weak references to the object

addhdf5(HDF5group)

Adds an HDF5 representation of object into an HDF5group (needs to already exist). Example: if f is an open HDF5, then T3D.addhdf5(f.create_group(‘T3D’)) will (1) create the group named ‘T3D’, and then (2) put the T3D representation in that group.

Parameters:

HDF5group – HDF5 group

addterms(coefflist)

Add additional coefficients into our object. No type checking. Only works if terms are completely non-overlapping (otherwise, need to use sum).

Parameters:

coefflist – list((n, lmax, powexpansion))

classmethod checkinternalsHDF5(HDF5group)

Reads the power expansion internals into an HDF5group, and performs sanity check

Parameters:

HDF5group – HDF5 group

classmethod coeffproductcoeff(a, b)

Takes a direction expansion a and b, and returns the product expansion.

Parameters:

• a – list((n, lmax, powexpansion)

• b – list((n, lmax, powexpansion) written as a series of coefficients; n defines the magnitude function, which is additive; lmax is the largest cumulative power of coefficients, and powexpansion is a numpy array that can multiplied. We assume that a and b have consistent shapes throughout–we do not test this; runtime will likely fail if not true. The entries in the list are tuples of n, lmax, pow

Return c:

list((n, lmax, powexpansion)), product of a and b

classmethod collectcoeff(a, inplace=False, atol=1e-10)

Collects coefficients: sums up all the common n values. Best to be done after reduce is called.

Parameters:

• a – list((n, lmax, powexpansion), expansion of function in powers

• inplace – modify a in place?

Return coefflist:

a

classmethod constructexpansion(basis, N=-1, pre=None)

Takes a “basis” for constructing an expansion – list of vectors and matrices – and constructs the expansions up to power N (default = Lmax)

Parameters:

• vect)) (basis = list((coeffmatrix,) – expansions to create; sum(coeffmatrix * (vect*q)^n), for powers n = 0..N

• N – maximum power to consider; for N=-1, use Lmax

• pre – list of prefactors, defining the Taylor expansion. Default = 1

Return list((n, lmax, powexpansion)),…:

our expansion, as input to create Taylor3D objects

copy()

Returns a copy of the current expansion

dumpinternalsHDF5(HDF5group)

Adds the initialized power expansion internals into an HDF5group–should be stored for a sanity check

Parameters:

HDF5group – HDF5 group

ildot(c)

Computes \(c\cdot self\) in place

inv(Nmax=0)

Return the inverse of the expansion, up to order Nmax

Parameters:

Nmax – maximum order in the inverse expansion

Return Taylor3D^-1:

Taylor series of inverse

classmethod inversecoeff(a, Nmax=0)

Takes a direction expansion , and returns the inversion expansion (approximated based on the Taylor expansion of \(1/(1-x) = \sum_{i=0}^{\infty} x^i\), or \((A + B)^{-1} = ((1+BA^{-1})A)^{-1} = A^{-1}(1-(-BA{^1}))^{-1} = A^{-1} \sum_{i=0} (-BA^{-1})^i\)

NOTE: assumes SMALLEST n coefficient is the leading order; only works if that coefficient is also isotropic (l=0). Otherwise, raises an error. NOTE: there is no sanity check on whether Nmax is reasonable given the expansion and Lmax values; caveat emptor.

Parameters:

• a – = list((n, lmax, powexpansion) written as a series of coefficients; n defines the magnitude function, which is additive; lmax is the largest cumulative power of coefficients, and powexpansion is a numpy array that can multiplied. We assume that a and b have consistent shapes throughout–we do not test this; runtime will likely fail if not true. The entries in the list are tuples of n, lmax, pow

• Nmax – maximum remaining n value in expansion. Default value of 0 means up to a discontinuity correction in an inversion, but higher (or lower) values are possible.

Return c:

list((n, lmax, powexpansion)), inverse of a

irdot(c)

Computes \(self\cdot c\) in place

irotate(powtrans)

Rotate in place.

Parameters:

powtrans – Npow x Npow matrix, of [oldpow,newpow] corresponding to the rotation

Returns:

self

ldot(c)

Returns \(c\cdot self\)

classmethod loadhdf5(HDF5group)

Creates a new T3D from an HDF5 group.

Parameters:

HDFgroup – HDF5 group

Return T3D:

new T3D object

classmethod makeLprojections()

Constructs a series of projection matrices for each l component in our power series

Returns:

projL[l][p][p’] projection of powers containing only l component. -1 component = sum(l=0..Lmax, projL[l]) = simplification projection

classmethod makeYlmpow()

Construct the expansion of the Ylm’s in powers of x,y,z. Done via brute force.

Return Ylmpow[lm, p]:

expansion of each Ylm in powers

classmethod makedirectmult()

Return direcmult[p][p’]:

index that corresponds to the multiplication of power indices p and p’

static makeindexPowerYlm(Lmax)

Analyzes the spherical harmonics and powers for a given Lmax; returns a series of index functions.

Parameters:

Lmax – maximum l value to consider; equal to the sum of powers

Return NYlm:

number of Ylm coefficients

Return Npower:

number of power coefficients

Return pow2ind[n1][n2][n3]:

powers to index

Return ind2pow[n]:

powers for a given index

Return Ylm2ind[l][m]:

(l,m) to index

Return ind2Ylm[lm]:

(l,m) for a given index

Return powlrange[l]:

upper limit of power indices for a given l value; note: [-1] = 0

classmethod makepowYlm()

Construct the expansion of the powers in Ylm’s. Done using recursion relations instead of direct calculation. Note: an alternative approach would be Gaussian quadrature.

Return powYlm[p][lm]:

expansion of powers in Ylm; uses indexing scheme above

classmethod makepowercoeff()

Make our power coefficients for our construct expansion method

Return powercoeff[n][p]:

vector we multiply by our power expansion to get the n’th coefficients

classmethod negcoeff(a)

Negates a coefficient expansion a

Parameters:

powexpansion) (a = list((n, lmax,) – expansion of function in powers

Return coefflist:

-a

nl()

Returns a list of (n,l) pairs in the coefflist

Return nl_list:

all of the (n,l) pairs that are present in our coefflist

classmethod powexp(u, normalize=True)

Given a vector u, normalize it and return the power expansion of uvec

Parameters:

• u[3] – vector to apply

• normalize – do we normalize u first?

Return upow[Npower]:

ux uy uz products of powers

Return umagn:

magnitude of u (if normalized)

rdot(c)

Returns \(self\cdot c\)

reduce()

Reduce the coefficients: eliminate any n that has zero coefficients, collect all of the same values of n together. Done in place.

classmethod reducecoeff(a, inplace=False, atol=1e-10)

Projects coefficients through Ylm space, then eliminates any zero contributions (including possible reduction in l values, too).

Parameters:

• a – list((n, lmax, powexpansion), expansion of function in powers

• inplace – modify a in place?

Return coefflist:

a

rotate(powtrans)

Return a rotated version of the expansion.

Parameters:

powtrans – Npow x Npow matrix, of [oldpow,newpow] corresponding to the rotation

Return rTaylor3D:

Taylor expansion, rotated

classmethod rotatecoeff(a, npowtrans, inplace=False)

Return a rotated version of the expansion. Needs to use pad to work with reduced representations.

Parameters:

• a – coefficiant list

• npowtrans – Lmax+1 x Npow x Npow matrix, of [n,oldpow,newpow] corresponding to the rotation

Return rcoeff:

coefficient list, rotated

classmethod rotatedirections(qptrans)

Takes a transformation matrix qptrans, where q[i] = sum_j qptrans[i][j] p[j], and returns the Npow x Npow transformation matrix for the new components in terms of the old. NOTE: This is more complex than one might first realize. If we only work with cases where all of the entries for a given power n have those same n (that is, not reduced), then this is straightforward. However, we run into problems with reductions: e.g., for n=2, the power \(x^0 y^0 z^0\) is, in reality, \(x^2+y^2+z^2\), and hence it must be transformed because we allow non-orthogonal transformation matrices.

Parameters:

qptrans – 3x3 matrix

Return npowtrans:

[Lmax +1][Npow][Npow] transformation matrix [n][original pow][new pow] for each n from 0 up to Lmax

classmethod scalarproductcoeff(c, a, inplace=False)

Multiplies an coefficient expansion a by a scalar c

Parameters:

• c – scalar or dictionary mapping (n,l) to scalars

• powexpansion) (a = list((n, lmax,) – expansion of function in powers

• inplace – modify a in place?

Return coefflist:

c*a

separate()

Separate out the coefficients into (n,l) terms where only l contributions appear in each.

classmethod separatecoeff(a, inplace=False, atol=1e-10)

Projects coefficients through Ylm space, one by one. Assumes they’ve already been reduced and collected first; if not, could lead to duplicated (n,l) entries in list, which is inefficient (should still evaluate the same, just with extra steps). After this, each (n,l) term only contains terms equal to l, rather than terms <= l.

Parameters:

• a – list((n, lmax, powexpansion), expansion of function in powers

• inplace – modify a in place?

Return coefflist:

a

classmethod sumcoeff(a, b, alpha=1, beta=1, inplace=False)

Takes Taylor3D expansion a and b, and returns the sum of the expansions.

Param:

a, b = list((n, lmax, powexpansion) written as a series of coefficients; n defines the magnitude function, which is additive; lmax is the largest cumulative power of coefficients, and powexpansion is a numpy array that can multiplied. We assume that a and b have consistent shapes throughout–we do not test this; runtime will likely fail if not true. The entries in the list are tuples of n, lmax, pow

Parameters:

• beta (alpha,) – optional scalars: c = alpha*a + beta*b; allows for more efficient expansions

• inplace – True if the summation should modify a in place

Return c:

coeff of sum of a and b (! NOTE ! does not return the class!) sum of a and b

classmethod tensorproductcoeff(c, a, leftmultiply=True)

Multiplies an coefficient expansion a by a scalar c

Parameters:

• c – array or dictionary mapping (n,l) to arrays

• powexpansion) (a = list((n, lmax,) – expansion of function in powers

• leftmultiply – tensordot(c,a) vs. tensordot(a,c)

Return coefflist:

c.a (or a.c)

truncate(Nmax, inplace=False)

Remove the coefficients above a given Nmax; normally returns a new object

Parameters:

• Nmax – maximum coefficient to include

• inplace – do it in place?

classmethod truncatecoeff(a, Nmax, inplace=False)

Remove the coefficients above a given Nmax; normally returns a new object

Parameters:

• Nmax – maximum coefficient to include

• a – list((n, lmax, powexpansion), expansion of function in powers

• inplace – do it in place?

classmethod zeros(nmin, nmax, shape, dtype=<class 'complex'>)

Constructs (and returns) a “zero” Taylor expansion with the prescribed shape. This will be useful for doing slicing assignments. Because of the manner in which slicing works for assignment, we create what looks like a lot of zeros, by explicitly making the full range of l values.

Parameters:

• nmin – minimum value of n

• nmax – maximum value of n (inclusive)

• shape – shape of matrix, as zeros would expect.

Return Taylor3D:

Taylor3D, with a zero coefficient list