pulsesuite.PSTD3D.usefulsubs

Useful subroutines for quantum wire simulations.

This module provides utility functions for array manipulation and derivative calculations using FFT methods.

Author: Rahul R. Sah

Bug fixes:

Fortran cshift(array, -1): shifts right (wraps left to right) NumPy np.roll(array, 1): shifts left (wraps right to left)

Attributes

ii

pi

twopi

small

kB

Functions

fflip_dp(f)

Flip a real array.

fflip_dpc(f)

Flip a complex array.

dfdy1D(f, qy)

Calculate derivative in y direction for 1D array using FFT.

dfdy2D(f, qy)

Calculate derivative in y direction for 2D array using FFT.

dfdx1D(f, qx)

Calculate derivative in x direction for 1D array using FFT.

dfdx2D(f, qx)

Calculate derivative in x direction for 2D array using FFT.

dfdy1D_q(f, qy)

Calculate derivative in y direction for 1D array in q-space.

dfdy2D_q(f, qy)

Calculate derivative in y direction for 2D array in q-space.

dfdx1D_q(f, qx)

Calculate derivative in x direction for 1D array in q-space.

dfdx2D_q(f, qx)

Calculate derivative in x direction for 2D array in q-space.

GFFT_1D(f, dx)

Gaussian FFT for 1D array.

GIFFT_1D(f, dq)

Gaussian IFFT for 1D array.

GFFT_2D(f, dx, dy)

Gaussian FFT for 2D array.

GIFFT_2D(f, dqx, dqy)

Gaussian IFFT for 2D array.

test2Dfrom1D(x, y)

Test function for 2D array construction from 1D arrays.

testconv(y)

Test function for convolution operations.

ApplyABC(Field, abc)

Apply absorbing boundary conditions (ABC) to a field.

dEdx(E, dx)

Calculate derivative of E field in x direction.

dEdy(E, dy)

Calculate derivative of E field in y direction.

dHdx(H, dx)

Calculate derivative of H field in x direction.

dHdy(H, dy)

Calculate derivative of H field in y direction.

testing_conv(Ex, y, q)

Test function for convolution operations.

testing_fftc(Ex, y, q)

Test function for FFTc operations.

print2file(x, y, filename)

Print arrays to file.

FT(y, x, q)

Fourier Transform using direct summation.

IFT(y, x, q)

Inverse Fourier Transform using direct summation.

Flip(x)

Flip a complex array.

GetArray0Index(x)

Get index of array element closest to zero.

GaussDelta(a, b)

Gaussian delta function.

delta(x[, dky])

Dirac delta function.

kdel(x)

Kronecker delta function.

delt(x)

Delta function variant.

sgn(x)

Sign function.

sgn2(x)

Sign function for arrays.

TotalEnergy(n, E)

Calculate total energy.

AvgEnergy(n, E)

Calculate average energy.

Temperature(n, E)

Calculate temperature from energy distribution.

Lrtz(a, b)

Lorentzian function.

theta(x)

Heaviside step function.

softtheta(x, g)

Soft Heaviside step function.

rad(degrees)

Convert degrees to radians.

RotateField3D(theta, Ex, Ey, Ez)

Rotate 3D field by angle theta about y-axis.

RotateField(theta, Ex, Ey)

Rotate 2D field by angle theta.

ShiftField(Lx, Ly, dx, dy, Ex, Ey)

Shift field by specified distances.

RotateShiftEField(theta, qx, qy, Ex, Ey[, FFTC, IFFTC])

Rotate and shift E field in momentum space.

cik01(z)

Compute modified Bessel functions I0(z), I1(z), K0(z) and K1(z) for complex argument.

K03(x)

Modified Bessel function K0 for real argument.

locator(x, x0)

Find index in sorted array where value should be inserted.

WriteIT2D(V, file)

Write 2D array to file.

ReadIT2D(V, file)

Read 2D array from file.

WriteIT1D(V, file)

Write 1D array to file.

ReadIT1D(V, file)

Read 1D array from file.

EAtX(f, x, x0)

Linear interpolation of 2D complex array at specified x position.

EAtXYZ(f, x, y, z, x0, y0, z0)

Trilinear interpolation of 3D complex field at point (x0, y0, z0).

printIT(Dx, z, n, file)

Print field to file with index number.

printITR(Dx, z, n, file)

Print real field to file with index number.

printIT2D(Dx, z, n, file)

Print 2D complex field to file with index number.

gaussian(x, x0)

Gaussian function.

convolve(x, h)

Convolution of two complex arrays.

FFTG(F)

FFT with Gaussian normalization.

iFFTG(F)

IFFT with Gaussian normalization.

ReadIt(V, file)

Read array from file (interface-style wrapper).

WriteIt(V, file)

Write array to file (interface-style wrapper).

dfdy(f, qy)

Calculate derivative in y direction (interface-style wrapper).

dfdx(f, qx)

Calculate derivative in x direction (interface-style wrapper).

dfdy_q(f, qy)

Calculate derivative in y direction in q-space (interface-style wrapper).

dfdx_q(f, qx)

Calculate derivative in x direction in q-space (interface-style wrapper).

