Skip to content

treams_rs.lattice

Lattice sums of spherical and cylindrical waves, and lattice geometry.

Mirrors treams.lattice. A lattice of dimension d holds the points R = n_1 a_1 + ... + n_d a_d with integers n_i. The rows of a are the lattice vectors a_i. For a wavenumber k, a Bloch vector kpar (the real wavevector components along the lattice) and a shift r, the spherical and cylindrical sums are

D_lm(k, kpar, r) = sum'_R h_l(k |r + R|) Y_lm(-r - R) exp(i kpar . R)
D_m(k, kpar, r)  = sum'_R H_m(k |r + R|) exp(i m phi) exp(i kpar . R)

with the outgoing (first-kind) Hankel functions h_l and H_m, the spherical harmonic Y_lm in the direction of -r - R and the azimuth phi of -r - R. The prime drops the term with r + R = 0.

Spherical sums (*sw*) take a degree l and an order m and run over lattices in 1, 2 or 3 dimensions; cylindrical sums (*cw*) take an order m and run over lattices in 1 or 2 dimensions. A 1D spherical lattice lies on the z axis, a 1D cylindrical lattice on the x axis, and a 2D lattice in the plane z = 0. In 1D, a is the period and kpar a number. In 2D and 3D, a is a (d, d) array of rows, or the d side lengths of a rectangular cell, and kpar has d components. The functions that take the dimension dim as their first argument, and the lsum* functions, also take a Lattice for a and a WaveVector for kpar, and use their components along the lattice axes.

The Ewald method splits each sum into a real-space part (realsum*), a sum over lattice points, and a reciprocal-space part (recsum*), a sum over the diffraction orders kpar + G with reciprocal lattice vectors G. Both parts converge exponentially. The Ewald split parameter eta sets how the sum divides between them; the exact sum does not depend on it. eta=0 (the default) selects sqrt(2 pi) / (k L) max(|k L| / 8, 1), where L is the length, the square root of the area or the cube root of the volume of the cell. The direct sums dsum* add one shell of lattice points at a time and serve as a check. volume, area, reciprocal, cube, cubeedge and diffr_orders_circle describe the lattice itself.

Accuracy

The two Ewald parts grow and cancel as eta gets small. An explicit split far below the automatic one loses about eps * exp(Re(1 / (2 * eta**2))) of relative accuracy, with the machine precision eps = 2.2e-16.

  • A split is small when Re(1 / (2 * eta**2)) > 16 / pi, which holds below every automatic split; a real split is small below 0.31.
  • A sum at a small split predicts its loss from the terms it adds. It raises ValueError "Ewald split too small" where the loss exceeds 1e-3 of max(|S|, 1) for the sum S. Off the axis, a 1D spherical sum takes its spectral series instead, where that series applies.
  • At a small split the real-space part needs more terms: its cost grows like 1 / eta**2 up to the shell limit. A sum fails as soon as its predicted loss exceeds 2e-3 of max(|S|, 1) for the sum S at the automatic split.
  • At a small split, a complete sum whose real-space shells reach their limit is returned only if its last shells add a negligible amount and it matches the sum at the automatic split within the predicted loss. Otherwise it raises ValueError "did not converge".
  • realsum* and recsum* apply the 1e-3 rule with the scale max(|P|, 1) of their part P, so a part can succeed at a split where the complete sum fails.
  • Gradients from diff.lattice_sum fail the same way where the loss predicted for a derivative exceeds 1e-3 of |dS| + max(|S|, 1) s, and as soon as it exceeds 2e-3 of that at the automatic split. The factor s is |k| for the shift and the lattice vectors and 1 / |k| for k and kpar. A value can succeed where its gradient fails. Gradients of a single part need an explicit nonzero eta.
  • Ewald sums require Im k >= 0; spherical sums also require Re k >= 0. Unsupported wavenumbers raise ValueError before summation. Finite direct shells accept every finite nonzero complex wavenumber.