GFFT(f, dx[, dy])

Gaussian FFT (interface-style wrapper).

GIFFT(f, dq[, dqy])

Gaussian IFFT (interface-style wrapper).

fflip(f)

Flip array (interface-style wrapper).

Module Contents

pulsesuite.PSTD3D.usefulsubs.ii = 1j
pulsesuite.PSTD3D.usefulsubs.pi
pulsesuite.PSTD3D.usefulsubs.twopi
pulsesuite.PSTD3D.usefulsubs.small = 1e-100
pulsesuite.PSTD3D.usefulsubs.kB = 1.380649e-23
pulsesuite.PSTD3D.usefulsubs.fflip_dp(f)

Flip a real array.

Reverses the order of elements in a real array.

Parameters:

f (ndarray) – Input real array, 1D array

Returns:

Flipped array, 1D array

Return type:

ndarray

pulsesuite.PSTD3D.usefulsubs.fflip_dpc(f)

Flip a complex array.

Reverses the order of elements in a complex array.

Parameters:

f (ndarray) – Input complex array, 1D array

Returns:

Flipped array, 1D array

Return type:

ndarray

pulsesuite.PSTD3D.usefulsubs.dfdy1D(f, qy)

Calculate derivative in y direction for 1D array using FFT.

Computes the derivative df/dy using FFT method: df/dy = IFFT(ii * qy * FFT(f))

Parameters:

  • f (ndarray) – Input function (complex), 1D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

Returns:

Derivative df/dy (complex), 1D array

Return type:

ndarray

Notes

Uses pyfftw FFT functions for computation. Returns zero array if qy has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdy2D(f, qy)

Calculate derivative in y direction for 2D array using FFT.

Computes the derivative df/dy for each row of a 2D array using the 1D derivative function.

Parameters:

  • f (ndarray) – Input function (complex), 2D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

Returns:

Derivative df/dy (complex), 2D array with same shape as f

Return type:

ndarray

Notes

This function calls dfdy1D for each row of the 2D array. Returns zero array if qy has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdx1D(f, qx)

Calculate derivative in x direction for 1D array using FFT.

Computes the derivative df/dx using FFT method: df/dx = IFFT(ii * qx * FFT(f))

Parameters:

  • f (ndarray) – Input function (complex), 1D array

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

Returns:

Derivative df/dx (complex), 1D array

Return type:

ndarray

Notes

Uses pyfftw FFT functions for computation. Returns zero array if qx has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdx2D(f, qx)

Calculate derivative in x direction for 2D array using FFT.

Computes the derivative df/dx for each column of a 2D array using the 1D derivative function.

Parameters:

  • f (ndarray) – Input function (complex), 2D array

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

Returns:

Derivative df/dx (complex), 2D array with same shape as f

Return type:

ndarray

Notes

This function calls dfdy1D for each column of the 2D array. Returns zero array if qx has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdy1D_q(f, qy)

Calculate derivative in y direction for 1D array in q-space.

Computes the derivative df/dy in q-space (Fourier space): df/dy = f * (ii * qy)

Parameters:

  • f (ndarray) – Input function in q-space (complex), 1D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

Returns:

Derivative df/dy in q-space (complex), 1D array

Return type:

ndarray

Notes

This is the q-space version that operates directly on Fourier-transformed arrays without requiring FFT/IFFT calls. Returns zero array if qy has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdy2D_q(f, qy)

Calculate derivative in y direction for 2D array in q-space.

Computes the derivative df/dy in q-space (Fourier space) for each element: df/dy(i,j) = f(i,j) * (ii * qy(j))

Parameters:

  • f (ndarray) – Input function in q-space (complex), 2D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

Returns:

Derivative df/dy in q-space (complex), 2D array with same shape as f

Return type:

ndarray

Notes

This is the q-space version that operates directly on Fourier-transformed arrays without requiring FFT/IFFT calls. Returns zero array if qy has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdx1D_q(f, qx)

Calculate derivative in x direction for 1D array in q-space.

Computes the derivative df/dx in q-space (Fourier space): df/dx = f * (ii * qx)

Parameters:

  • f (ndarray) – Input function in q-space (complex), 1D array

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

Returns:

Derivative df/dx in q-space (complex), 1D array

Return type:

ndarray

Notes

This is the q-space version that operates directly on Fourier-transformed arrays without requiring FFT/IFFT calls. Returns zero array if qx has only one element.

pulsesuite.PSTD3D.usefulsubs.dfdx2D_q(f, qx)

Calculate derivative in x direction for 2D array in q-space.

Computes the derivative df/dx in q-space (Fourier space) for each element: df/dx(i,j) = f(i,j) * (ii * qx(i))

Parameters:

  • f (ndarray) – Input function in q-space (complex), 2D array

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

Returns:

Derivative df/dx in q-space (complex), 2D array with same shape as f

Return type:

ndarray

Notes

This is the q-space version that operates directly on Fourier-transformed arrays without requiring FFT/IFFT calls. Returns zero array if qx has only one element.

pulsesuite.PSTD3D.usefulsubs.GFFT_1D(f, dx)

Gaussian FFT for 1D array.