Differences from treams

  • a may be a Lattice and kpar a WaveVector, as described above.
  • eta defaults to 0, the automatic split; treams requires it.
  • The automatic split in 3D uses the cell length L = V**(1/3) of the volume V; treams divides by k V**(2/3). Both give the same sum where the parts converge.
  • Each Ewald part stops when two consecutive shells add less than 2e-13 max(|P|, 1) and raises ValueError at its shell limit or at a small split, as described under Accuracy. treams stops at a change below 1e-10 or after 200, 20 or 10 shells, and returns the sum without warning.
  • Both Ewald parts sum over a reduced basis, with the shift reduced into a cell of the lattice and kpar into a cell of the reciprocal lattice. treams sums over the given basis and can miss short lattice vectors of a skewed basis.
  • At a complex split and Im k >= 0, the reciprocal part continues the sum from the automatic split, so the value does not depend on the split. treams takes the principal branches.
  • For odd l (spherical) or odd m (cylindrical), kpar = 0 and a shift r in the lattice line or plane with 2 r a lattice vector, the sum is exactly zero at every split. treams returns exact zeros only at r = 0 (and at r = ±a / 2 in 1D).
  • Off the axis, the Ewald parts of a 1D spherical sum can cancel strongly. There the sum comes from a spectral series, a sum over diffraction orders of cylindrical waves, wherever that is more accurate.

Example:

import numpy as np
from treams_rs import Lattice, WaveVector, lattice

a, kpar = Lattice([1.7, 1.7]), WaveVector([0.1, 0.0])
r = np.array([0.2, 0.1])
total = lattice.lsumsw2d(2, 0, 1.3, kpar, a, r)  # l, m, k, kpar, a, r
# The sum does not depend on the Ewald split eta.
split = lattice.lsumsw2d(2, 0, 1.3, kpar, a, r, eta=0.6)
np.testing.assert_allclose(split, total, rtol=1e-12)
# A shift by the lattice vector R = (1.7, 0) multiplies it by exp(-i kpar . R).
shifted = lattice.lsumsw2d(2, 0, 1.3, kpar, a, r + [1.7, 0.0])
np.testing.assert_allclose(shifted, np.exp(-0.17j) * total, rtol=1e-12)

SumResult

SumResult = complex | np.ndarray[tuple[int, ...], np.dtype[np.complex128]]

Lattice-sum value: a complex scalar, or a complex128 array of the broadcast shape.

area

area(cell, *args, **kwargs)

Same as volume.

Signed volume (area, length) of cells whose rows are lattice vectors.

Cells have shape (..., d, d) with d = 1, 2 or 3; integer cells stay integer.

Mirrors treams.lattice.volume.

Differences from treams: also one-dimensional cells.

cube

cube(d: int, n: int) -> NDArray[np.int64]

All integer points in the cube [-n, n]^d, in lexicographic order.

Mirrors treams.lattice.cube.

Args

  • d: Space dimension 1, 2 or 3.
  • n: Nonnegative half side length of the cube.

Returns

int64 array of shape ((2 n + 1)**d, d).

cubeedge

cubeedge(d: int, n: int) -> NDArray[np.int64]

Integer points on the surface of the cube [-n, n]^d, in lexicographic order.

Mirrors treams.lattice.cubeedge. For n = 0 the surface is the origin alone.

Args

  • d: Space dimension 1, 2 or 3.
  • n: Nonnegative half side length of the cube.

Returns

int64 array of shape (points, d).

diffr_orders_circle

diffr_orders_circle(b: ArrayLike, rmax: float) -> NDArray[np.int64]

All diffraction orders within a circle of radius rmax.

Mirrors treams.lattice.diffr_orders_circle. Each order is followed by its opposite; the enumeration covers skew lattices and keeps the treams order on orthogonal cells.