Performs FFT and scales by dx/sqrt(2*pi) for Gaussian normalization.

Parameters:

  • f (ndarray) – Input function (complex), modified in-place, 1D array

  • dx (float) – Spatial step size (m)

Returns:

f array is modified in-place.

Return type:

None

Notes

Uses pyfftw FFT function for computation. The function performs: FFT(f) then f = f * dx / sqrt(2*pi)

pulsesuite.PSTD3D.usefulsubs.GIFFT_1D(f, dq)

Gaussian IFFT for 1D array.

Performs IFFT and scales by dq/sqrt(2*pi) * N for Gaussian normalization.

Parameters:

  • f (ndarray) – Input function (complex), modified in-place, 1D array

  • dq (float) – Momentum step size (1/m)

Returns:

f array is modified in-place.

Return type:

None

Notes

Uses pyfftw IFFT function for computation. The function performs: IFFT(f) then f = f * dq / sqrt(2*pi) * N

pulsesuite.PSTD3D.usefulsubs.GFFT_2D(f, dx, dy)

Gaussian FFT for 2D array.

Performs FFT and scales by dx*dy/(2*pi) for Gaussian normalization.

Parameters:

  • f (ndarray) – Input function (complex), modified in-place, 2D array

  • dx (float) – Spatial step size in x direction (m)

  • dy (float) – Spatial step size in y direction (m)

Returns:

f array is modified in-place.

Return type:

None

Notes

Uses pyfftw FFT function for computation. The function performs: FFT(f) then f = f * dx * dy / (2*pi)

pulsesuite.PSTD3D.usefulsubs.GIFFT_2D(f, dqx, dqy)

Gaussian IFFT for 2D array.

Performs IFFT and scales by dqx*dqy/(2*pi) * Nx * Ny for Gaussian normalization.

Parameters:

  • f (ndarray) – Input function (complex), modified in-place, 2D array

  • dqx (float) – Momentum step size in x direction (1/m)

  • dqy (float) – Momentum step size in y direction (1/m)

Returns:

f array is modified in-place.

Return type:

None

Notes

Uses pyfftw IFFT function for computation. The function performs: IFFT(f) then f = f * dqx * dqy / (2*pi) * Nx * Ny

pulsesuite.PSTD3D.usefulsubs.test2Dfrom1D(x, y)

Test function for 2D array construction from 1D arrays.

Creates 2D Gaussian functions from 1D arrays and tests FFT operations.

Parameters:

  • x (ndarray) – X coordinates (m), 1D array

  • y (ndarray) – Y coordinates (m), 1D array

Notes

This is a test function. The function prints the sum of squared absolute values and stops execution.

pulsesuite.PSTD3D.usefulsubs.testconv(y)

Test function for convolution operations.

Tests convolution of two Gaussian functions using FFT methods.

Parameters:

y (ndarray) – Y coordinates (m), 1D array

Notes

This is a test function that uses nyquist_1D and convolve functions which need to be defined elsewhere. The function prints results and stops.

pulsesuite.PSTD3D.usefulsubs.ApplyABC(Field, abc)

Apply absorbing boundary conditions (ABC) to a field.

Transforms field to real space, multiplies by ABC coefficients, and transforms back to Fourier space.

Parameters:

  • Field (ndarray) – Field array (complex), modified in-place, 2D array

  • abc (ndarray) – Absorbing boundary condition coefficients (real), 2D array

Returns:

Field array is modified in-place.

Return type:

None

Notes

The function performs: IFFT(Field), Field = Field * abc, FFT(Field)

pulsesuite.PSTD3D.usefulsubs.dEdx(E, dx)

Calculate derivative of E field in x direction.

Computes forward difference derivative: dE/dx = (E(i+1,j) - E(i,j)) / dx

Parameters:

  • E (ndarray) – Electric field (complex), 2D array

  • dx (float) – Spatial step size in x direction (m)

Returns:

Derivative dE/dx (complex), 2D array with same shape as E

Return type:

ndarray

Notes

Returns zero array if E has only one row. Uses forward difference scheme with shifted indices.

pulsesuite.PSTD3D.usefulsubs.dEdy(E, dy)

Calculate derivative of E field in y direction.

Computes forward difference derivative: dE/dy = (E(i,j+1) - E(i,j)) / dy

Parameters:

  • E (ndarray) – Electric field (complex), 2D array

  • dy (float) – Spatial step size in y direction (m)

Returns:

Derivative dE/dy (complex), 2D array with same shape as E

Return type:

ndarray

Notes

Returns zero array if E has only one column. Uses forward difference scheme with shifted indices.

pulsesuite.PSTD3D.usefulsubs.dHdx(H, dx)

Calculate derivative of H field in x direction.

Computes backward difference derivative: dH/dx = (H(i,j) - H(i-1,j)) / dx

Parameters:

  • H (ndarray) – Magnetic field (complex), 2D array

  • dx (float) – Spatial step size in x direction (m)

Returns:

Derivative dH/dx (complex), 2D array with same shape as H

Return type:

ndarray

Notes

Returns zero array if H has only one row. Uses backward difference scheme with shifted indices.