Args

  • b: Reciprocal lattice vectors as the rows of a (2, 2) array.
  • rmax: Radius of the circle in reciprocal space.

Returns

int64 array of shape (orders, 2).

Differences from treams

A negative rmax gives an empty (0, 2) array; treams gives an empty one-dimensional array.

dsumcw

dsumcw(dim: int, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, i: ArrayLike, out: Any=None, **kwargs: Any) -> SumResult

Shell i of the direct sum D_m over a 1D or 2D lattice.

Mirrors treams.lattice.dsumcw. Calls dsumcw1d_shift or dsumcw2d. Shell i holds the lattice points whose integer coordinates have the largest magnitude i. In 1D at a shift r = s a / 2 on the axis, with s = 1 or -1, shell i holds n = s i and n = -s (i + 1) instead. The shells 0, 1, 2, ... add up to the sum, but slowly.

Args

  • dim: Lattice dimension, 1 or 2.
  • m: Order, |m| up to 128.
  • k: Wavenumber, real or complex, nonzero.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y).
  • i: Shell index, 0 or more.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The shell sum, complex128 with the broadcast shape of the arguments.

dsumcw1d

dsumcw1d(m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, i: ArrayLike, out: Any=None, **kwargs: Any) -> SumResult

Shell i of the direct sum D_m over a 1D lattice on the x axis.

Mirrors treams.lattice.dsumcw1d. a is the period, kpar the Bloch wavenumber along x and r the shift along x. Shell i holds the lattice points n a with |n| = i. At r = s a / 2, with s = 1 or -1, it holds n = s i and n = -s (i + 1) instead. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc.

dsumcw1d_shift

dsumcw1d_shift(m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, i: ArrayLike, out: Any=None, **kwargs: Any) -> SumResult

Shell i of the direct sum D_m over a 1D lattice on the x axis.

Mirrors treams.lattice.dsumcw1d_shift. a is the period, kpar the Bloch wavenumber along x and r the shift (x, y). Shell i holds the lattice points n a with |n| = i. At r = (s a / 2, 0), with s = 1 or -1, it holds n = s i and n = -s (i + 1) instead. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc.

dsumcw2d

dsumcw2d(m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, i: ArrayLike, out: Any=None, **kwargs: Any) -> SumResult

Shell i of the direct sum D_m over a 2D lattice in the plane z = 0.

Mirrors treams.lattice.dsumcw2d. The rows of a, shape (2, 2), are the lattice vectors; kpar and r have shape (2,). Shell i holds the lattice points whose integer coordinates have the largest magnitude i. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc.

dsumsw

dsumsw(dim: int, l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, i: ArrayLike, out: Any=None, **kwargs: Any) -> SumResult

Shell i of the direct sum D_lm over a 1D, 2D or 3D lattice.

Mirrors treams.lattice.dsumsw. Calls dsumsw1d_shift, dsumsw2d_shift or dsumsw3d. Shell i holds the lattice points whose integer coordinates have the largest magnitude i. In 1D at a shift r = s a / 2 on the axis, with s = 1 or -1, shell i holds n = s i and n = -s (i + 1) instead. The shells 0, 1, 2, ... add up to the sum, but slowly.

Args

  • dim: Lattice dimension, 1, 2 or 3.
  • l: Degree, 0 to 128.
  • m: Order, |m| <= l.
  • k: Wavenumber, real or complex, nonzero.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y, z).
  • i: Shell index, 0 or more.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The shell sum, complex128 with the broadcast shape of the arguments.

dsumsw1d

dsumsw1d(l, k, kpar, a, r, i, /, out=None, *, where=True)

Shell i of the direct sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. Shell i holds the lattice points whose integer coordinates in the basis a have the largest magnitude i; the shells 0, 1, 2, ... add up to the sum. The lattice lies on the z axis: a is the pitch, kpar the Bloch wavenumber and r the shift along z; m = 0.

Mirrors treams.lattice.dsumsw1d.

Differences from treams: degrees up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume.

dsumsw1d_shift

dsumsw1d_shift(l, m, k, kpar, a, r, i, /, out=None)

Shell i of the direct sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. Shell i holds the lattice points whose integer coordinates in the basis a have the largest magnitude i; the shells 0, 1, 2, ... add up to the sum. The lattice lies on the z axis: a is the pitch, kpar the Bloch wavenumber and r a shift (x, y, z).

Mirrors treams.lattice.dsumsw1d_shift.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume.

dsumsw2d

dsumsw2d(l, m, k, kpar, a, r, i, /, out=None)

Shell i of the direct sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. Shell i holds the lattice points whose integer coordinates in the basis a have the largest magnitude i; the shells 0, 1, 2, ... add up to the sum. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors, kpar has shape (2,) and r is a shift (x, y).

Mirrors treams.lattice.dsumsw2d.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume.

dsumsw2d_shift

dsumsw2d_shift(l, m, k, kpar, a, r, i, /, out=None)

Shell i of the direct sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. Shell i holds the lattice points whose integer coordinates in the basis a have the largest magnitude i; the shells 0, 1, 2, ... add up to the sum. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors, kpar has shape (2,) and r is a shift (x, y, z).

Mirrors treams.lattice.dsumsw2d_shift.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume.

dsumsw3d

dsumsw3d(l, m, k, kpar, a, r, i, /, out=None)

Shell i of the direct sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. Shell i holds the lattice points whose integer coordinates in the basis a have the largest magnitude i; the shells 0, 1, 2, ... add up to the sum. The rows of a, shape (3, 3), are the lattice vectors; kpar and r have shape (3,).

Mirrors treams.lattice.dsumsw3d.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume.

lsumcw

lsumcw(dim: int, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_m of cylindrical waves over a 1D or 2D lattice.

Mirrors treams.lattice.lsumcw. Calls lsumcw1d_shift or lsumcw2d.

Args

  • dim: Lattice dimension, 1 or 2.
  • m: Order, |m| up to 128.
  • k: Finite nonzero wavenumber with Im k >= 0.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y).
  • eta: Ewald split parameter; 0 selects it automatically.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The sum, complex128 with the broadcast shape of the arguments.

See the Accuracy section of treams_rs.lattice.

lsumcw1d