pulsesuite.PSTD3D.usefulsubs.dHdy(H, dy)

Calculate derivative of H field in y direction.

Computes backward difference derivative: dH/dy = (H(i,j) - H(i,j-1)) / dy

Parameters:

  • H (ndarray) – Magnetic field (complex), 2D array

  • dy (float) – Spatial step size in y direction (m)

Returns:

Derivative dH/dy (complex), 2D array with same shape as H

Return type:

ndarray

Notes

Returns zero array if H has only one column. Uses backward difference scheme with shifted indices.

pulsesuite.PSTD3D.usefulsubs.testing_conv(Ex, y, q)

Test function for convolution operations.

Tests FFT/IFFT operations and normalization for convolution.

Parameters:

  • Ex (ndarray) – Field array (complex), modified in-place, 1D array

  • y (ndarray) – Spatial coordinates (m), 1D array

  • q (ndarray) – Momentum coordinates (1/m), 1D array

Notes

This is a test function that uses module variables yw, dy, dq, Ny and functions FFTc, IFFTc which need to be defined elsewhere. The function prints results for testing purposes.

pulsesuite.PSTD3D.usefulsubs.testing_fftc(Ex, y, q)

Test function for FFTc operations.

Tests FFTc function with normalization.

Parameters:

  • Ex (ndarray) – Field array (complex), modified in-place, 1D array

  • y (ndarray) – Spatial coordinates (m), 1D array

  • q (ndarray) – Momentum coordinates (1/m), 1D array

Notes

This is a test function that uses module variables dy and function FFTc which need to be defined elsewhere. The function prints results.

pulsesuite.PSTD3D.usefulsubs.print2file(x, y, filename)

Print arrays to file.

Writes x, y arrays and index to a file.

Parameters:

  • x (ndarray) – First array (real), 1D array

  • y (ndarray) – Second array (real), 1D array

  • filename (str) – Output filename

Return type:

None

Notes

The function writes: x(i), y(i), i for each element.

pulsesuite.PSTD3D.usefulsubs.FT(y, x, q)

Fourier Transform using direct summation.

Computes FT: Y(q) = (1/N) * sum(y(x) * exp(ii*x*q))

Parameters:

  • y (ndarray) – Input function (complex), modified in-place, 1D array

  • x (ndarray) – Spatial coordinates (m), 1D array

  • q (ndarray) – Momentum coordinates (1/m), 1D array

Returns:

y array is modified in-place with transformed values.

Return type:

None

Notes

Uses direct summation method for Fourier transform. The result is normalized by N (length of arrays).

pulsesuite.PSTD3D.usefulsubs.IFT(y, x, q)

Inverse Fourier Transform using direct summation.

Computes IFT: Y(x) = sum(y(q) * exp(-ii*x*q))

Parameters:

  • y (ndarray) – Input function in q-space (complex), modified in-place, 1D array

  • x (ndarray) – Spatial coordinates (m), 1D array

  • q (ndarray) – Momentum coordinates (1/m), 1D array

Returns:

y array is modified in-place with transformed values.

Return type:

None

Notes

Uses direct summation method for inverse Fourier transform. No normalization factor is applied.

pulsesuite.PSTD3D.usefulsubs.Flip(x)

Flip a complex array.

Reverses the order of elements in a complex array.

Parameters:

x (ndarray) – Input complex array, 1D array

Returns:

Flipped array, 1D array

Return type:

ndarray

Notes

The function performs: Flip[i] = x[N-i] for i=0 to N-1

pulsesuite.PSTD3D.usefulsubs.GetArray0Index(x)

Get index of array element closest to zero.

Finds the index where the array value is closest to zero by rounding and checking for zero.

Parameters:

x (ndarray) – Input array (real), 1D array

Returns:

Index (1-based in Fortran, 0-based in Python) where value is closest to zero

Return type:

int

Notes

The function rounds array values and finds the first index where the rounded value is zero. Returns error message if not found.

pulsesuite.PSTD3D.usefulsubs.GaussDelta(a, b)

Gaussian delta function.

Computes normalized Gaussian function: (1/sqrt(pi)/b) * exp(-(a/b)^2)

Parameters:

  • a (float or ndarray) – Input value(s)

  • b (float or ndarray) – Width parameter

Returns:

Gaussian delta function value(s)

Return type:

float or ndarray

Notes

This is an elemental function that works with both scalars and arrays.

pulsesuite.PSTD3D.usefulsubs.delta(x, dky=None)

Dirac delta function.

Returns 1 if x/dky rounds to zero, otherwise 0.

Parameters:

  • x (float) – Input value

  • dky (float, optional) – Step size for delta function. If None, uses a default small value.

Returns:

1 if nint(x/dky) == 0, else 0

Return type:

int

Notes

Note: dky is a module variable in Fortran. Pass it as parameter if needed.

pulsesuite.PSTD3D.usefulsubs.kdel(x)

Kronecker delta function.

Returns 1 if x == 0, otherwise 0.

Parameters:

x (int) – Input integer value

Returns:

1 if x == 0, else 0

Return type:

int

pulsesuite.PSTD3D.usefulsubs.delt(x)

Delta function variant.

Computes: 1 - abs(x) / (abs(x) + 1e-100)

Parameters:

x (int) – Input integer value

Returns:

Delta function value

Return type:

float

pulsesuite.PSTD3D.usefulsubs.sgn(x)

Sign function.

Returns the sign of a number: -1 if x < 0, +1 if x >= 0.

Parameters:

x (float) – Input value

Returns:

-1 if x < 0, +1 if x >= 0

Return type:

int

pulsesuite.PSTD3D.usefulsubs.sgn2(x)

Sign function for arrays.

Applies sign function element-wise to an array.

Parameters:

x (ndarray) – Input array (real), 1D array

Returns:

Array of signs (-1 or +1), 1D array of integers

Return type:

ndarray

pulsesuite.PSTD3D.usefulsubs.TotalEnergy(n, E)

Calculate total energy.

Computes total energy as real part of sum(n * E).

Parameters:

  • n (ndarray) – Occupation numbers (complex), 1D array

  • E (ndarray) – Energy values (real), 1D array

Returns:

Total energy

Return type:

float

pulsesuite.PSTD3D.usefulsubs.AvgEnergy(n, E)

Calculate average energy.

Computes average energy as real(sum(n*E) / (sum(n) + small)).

Parameters:

  • n (ndarray) – Occupation numbers (complex), 1D array

  • E (ndarray) – Energy values (real), 1D array

Returns:

Average energy

Return type:

float

Notes

Uses small constant to avoid division by zero.

pulsesuite.PSTD3D.usefulsubs.Temperature(n, E)

Calculate temperature from energy distribution.

Computes temperature as 2 * AvgEnergy(n, E) / kB.

Parameters:

  • n (ndarray) – Occupation numbers (complex), 1D array

  • E (ndarray) – Energy values (real), 1D array

Returns:

Temperature (K)

Return type:

float

Notes

Uses Boltzmann constant kB for temperature calculation.

pulsesuite.PSTD3D.usefulsubs.Lrtz(a, b)

Lorentzian function.

Computes normalized Lorentzian: (b/pi) / (a^2 + b^2)

Parameters:

  • a (float or ndarray) – Input value(s)

  • b (float or ndarray) – Width parameter

Returns:

Lorentzian function value(s)

Return type:

float or ndarray

Notes

This is an elemental function that works with both scalars and arrays.

pulsesuite.PSTD3D.usefulsubs.theta(x)

Heaviside step function.

Computes step function: (abs(x) + x) / 2 / (abs(x) + small)

Parameters:

x (float or ndarray) – Input value(s)

Returns:

Step function value(s): 0 if x < 0, 1 if x > 0

Return type:

float or ndarray

Notes

This is an elemental function that works with both scalars and arrays. Uses small constant to avoid division by zero at x = 0.

pulsesuite.PSTD3D.usefulsubs.softtheta(x, g)

Soft Heaviside step function.

Computes smooth step function: 0.5 * (1.0 + 2.0/pi * atan(x/g))

Parameters:

  • x (float or ndarray) – Input value(s)

  • g (float or ndarray) – Smoothness parameter

Returns:

Soft step function value(s)

Return type:

float or ndarray

Notes

This is an elemental function that works with both scalars and arrays. Provides a smooth transition instead of a sharp step.

pulsesuite.PSTD3D.usefulsubs.rad(degrees)

Convert degrees to radians.

Parameters:

degrees (float or ndarray) – Angle in degrees

Returns:

Angle in radians

Return type:

float or ndarray

Notes

This is an elemental function that works with both scalars and arrays.

pulsesuite.PSTD3D.usefulsubs.RotateField3D(theta, Ex, Ey, Ez)

Rotate 3D field by angle theta about y-axis.

Performs right-handed rotation about y-axis using rotation matrix.

Parameters:

  • theta (float) – Rotation angle (radians)

  • Ex (ndarray) – X component of field (complex), modified in-place, 3D array

  • Ey (ndarray) – Y component of field (complex), modified in-place, 3D array

  • Ez (ndarray) – Z component of field (complex), modified in-place, 3D array

Returns:

Ex, Ey, Ez arrays are modified in-place.

Return type:

None

Notes

Rotation matrix for rotation about y-axis: R = [[cos(theta), 0, sin(theta)],

[0, 1, 0 ], [-sin(theta), 0, cos(theta)]]

pulsesuite.PSTD3D.usefulsubs.RotateField(theta, Ex, Ey)

Rotate 2D field by angle theta.

Performs rotation in 2D plane using rotation matrix.

Parameters:

  • theta (float) – Rotation angle (radians)

  • Ex (ndarray) – X component of field (complex), modified in-place, 2D array

  • Ey (ndarray) – Y component of field (complex), modified in-place, 2D array

Returns:

Ex, Ey arrays are modified in-place.

Return type:

None

Notes

Rotation matrix: R = [[cos(theta), -sin(theta)],

[sin(theta), cos(theta)]]

pulsesuite.PSTD3D.usefulsubs.ShiftField(Lx, Ly, dx, dy, Ex, Ey)

Shift field by specified distances.

Shifts field arrays by integer number of grid points in x and y directions.