lsumcw1d(m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_m over a 1D lattice on the x axis.

Mirrors treams.lattice.lsumcw1d. a is the period or a Lattice, and kpar the Bloch wavenumber along x or a WaveVector. r is the shift along x. eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumcw1d_shift

lsumcw1d_shift(m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_m over a 1D lattice on the x axis.

Mirrors treams.lattice.lsumcw1d_shift. a is the period or a Lattice, and kpar the Bloch wavenumber along x or a WaveVector. r is the shift (x, y). eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumcw2d

lsumcw2d(m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_m over a 2D lattice in the plane z = 0.

Mirrors treams.lattice.lsumcw2d. The rows of a, shape (2, 2), are the lattice vectors; a may also be the two side lengths of a rectangular cell or a Lattice. kpar has shape (2,) or is a WaveVector. r is the shift (x, y). eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumsw

lsumsw(dim: int, l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_lm of spherical waves over a 1D, 2D or 3D lattice.

Mirrors treams.lattice.lsumsw. Calls lsumsw1d_shift, lsumsw2d_shift or lsumsw3d.

Args

  • dim: Lattice dimension, 1, 2 or 3.
  • l: Degree, 0 to 128.
  • m: Order, |m| <= l.
  • k: Finite nonzero wavenumber with Re k >= 0 and Im k >= 0.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y, z).
  • eta: Ewald split parameter; 0 selects it automatically.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The sum, complex128 with the broadcast shape of the arguments.

See the Accuracy section of treams_rs.lattice.

lsumsw1d

lsumsw1d(l: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_lm with m = 0 over a 1D lattice on the z axis.

Mirrors treams.lattice.lsumsw1d. a is the period or a Lattice, and kpar the Bloch wavenumber along z or a WaveVector. r is the shift along z. eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumsw1d_shift

lsumsw1d_shift(l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_lm over a 1D lattice on the z axis.

Mirrors treams.lattice.lsumsw1d_shift. a is the period or a Lattice, and kpar the Bloch wavenumber along z or a WaveVector. r is the shift (x, y, z). eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumsw2d

lsumsw2d(l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_lm over a 2D lattice in the plane z = 0.

Mirrors treams.lattice.lsumsw2d. The rows of a, shape (2, 2), are the lattice vectors; a may also be the two side lengths of a rectangular cell or a Lattice. kpar has shape (2,) or is a WaveVector. r is the shift (x, y) in the plane. eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumsw2d_shift

lsumsw2d_shift(l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_lm over a 2D lattice in the plane z = 0.

Mirrors treams.lattice.lsumsw2d_shift. The rows of a, shape (2, 2), are the lattice vectors; a may also be the two side lengths of a rectangular cell or a Lattice. kpar has shape (2,) or is a WaveVector. r is the shift (x, y, z). eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

lsumsw3d

lsumsw3d(l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Ewald sum D_lm over a 3D lattice.

Mirrors treams.lattice.lsumsw3d. The rows of a, shape (3, 3), are the lattice vectors; a may also be the three side lengths of a rectangular cell or a Lattice. kpar has shape (3,) or is a WaveVector. r is the shift (x, y, z). eta is the Ewald split parameter, and eta=0 selects it automatically. Arguments broadcast as for a NumPy ufunc; out and **kwargs go to the ufunc. See the Accuracy section of treams_rs.lattice.

realsumcw

realsumcw(dim: int, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Real-space part of the Ewald sum D_m over a 1D or 2D lattice.

Mirrors treams.lattice.realsumcw. Calls realsumcw1d_shift or realsumcw2d. Adding recsumcw at the same eta gives lsumcw.

Args

  • dim: Lattice dimension, 1 or 2.
  • m: Order, |m| up to 128.
  • k: Finite nonzero wavenumber with Im k >= 0.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y).
  • eta: Ewald split parameter; 0 selects it automatically.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The part, complex128 with the broadcast shape of the arguments.

See the Accuracy section of treams_rs.lattice.

realsumcw1d

realsumcw1d(m, k, kpar, a, r, eta, /, out=None, *, where=True)

The real-space part of the Ewald sum over the lattice points R of H_m(k |r + R|) exp(i m phi) exp(i kpar.R), where phi is the azimuth of -r - R, without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the x axis: a is the pitch, kpar the Bloch wavenumber and r the shift along x.

Mirrors treams.lattice.realsumcw1d.

Differences from treams: orders |m| up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumcw1d_shift

realsumcw1d_shift(m, k, kpar, a, r, eta, /, out=None)

The real-space part of the Ewald sum over the lattice points R of H_m(k |r + R|) exp(i m phi) exp(i kpar.R), where phi is the azimuth of -r - R, without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the x axis: a is the pitch, kpar the Bloch wavenumber and r a shift (x, y).

Mirrors treams.lattice.realsumcw1d_shift.

Differences from treams: orders |m| up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumcw2d

realsumcw2d(m, k, kpar, a, r, eta, /, out=None)

The real-space part of the Ewald sum over the lattice points R of H_m(k |r + R|) exp(i m phi) exp(i kpar.R), where phi is the azimuth of -r - R, without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors; kpar and r have shape (2,).

Mirrors treams.lattice.realsumcw2d.

Differences from treams: orders |m| up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumsw

realsumsw(dim: int, l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Real-space part of the Ewald sum D_lm over a 1D, 2D or 3D lattice.

Mirrors treams.lattice.realsumsw. Calls realsumsw1d_shift, realsumsw2d_shift or realsumsw3d. Adding recsumsw at the same eta gives lsumsw.

Args

  • dim: Lattice dimension, 1, 2 or 3.
  • l: Degree, 0 to 128.
  • m: Order, |m| <= l.
  • k: Finite nonzero wavenumber with Re k >= 0 and Im k >= 0.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y, z).
  • eta: Ewald split parameter; 0 selects it automatically.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The part, complex128 with the broadcast shape of the arguments.

See the Accuracy section of treams_rs.lattice.

realsumsw1d

realsumsw1d(l, k, kpar, a, r, eta, /, out=None, *, where=True)

The real-space part of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the z axis: a is the pitch, kpar the Bloch wavenumber and r the shift along z; m = 0.

Mirrors treams.lattice.realsumsw1d.

Differences from treams: degrees up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumsw1d_shift

realsumsw1d_shift(l, m, k, kpar, a, r, eta, /, out=None)

The real-space part of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the z axis: a is the pitch, kpar the Bloch wavenumber and r a shift (x, y, z).

Mirrors treams.lattice.realsumsw1d_shift.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumsw2d

realsumsw2d(l, m, k, kpar, a, r, eta, /, out=None)

The real-space part of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors, kpar has shape (2,) and r is a shift (x, y).

Mirrors treams.lattice.realsumsw2d.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumsw2d_shift

realsumsw2d_shift(l, m, k, kpar, a, r, eta, /, out=None)

The real-space part of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors, kpar has shape (2,) and r is a shift (x, y, z).

Mirrors treams.lattice.realsumsw2d_shift.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

realsumsw3d

realsumsw3d(l, m, k, kpar, a, r, eta, /, out=None)

The real-space part of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The rows of a, shape (3, 3), are the lattice vectors; kpar and r have shape (3,).

Mirrors treams.lattice.realsumsw3d.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError where the sum does not converge and where the split eta is too small for full accuracy.

reciprocal

reciprocal(cell, *args, **kwargs)

Reciprocal lattice vectors as rows, with a_i . b_j = 2 pi delta_ij.

Cells have shape (..., d, d) with d = 1, 2 or 3 and rows as lattice vectors.

Mirrors treams.lattice.reciprocal.

Differences from treams: also one-dimensional cells.

recsumcw

recsumcw(dim: int, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Reciprocal-space part of the Ewald sum D_m over a 1D or 2D lattice.

Mirrors treams.lattice.recsumcw. Calls recsumcw1d_shift or recsumcw2d. At r = 0 the part includes the correction for the dropped term at R = 0, as in treams.

Args

  • dim: Lattice dimension, 1 or 2.
  • m: Order, |m| up to 128.
  • k: Finite nonzero wavenumber with Im k >= 0.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y).
  • eta: Ewald split parameter; 0 selects it automatically.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The part, complex128 with the broadcast shape of the arguments.

See the Accuracy section of treams_rs.lattice.

recsumcw1d

recsumcw1d(m, k, kpar, a, r, eta, /, out=None, *, where=True)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of H_m(k |r + R|) exp(i m phi) exp(i kpar.R), where phi is the azimuth of -r - R, without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the x axis: a is the pitch, kpar the Bloch wavenumber and r the shift along x.

Mirrors treams.lattice.recsumcw1d.

Differences from treams: orders |m| up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumcw1d_shift

recsumcw1d_shift(m, k, kpar, a, r, eta, /, out=None)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of H_m(k |r + R|) exp(i m phi) exp(i kpar.R), where phi is the azimuth of -r - R, without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the x axis: a is the pitch, kpar the Bloch wavenumber and r a shift (x, y).

Mirrors treams.lattice.recsumcw1d_shift.

Differences from treams: orders |m| up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumcw2d

recsumcw2d(m, k, kpar, a, r, eta, /, out=None)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of H_m(k |r + R|) exp(i m phi) exp(i kpar.R), where phi is the azimuth of -r - R, without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors; kpar and r have shape (2,).

Mirrors treams.lattice.recsumcw2d.

Differences from treams: orders |m| up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumsw

recsumsw(dim: int, l: ArrayLike, m: ArrayLike, k: ArrayLike, kpar: ArrayLike, a: ArrayLike, r: ArrayLike, eta: ArrayLike=0, out: Any=None, **kwargs: Any) -> SumResult

Reciprocal-space part of the Ewald sum D_lm over a 1D, 2D or 3D lattice.

Mirrors treams.lattice.recsumsw. Calls recsumsw1d_shift, recsumsw2d_shift or recsumsw3d. At r = 0 the part includes the correction for the dropped term at R = 0, as in treams.

Args

  • dim: Lattice dimension, 1, 2 or 3.
  • l: Degree, 0 to 128.
  • m: Order, |m| <= l.
  • k: Finite nonzero wavenumber with Re k >= 0 and Im k >= 0.
  • kpar: Bloch vector: a number in 1D, dim components otherwise, or a WaveVector.
  • a: Lattice vectors as rows: the period in 1D, a (dim, dim) array or the side lengths of a rectangular cell, or a Lattice.
  • r: Shift (x, y, z).
  • eta: Ewald split parameter; 0 selects it automatically.
  • out: Array for the result, as for a NumPy ufunc.
  • **kwargs: Further ufunc keywords.

Returns

The part, complex128 with the broadcast shape of the arguments.

See the Accuracy section of treams_rs.lattice.

recsumsw1d

recsumsw1d(l, k, kpar, a, r, eta, /, out=None, *, where=True)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the z axis: a is the pitch, kpar the Bloch wavenumber and r the shift along z; m = 0.

Mirrors treams.lattice.recsumsw1d.

Differences from treams: degrees up to 128; ValueError for non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumsw1d_shift

recsumsw1d_shift(l, m, k, kpar, a, r, eta, /, out=None)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies on the z axis: a is the pitch, kpar the Bloch wavenumber and r a shift (x, y, z).

Mirrors treams.lattice.recsumsw1d_shift.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumsw2d

recsumsw2d(l, m, k, kpar, a, r, eta, /, out=None)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors, kpar has shape (2,) and r is a shift (x, y).

Mirrors treams.lattice.recsumsw2d.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumsw2d_shift

recsumsw2d_shift(l, m, k, kpar, a, r, eta, /, out=None)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The lattice lies in the xy plane: the rows of a, shape (2, 2), are the lattice vectors, kpar has shape (2,) and r is a shift (x, y, z).

Mirrors treams.lattice.recsumsw2d_shift.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

recsumsw3d

recsumsw3d(l, m, k, kpar, a, r, eta, /, out=None)

The reciprocal-space part, with the self correction, of the Ewald sum over the lattice points R of h_l(k |r + R|) Y_lm(-r - R) exp(i kpar.R), without the term at r + R = 0. eta sets how the sum divides into a real-space and a reciprocal-space part (the Ewald split); eta = 0 picks it automatically. The rows of a, shape (3, 3), are the lattice vectors; kpar and r have shape (3,).

Mirrors treams.lattice.recsumsw3d.

Differences from treams: degrees up to 128; ValueError for |m| > l, non-finite input, k = 0 and a cell of zero volume. It also raises ValueError at a diffraction threshold k = |kpar + G|, with G a reciprocal lattice vector, where the sum does not converge and where the split eta is too small for full accuracy.

volume

volume(cell, *args, **kwargs)

Signed volume (area, length) of cells whose rows are lattice vectors.

Cells have shape (..., d, d) with d = 1, 2 or 3; integer cells stay integer.

Mirrors treams.lattice.volume.

Differences from treams: also one-dimensional cells.