Parameters:

  • Lx (float) – Shift distance in x direction (m)

  • Ly (float) – Shift distance in y direction (m)

  • dx (float) – Grid spacing in x direction (m)

  • dy (float) – Grid spacing in y direction (m)

  • Ex (ndarray) – X component of field (complex), modified in-place, 2D array

  • Ey (ndarray) – Y component of field (complex), modified in-place, 2D array

Returns:

Ex, Ey arrays are modified in-place.

Return type:

None

Notes

Uses circular shift (cshift) to shift arrays by nx and ny grid points.

pulsesuite.PSTD3D.usefulsubs.RotateShiftEField(theta, qx, qy, Ex, Ey, FFTC=None, IFFTC=None)

Rotate and shift E field in momentum space.

Transforms field to momentum space, calculates center of mass, shifts by rotation angle, and transforms back.

Parameters:

  • theta (float) – Rotation angle (radians)

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

  • Ex (ndarray) – X component of field (complex), modified in-place, 2D array

  • Ey (ndarray) – Y component of field (complex), modified in-place, 2D array

  • FFTC (callable, optional) – Forward FFT function. If None, uses pyfftw.

  • IFFTC (callable, optional) – Inverse FFT function. If None, uses pyfftw.

Returns:

Ex, Ey arrays are modified in-place.

Return type:

None

Notes

This function uses FFTC and IFFTC which need to be defined. Also uses module variables: dumb, qx0, qy0, q0x, q0y. These should be passed as parameters or defined as module variables.

pulsesuite.PSTD3D.usefulsubs.cik01(z)

Compute modified Bessel functions I0(z), I1(z), K0(z) and K1(z) for complex argument.

This procedure computes the modified Bessel functions I0(z), I1(z), K0(z), K1(z), and their derivatives for a complex argument.

Parameters:

z (complex) – The complex argument

Returns:

(cbi0, cdi0, cbi1, cdi1, cbk0, cdk0, cbk1, cdk1) Values of I0(z), I0’(z), I1(z), I1’(z), K0(z), K0’(z), K1(z), K1’(z)

Return type:

tuple

Notes

This routine is copyrighted by Shanjie Zhang and Jianming Jin. Reference: Shanjie Zhang, Jianming Jin, Computation of Special Functions, Wiley, 1996, ISBN: 0-471-11963-6, LC: QA351.C45.

pulsesuite.PSTD3D.usefulsubs.K03(x)

Modified Bessel function K0 for real argument.

Computes K0(x) using the complex Bessel function routine.

Parameters:

x (float) – Real argument

Returns:

Value of K0(x), or 0.0 if x > 100

Return type:

float

Notes

Returns 0.0 for large arguments (x > 100) to avoid overflow.

pulsesuite.PSTD3D.usefulsubs.locator(x, x0)

Find index in sorted array where value should be inserted.

Finds the index i such that x[i] <= x0 < x[i+1] (0-based indexing).

Parameters:

  • x (ndarray) – Sorted array (real), 1D array

  • x0 (float) – Value to locate

Returns:

Index i such that x[i] <= x0 < x[i+1] (0-based)

Return type:

int

Notes

Uses binary search to find the insertion point. Returns 0 if x0 < x[0], and len(x)-2 if x0 >= x[-1].

pulsesuite.PSTD3D.usefulsubs.WriteIT2D(V, file)

Write 2D array to file.

Writes a 2D real array to a file in the ‘dataQW’ directory.

Parameters:

  • V (ndarray) – Array to write (real), 2D array

  • file (str) – Base filename (without extension)

Return type:

None

Notes

The file is written to ‘dataQW/{file}.dat’. Each element is written on a separate line.

pulsesuite.PSTD3D.usefulsubs.ReadIT2D(V, file)

Read 2D array from file.

Reads a 2D real array from a file in the ‘dataQW’ directory.

Parameters:

  • V (ndarray) – Array to read into (real), modified in-place, 2D array

  • file (str) – Base filename (without extension)

Returns:

V array is modified in-place.

Return type:

None

Notes

The file is read from ‘dataQW/{file}.dat’. The array shape must match the file contents.

pulsesuite.PSTD3D.usefulsubs.WriteIT1D(V, file)

Write 1D array to file.

Writes a 1D real array to a file in the ‘dataQW’ directory.

Parameters:

  • V (ndarray) – Array to write (real), 1D array

  • file (str) – Base filename (without extension)

Return type:

None

Notes

The file is written to ‘dataQW/{file}.dat’. Each element is written on a separate line.

pulsesuite.PSTD3D.usefulsubs.ReadIT1D(V, file)

Read 1D array from file.

Reads a 1D real array from a file in the ‘dataQW’ directory.

Parameters:

  • V (ndarray) – Array to read into (real), modified in-place, 1D array

  • file (str) – Base filename (without extension)

Returns:

V array is modified in-place.

Return type:

None

Notes

The file is read from ‘dataQW/{file}.dat’. The array length must match the file contents.

pulsesuite.PSTD3D.usefulsubs.EAtX(f, x, x0)

Linear interpolation of 2D complex array at specified x position.

Computes a linear interpolation of a complex 2D array at a specified x position. The interpolation is performed along the first dimension.

Parameters:

  • f (ndarray) – 2D array to be interpolated (complex), 2D array

  • x (ndarray) – 1D position array corresponding to first dimension of f (real), 1D array

  • x0 (float) – Position at which f is to be interpolated

Returns:

Interpolated values (complex), 1D array of length f.shape[1]

Return type:

ndarray

Notes

Returns f[0, :] if x has only one element. Returns zero array if x0 is outside the valid range.

pulsesuite.PSTD3D.usefulsubs.EAtXYZ(f, x, y, z, x0, y0, z0)

Trilinear interpolation of 3D complex field at point (x0, y0, z0).

Computes trilinear interpolation of a complex 3D field at a specified point.

Parameters:

  • f (ndarray) – 3D field array (complex), 3D array

  • x (ndarray) – 1D array of grid coordinates along x axis (real), 1D array

  • y (ndarray) – 1D array of grid coordinates along y axis (real), 1D array

  • z (ndarray) – 1D array of grid coordinates along z axis (real), 1D array

  • x0 (float) – Query coordinate in x direction

  • y0 (float) – Query coordinate in y direction

  • z0 (float) – Query coordinate in z direction

Returns:

Interpolated field value at (x0, y0, z0)

Return type:

complex

Notes

Uses trilinear interpolation with weights computed for each axis. Handles degenerate cases where arrays have only one element.

pulsesuite.PSTD3D.usefulsubs.printIT(Dx, z, n, file)

Print field to file with index number.

Writes a complex 1D field array to a file with index number in filename.

Parameters:

  • Dx (ndarray) – Field array (complex), 1D array

  • z (ndarray) – Spatial coordinates (real), 1D array

  • n (int) – Index number for filename

  • file (str) – Base filename (without extension and index)

Return type:

None

Notes

The file is written to ‘dataQW/{file}{n:06d}.dat’. Each line contains: z(i), real(Dx(i)), imag(Dx(i))

pulsesuite.PSTD3D.usefulsubs.printITR(Dx, z, n, file)

Print real field to file with index number.

Writes a real 1D field array to a file with index number in filename.

Parameters:

  • Dx (ndarray) – Field array (real), 1D array

  • z (ndarray) – Spatial coordinates (real), 1D array

  • n (int) – Index number for filename

  • file (str) – Base filename (without extension and index)

Return type:

None

Notes

The file is written to ‘dataQW/{file}{n:06d}.dat’. Each line contains: z(i), Dx(i)

pulsesuite.PSTD3D.usefulsubs.printIT2D(Dx, z, n, file)

Print 2D complex field to file with index number.

Writes a 2D complex field array to a file with index number in filename.

Parameters:

  • Dx (ndarray) – Field array (complex), 2D array

  • z (ndarray) – Spatial coordinates (real), 1D array (not used in output)

  • n (int) – Index number for filename

  • file (str) – Base filename (without extension and index)

Return type:

None

Notes

The file is written to ‘dataQW/{file}{n:07d}.dat’. Each line contains: abs(Dx(i,j)) The z parameter is kept for interface compatibility but not used.

pulsesuite.PSTD3D.usefulsubs.gaussian(x, x0)

Gaussian function.

Computes normalized Gaussian: exp(-x^2 / x0^2)

Parameters:

  • x (float or ndarray) – Input value(s)

  • x0 (float or ndarray) – Width parameter

Returns:

Gaussian function value(s)

Return type:

float or ndarray

Notes

This is an elemental function that works with both scalars and arrays.

pulsesuite.PSTD3D.usefulsubs.convolve(x, h)

Convolution of two complex arrays.

Computes convolution of signal array x with kernel/impulse array h.

Parameters:

  • x (ndarray) – Signal array (complex), 1D array

  • h (ndarray) – Kernel/impulse array (complex), 1D array

Returns:

Convolved array (complex), 1D array of same length as x

Return type:

ndarray

Notes

The convolution is computed using direct summation: - For i >= kernelsize: y(i) = sum(x(j)*h(k)) where j goes from i down to i-kernelsize+1 - For i < kernelsize: y(i) = sum(x(j)*h(k)) where j goes from i down to 1

pulsesuite.PSTD3D.usefulsubs.FFTG(F)

FFT with Gaussian normalization.

Performs FFT and applies Gaussian normalization: F = -FFT(F) / Nf

Parameters:

F (ndarray) – Input function (complex), modified in-place, 1D array

Returns:

F array is modified in-place.

Return type:

None

Notes

Uses pyfftw for FFT computation. The function performs: FFTC(F) then F = -F / Nf

pulsesuite.PSTD3D.usefulsubs.iFFTG(F)

IFFT with Gaussian normalization.

Performs IFFT and applies Gaussian normalization: F = -IFFT(F) * Nf

Parameters:

F (ndarray) – Input function (complex), modified in-place, 1D array

Returns:

F array is modified in-place.

Return type:

None

Notes

Uses pyfftw for IFFT computation. The function performs: iFFTC(F) then F = -F * Nf

pulsesuite.PSTD3D.usefulsubs.ReadIt(V, file)

Read array from file (interface-style wrapper).

Automatically dispatches to ReadIT1D or ReadIT2D based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • V (ndarray) – Array to read into (real), modified in-place, 1D or 2D array

  • file (str) – Base filename (without extension)

Returns:

V array is modified in-place.

Return type:

None

Notes

  • 1D arrays: calls ReadIT1D

  • 2D arrays: calls ReadIT2D

  • Raises ValueError for unsupported array dimensions

pulsesuite.PSTD3D.usefulsubs.WriteIt(V, file)

Write array to file (interface-style wrapper).

Automatically dispatches to WriteIT1D or WriteIT2D based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • V (ndarray) – Array to write (real), 1D or 2D array

  • file (str) – Base filename (without extension)

Return type:

None

Notes

  • 1D arrays: calls WriteIT1D

  • 2D arrays: calls WriteIT2D

  • Raises ValueError for unsupported array dimensions

pulsesuite.PSTD3D.usefulsubs.dfdy(f, qy)

Calculate derivative in y direction (interface-style wrapper).

Automatically dispatches to dfdy1D or dfdy2D based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • f (ndarray) – Input function (complex), 1D or 2D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

Returns:

Derivative df/dy (complex), same shape as input array

Return type:

ndarray

Notes

  • 1D arrays: calls dfdy1D

  • 2D arrays: calls dfdy2D

  • Raises ValueError for unsupported array dimensions

pulsesuite.PSTD3D.usefulsubs.dfdx(f, qx)

Calculate derivative in x direction (interface-style wrapper).

Automatically dispatches to dfdx1D or dfdx2D based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • f (ndarray) – Input function (complex), 1D or 2D array

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

Returns:

Derivative df/dx (complex), same shape as input array

Return type:

ndarray

Notes

  • 1D arrays: calls dfdx1D

  • 2D arrays: calls dfdx2D

  • Raises ValueError for unsupported array dimensions

pulsesuite.PSTD3D.usefulsubs.dfdy_q(f, qy)

Calculate derivative in y direction in q-space (interface-style wrapper).

Automatically dispatches to dfdy1D_q or dfdy2D_q based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • f (ndarray) – Input function in q-space (complex), 1D or 2D array

  • qy (ndarray) – Momentum coordinates in y direction (1/m), 1D array

Returns:

Derivative df/dy in q-space (complex), same shape as input array

Return type:

ndarray

Notes

  • 1D arrays: calls dfdy1D_q

  • 2D arrays: calls dfdy2D_q

  • Raises ValueError for unsupported array dimensions

pulsesuite.PSTD3D.usefulsubs.dfdx_q(f, qx)

Calculate derivative in x direction in q-space (interface-style wrapper).

Automatically dispatches to dfdx1D_q or dfdx2D_q based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • f (ndarray) – Input function in q-space (complex), 1D or 2D array

  • qx (ndarray) – Momentum coordinates in x direction (1/m), 1D array

Returns:

Derivative df/dx in q-space (complex), same shape as input array

Return type:

ndarray

Notes

  • 1D arrays: calls dfdx1D_q

  • 2D arrays: calls dfdx2D_q

  • Raises ValueError for unsupported array dimensions

pulsesuite.PSTD3D.usefulsubs.GFFT(f, dx, dy=None)

Gaussian FFT (interface-style wrapper).

Automatically dispatches to GFFT_1D or GFFT_2D based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • f (ndarray) – Input function (complex), modified in-place, 1D or 2D array

  • dx (float) – Spatial step size in x direction (m)

  • dy (float, optional) – Spatial step size in y direction (m). Required for 2D arrays.

Returns:

f array is modified in-place.

Return type:

None

Notes

  • 1D arrays: calls GFFT_1D(f, dx)

  • 2D arrays: calls GFFT_2D(f, dx, dy)

  • Raises ValueError for unsupported array dimensions or missing dy for 2D

pulsesuite.PSTD3D.usefulsubs.GIFFT(f, dq, dqy=None)

Gaussian IFFT (interface-style wrapper).

Automatically dispatches to GIFFT_1D or GIFFT_2D based on array dimensions. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

  • f (ndarray) – Input function (complex), modified in-place, 1D or 2D array

  • dq (float) – Momentum step size in x direction (1/m)

  • dqy (float, optional) – Momentum step size in y direction (1/m). Required for 2D arrays.

Returns:

f array is modified in-place.

Return type:

None

Notes

  • 1D arrays: calls GIFFT_1D(f, dq)

  • 2D arrays: calls GIFFT_2D(f, dq, dqy)

  • Raises ValueError for unsupported array dimensions or missing dqy for 2D

pulsesuite.PSTD3D.usefulsubs.fflip(f)

Flip array (interface-style wrapper).

Automatically dispatches to fflip_dp or fflip_dpc based on array dtype. This provides a unified interface similar to Fortran’s interface construct.

Parameters:

f (ndarray) – Input array (real or complex), 1D array

Returns:

Flipped array, same dtype as input

Return type:

ndarray

Notes

  • Real arrays: calls fflip_dp

  • Complex arrays: calls fflip_dpc

  • Raises ValueError for unsupported array dimensions