pulsesuite.libpulsesuite.helpers¶

Helper functions module.

Mostly useful functions that did not fit anywhere else.

This module provides utility functions for mathematical operations, interpolation, and field conversions.

Author: Rahul R. Sah

Attributes¶

`pi`
`eps0`
`c0`
`ec2`

Functions¶

`sech`(→ Union[float, numpy.ndarray])	Hyperbolic secant function.
`arg`(→ Union[float, numpy.ndarray])	Returns the angle of a complex number.
`gauss`(→ Union[float, numpy.ndarray])	Gaussian function.
`magsq`(→ Union[float, numpy.ndarray])	Magnitude squared of a complex number.
`constrain`(→ Union[float, int, numpy.ndarray])	Constrains values between limits.
`LinearInterp`(→ Union[float, complex])	Linear interpolation.
`BilinearInterp`(→ Union[float, complex])	Bilinear interpolation.
`TrilinearInterp`(→ Union[float, complex])	Trilinear interpolation.
`dfdt`(→ Union[float, complex, numpy.ndarray])	First derivative with respect to t.
`AmpToInten`(→ float)	Converts a real amplitude into the intensity.
`FldToInten`(→ float)	Converts a complex amplitude into the intensity.
`IntenToAmp`(→ float)	Converts the medium intensity to a real amplitude.
`arg_dp`(→ Union[float, numpy.ndarray])	Returns the angle of a complex number wrt the real axis.
`arg_sp`(→ Union[float, numpy.ndarray])	Returns the angle of a complex number wrt the real axis.
`sech_sp`(→ Union[float, numpy.ndarray])	Single precision sech.
`sech_dp`(→ Union[float, numpy.ndarray])	Double precision sech.
`gauss_dp`(→ Union[float, numpy.ndarray])	The Gaussian function.
`gauss_sp`(→ Union[float, numpy.ndarray])	The Gaussian function.
`magsq_dp`(→ Union[float, numpy.ndarray])	Computes the magnitude squared of a complex number.
`magsq_sp`(→ Union[float, numpy.ndarray])	Computes the magnitude squared of a complex number.
`LAX`(→ complex)	Implements the Lax method in finite differencing.
`noLAX`(→ complex)	Function with the same signature as LAX for a direct replacement.
`constrain_dp`(→ Union[float, numpy.ndarray])	Constrains a number between a high and a low value.
`constrain_int`(→ Union[int, numpy.ndarray])	Constrains a number between a high and a low value.
`l2f`(→ float)	Converts a wavelength into its corresponding frequency.
`l2w`(→ float)	Converts a wavelength into its corresponding angular frequency.
`w2l`(→ float)	Converts an angular frequency into its corresponding wavelength.
`GetSpaceArray`(→ numpy.ndarray)	Helper function to calculate the spatial array.
`GetKArray`(→ numpy.ndarray)	Calculates the wavevector array for the FFT.
`unwrap`(→ numpy.ndarray)	Reconstructs a smooth phase from one that has been wrapped by modulo 2π.
`factorial`(→ int)	Computes the factorial of an integer.
`LinearInterp_dpc`(→ complex)	Computes a linear interpolation of a complex 1D array at a specified position.
`LinearInterp_dp`(→ float)	Computes a linear interpolation of a real 1D array at a specified position.
`BilinearInterp_dpc`(→ complex)	Computes a linear interpolation of a complex 2D array at a specified position.
`BilinearInterp_dp`(→ float)	Computes a linear interpolation of a real 2D array at a specified position.
`TrilinearInterp_dpc`(→ complex)	Computes a linear interpolation of a complex 3D array at a specified position.
`TrilinearInterp_dp`(→ float)	Computes a linear interpolation of a real 3D array at a specified position.
`dfdt_dp`(→ float)	Returns the first derivative value of the array f(:) with respect to t
`dfdt_dpc`(→ complex)	Returns the first derivative value of the array f(:) with respect to t
`dfdt_1D_dp`(→ numpy.ndarray)	Returns the first derivative of the array f(:) with respect to t
`dfdt_1D_dpc`(→ numpy.ndarray)	Returns the first derivative of the array f(:) with respect to t
`isnan_dp`(→ Union[bool, numpy.ndarray])	A double precision isnan.
`isnan_sp`(→ Union[bool, numpy.ndarray])	A single precision isnan.

Module Contents¶

pulsesuite.libpulsesuite.helpers.pi¶

pulsesuite.libpulsesuite.helpers.eps0¶

pulsesuite.libpulsesuite.helpers.c0¶

pulsesuite.libpulsesuite.helpers.ec2¶

pulsesuite.libpulsesuite.helpers.sech(t: float | numpy.ndarray) → float | numpy.ndarray¶

Hyperbolic secant function.

Single and double precision sech function.

Parameters:: t (float or ndarray) – Input value(s)
Returns:: sech(t) = 1.0 / cosh(t)
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.arg(Z: complex | numpy.ndarray) → float | numpy.ndarray¶

Returns the angle of a complex number.

Returns the angle of a complex number with respect to the real axis.

Parameters:: Z (complex or ndarray) – Complex number(s)
Returns:: Angle in radians: atan2(imag(Z), real(Z))
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.gauss(x: float | numpy.ndarray) → float | numpy.ndarray¶

Gaussian function.

Returns exp(-x^2).

Parameters:: x (float or ndarray) – Input value(s)
Returns:: exp(-x^2)
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.magsq(Z: complex | numpy.ndarray) → float | numpy.ndarray¶

Magnitude squared of a complex number.

Provides a faster abs(Z)**2 by computing real(Z)^2 + imag(Z)^2.

Parameters:: Z (complex or ndarray) – Complex number(s)
Returns:: |Z|^2 = real(Z)^2 + imag(Z)^2
Return type:: float or ndarray

Constrains values between limits.

Constrains a number between a high and a low value.

Parameters:

x (float, int, or ndarray) – Value(s) to constrain
H (float or int) – High limit
L (float or int) – Low limit

Returns:

Constrained value(s): max(min(L,H), min(max(L,H), x))

Return type:

float, int, or ndarray

pulsesuite.libpulsesuite.helpers.LinearInterp(f: numpy.ndarray, x: numpy.ndarray, x0: float) → float | complex¶

Linear interpolation.

Returns the linearly interpolated value of the array f(:) at the position x0.

Parameters:

f (ndarray) – 1D array to be interpolated
x (ndarray) – 1D position array corresponding to ‘f’
x0 (float) – Position at which ‘f’ is to be interpolated

Returns:

Interpolated value at x0

Return type:

float or complex

pulsesuite.libpulsesuite.helpers.BilinearInterp(f: numpy.ndarray, x: numpy.ndarray, y: numpy.ndarray, x0: float, y0: float) → float | complex¶

Bilinear interpolation.

Returns the linearly interpolated value of the array f(:,:) at the position (x0,y0).

Parameters:

f (ndarray) – 2D array to be interpolated
x (ndarray) – 1D X position array corresponding to ‘f’
y (ndarray) – 1D Y position array corresponding to ‘f’
x0 (float) – X position at which ‘f’ is to be interpolated
y0 (float) – Y position at which ‘f’ is to be interpolated

Returns:

Interpolated value at (x0, y0)

Return type:

float or complex

pulsesuite.libpulsesuite.helpers.TrilinearInterp(f: numpy.ndarray, x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, x0: float, y0: float, z0: float) → float | complex¶

Trilinear interpolation.

Returns the linearly interpolated value of the array f(:,:,:) at the position (x0,y0,z0).

Parameters:

f (ndarray) – 3D array to be interpolated
x (ndarray) – 1D X position array corresponding to ‘f’
y (ndarray) – 1D Y position array corresponding to ‘f’
z (ndarray) – 1D Z position array corresponding to ‘f’
x0 (float) – X position at which ‘f’ is to be interpolated
y0 (float) – Y position at which ‘f’ is to be interpolated
z0 (float) – Z position at which ‘f’ is to be interpolated

Returns:

Interpolated value at (x0, y0, z0)

Return type:

float or complex

pulsesuite.libpulsesuite.helpers.dfdt(f: numpy.ndarray, dt: float, k: int | None = None) → float | complex | numpy.ndarray¶

First derivative with respect to t.

Returns the first derivative value of the array f(:) with respect to t at the index k with a five-point stencil method.

Parameters:

f (ndarray) – Function of t, 1D array
dt (float) – t differential
k (int, optional) – t-index for dfdt. If None, returns derivative for all points.

Returns:

Derivative value(s)

Return type:

float, complex, or ndarray

pulsesuite.libpulsesuite.helpers.AmpToInten(e: float, n0: float | None = None) → float¶

Converts a real amplitude into the intensity.

Converts a real amplitude into the intensity in a medium with refractive index n0. Default n0 = 1.0.

Uses the formula: I = n0 * 2 * eps0 * c0 * E^2

Parameters:

e (float) – The amplitude
n0 (float, optional) – The linear refractive index (default: 1.0)

Returns:

The corresponding intensity

Return type:

float

pulsesuite.libpulsesuite.helpers.FldToInten(e: complex, n0: float | None = None) → float¶

Converts a complex amplitude into the intensity.

Converts a complex amplitude into the intensity in a medium with refractive index n0. Default n0 = 1.0.

Uses the formula: I = n0 * 2 * eps0 * c0 * |E|^2

Parameters:

e (complex) – The complex amplitude
n0 (float, optional) – The linear refractive index (default: 1.0)

Returns:

The corresponding intensity

Return type:

float

pulsesuite.libpulsesuite.helpers.IntenToAmp(inten: float, n0: float | None = None) → float¶

Converts the medium intensity to a real amplitude.

Converts the medium intensity to a real amplitude. Default n0 = 1.0.

Uses the formula: E = sqrt(I / (n0 * 2 * eps0 * c0))

Parameters:

inten (float) – The intensity
n0 (float, optional) – The linear refractive index (default: 1.0)

Returns:

The corresponding amplitude

Return type:

float

pulsesuite.libpulsesuite.helpers.arg_dp(Z: complex | numpy.ndarray) → float | numpy.ndarray¶

Returns the angle of a complex number wrt the real axis.

Parameters:: Z (complex or ndarray) – Complex number(s)
Returns:: Angle in radians: atan2(imag(Z), real(Z))
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.arg_sp(Z: complex | numpy.ndarray) → float | numpy.ndarray¶

Returns the angle of a complex number wrt the real axis.

Parameters:: Z (complex or ndarray) – Complex number(s), single precision
Returns:: Angle in radians: atan2(imag(Z), real(Z))
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.sech_sp(t: float | numpy.ndarray) → float | numpy.ndarray¶

Single precision sech.

Parameters:: t (float or ndarray) – Input value(s), single precision
Returns:: sech(t) = 1.0 / cosh(t)
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.sech_dp(t: float | numpy.ndarray) → float | numpy.ndarray¶

Double precision sech.

Parameters:: t (float or ndarray) – Input value(s), double precision
Returns:: sech(t) = 1.0 / cosh(t)
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.gauss_dp(x: float | numpy.ndarray) → float | numpy.ndarray¶

The Gaussian function.

Returns exp(-x^2).

Parameters:: x (float or ndarray) – Input value(s), double precision
Returns:: exp(-x^2)
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.gauss_sp(x: float | numpy.ndarray) → float | numpy.ndarray¶

The Gaussian function.

Returns exp(-x^2).

Parameters:: x (float or ndarray) – Input value(s), single precision
Returns:: exp(-x^2)
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.magsq_dp(Z: complex | numpy.ndarray) → float | numpy.ndarray¶

Computes the magnitude squared of a complex number.

Computes real(Z)^2 + imag(Z)^2.

Parameters:: Z (complex or ndarray) – Complex number(s), double precision
Returns:: |Z|^2 = real(Z)^2 + imag(Z)^2
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.magsq_sp(Z: complex | numpy.ndarray) → float | numpy.ndarray¶

Computes the magnitude squared of a complex number.

Computes real(Z)^2 + imag(Z)^2.

Parameters:: Z (complex or ndarray) – Complex number(s), single precision
Returns:: |Z|^2 = real(Z)^2 + imag(Z)^2
Return type:: float or ndarray

pulsesuite.libpulsesuite.helpers.LAX(u: numpy.ndarray, i: int, j: int, k: int) → complex¶

Implements the Lax method in finite differencing.

Improves the stability of explicit methods.

Parameters:

u (ndarray) – 3D complex array
i (int) – Index in first dimension
j (int) – Index in second dimension
k (int) – Index in third dimension

Returns:

Lax average: (u(i-1,j,k) + u(i+1,j,k) + u(i,j-1,k) + u(i,j+1,k) + u(i,j,k-1) + u(i,j,k+1)) / 6.0

Return type:

complex

pulsesuite.libpulsesuite.helpers.noLAX(u: numpy.ndarray, i: int, j: int, k: int) → complex¶

Function with the same signature as LAX for a direct replacement.

Does not implement the Lax method.

Parameters:

u (ndarray) – 3D complex array
i (int) – Index in first dimension
j (int) – Index in second dimension
k (int) – Index in third dimension

Returns:

Direct value: u(i,j,k)

Return type:

complex

pulsesuite.libpulsesuite.helpers.constrain_dp(x: float | numpy.ndarray, H: float, L: float) → float | numpy.ndarray¶

Constrains a number between a high and a low value.

Parameters:

x (float or ndarray) – Value(s) to constrain, double precision
H (float) – High limit
L (float) – Low limit

Returns:

Constrained value(s): max(min(L,H), min(max(L,H), x))

Return type:

float or ndarray

pulsesuite.libpulsesuite.helpers.constrain_int(x: int | numpy.ndarray, H: int, L: int) → int | numpy.ndarray¶

Constrains a number between a high and a low value.

Parameters:

x (int or ndarray) – Value(s) to constrain, integer
H (int) – High limit
L (int) – Low limit

Returns:

Constrained value(s): max(min(L,H), min(max(L,H), x))

Return type:

int or ndarray

pulsesuite.libpulsesuite.helpers.l2f(lam: float) → float¶

Converts a wavelength into its corresponding frequency.

Uses the formula: f = c0 / λ

Parameters:: lam (float) – Wavelength
Returns:: Corresponding frequency: c0 / lam
Return type:: float

pulsesuite.libpulsesuite.helpers.l2w(lam: float) → float¶

Converts a wavelength into its corresponding angular frequency.

Uses the formula: ω = 2π * c0 / λ

Parameters:: lam (float) – Wavelength
Returns:: Corresponding angular frequency: 2π * c0 / lam
Return type:: float

pulsesuite.libpulsesuite.helpers.w2l(w: float) → float¶

Converts an angular frequency into its corresponding wavelength.

Uses the formula: λ = 2π * c0 / ω

Parameters:: w (float) – Angular frequency
Returns:: Corresponding wavelength: 2π * c0 / w
Return type:: float

pulsesuite.libpulsesuite.helpers.GetSpaceArray(N: int, length: float) → numpy.ndarray¶

Helper function to calculate the spatial array.

Change this function to change the centering of the field.

Parameters:

N (int) – Number of points
length (float) – Total length

Returns:

Spatial array X of size N, centered around 0

Return type:

ndarray

pulsesuite.libpulsesuite.helpers.GetKArray(N: int, length: float) → numpy.ndarray¶

Calculates the wavevector array for the FFT.

Parameters:

N (int) – Number of points
length (float) – Total length

Returns:

Wavevector array of size N

Return type:

ndarray

pulsesuite.libpulsesuite.helpers.unwrap(phase: numpy.ndarray) → numpy.ndarray¶

Reconstructs a smooth phase from one that has been wrapped by modulo 2π.

Parameters:: phase (ndarray) – Wrapped phase array
Returns:: Unwrapped phase array
Return type:: ndarray

pulsesuite.libpulsesuite.helpers.factorial(p: int) → int¶

Computes the factorial of an integer.

Parameters:: p (int) – Input integer
Returns:: Factorial of p (p!)
Return type:: int

pulsesuite.libpulsesuite.helpers.LinearInterp_dpc(f: numpy.ndarray, x: numpy.ndarray, x0: float) → complex¶

Computes a linear interpolation of a complex 1D array at a specified position.

Parameters:

f (ndarray) – 1D complex array to be interpolated
x (ndarray) – 1D position array corresponding to ‘f’
x0 (float) – Position at which ‘f’ is to be interpolated

Returns:

Interpolated value at x0

Return type:

complex

pulsesuite.libpulsesuite.helpers.LinearInterp_dp(f: numpy.ndarray, x: numpy.ndarray, x0: float) → float¶

Computes a linear interpolation of a real 1D array at a specified position.

Parameters:

f (ndarray) – 1D real array to be interpolated
x (ndarray) – 1D position array corresponding to ‘f’
x0 (float) – Position at which ‘f’ is to be interpolated

Returns:

Interpolated value at x0

Return type:

float

pulsesuite.libpulsesuite.helpers.BilinearInterp_dpc(f: numpy.ndarray, x: numpy.ndarray, y: numpy.ndarray, x0: float, y0: float) → complex¶

Computes a linear interpolation of a complex 2D array at a specified position.

Parameters:

f (ndarray) – 2D complex array to be interpolated
x (ndarray) – 1D X position array corresponding to ‘f’
y (ndarray) – 1D Y position array corresponding to ‘f’
x0 (float) – X position at which ‘f’ is to be interpolated
y0 (float) – Y position at which ‘f’ is to be interpolated

Returns:

Interpolated value at (x0, y0)

Return type:

complex

pulsesuite.libpulsesuite.helpers.BilinearInterp_dp(f: numpy.ndarray, x: numpy.ndarray, y: numpy.ndarray, x0: float, y0: float) → float¶

Computes a linear interpolation of a real 2D array at a specified position.

Parameters:

f (ndarray) – 2D real array to be interpolated
x (ndarray) – 1D X position array corresponding to ‘f’
y (ndarray) – 1D Y position array corresponding to ‘f’
x0 (float) – X position at which ‘f’ is to be interpolated
y0 (float) – Y position at which ‘f’ is to be interpolated

Returns:

Interpolated value at (x0, y0)

Return type:

float

pulsesuite.libpulsesuite.helpers.TrilinearInterp_dpc(f: numpy.ndarray, x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, x0: float, y0: float, z0: float) → complex¶

Computes a linear interpolation of a complex 3D array at a specified position.

Parameters:

f (ndarray) – 3D complex array to be interpolated
x (ndarray) – 1D X position array corresponding to ‘f’
y (ndarray) – 1D Y position array corresponding to ‘f’
z (ndarray) – 1D Z position array corresponding to ‘f’
x0 (float) – X position at which ‘f’ is to be interpolated
y0 (float) – Y position at which ‘f’ is to be interpolated
z0 (float) – Z position at which ‘f’ is to be interpolated

Returns:

Interpolated value at (x0, y0, z0)

Return type:

complex

pulsesuite.libpulsesuite.helpers.TrilinearInterp_dp(f: numpy.ndarray, x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, x0: float, y0: float, z0: float) → float¶

Computes a linear interpolation of a real 3D array at a specified position.

Parameters:

f (ndarray) – 3D real array to be interpolated
x (ndarray) – 1D X position array corresponding to ‘f’
y (ndarray) – 1D Y position array corresponding to ‘f’
z (ndarray) – 1D Z position array corresponding to ‘f’
x0 (float) – X position at which ‘f’ is to be interpolated
y0 (float) – Y position at which ‘f’ is to be interpolated
z0 (float) – Z position at which ‘f’ is to be interpolated

Returns:

Interpolated value at (x0, y0, z0)

Return type:

float

pulsesuite.libpulsesuite.helpers.dfdt_dp(f: numpy.ndarray, dt: float, k: int) → float¶

Returns the first derivative value of the array f(:) with respect to t at the index k with a five-point stencil method.

Parameters:

f (ndarray) – Function of t, 1D real array
dt (float) – t differential
k (int) – t-index for dfdt (0-based, but FORTRAN logic uses 1-based)

Returns:

Derivative value at index k

Return type:

float

pulsesuite.libpulsesuite.helpers.dfdt_dpc(f: numpy.ndarray, dt: float, k: int) → complex¶

Returns the first derivative value of the array f(:) with respect to t at the index k with a five-point stencil method.

Parameters:

f (ndarray) – Function of t, 1D complex array
dt (float) – t differential
k (int) – t-index for dfdt (0-based, but FORTRAN logic uses 1-based)

Returns:

Derivative value at index k

Return type:

complex

pulsesuite.libpulsesuite.helpers.dfdt_1D_dp(f: numpy.ndarray, dt: float) → numpy.ndarray¶

Returns the first derivative of the array f(:) with respect to t for all points using a five-point stencil method.

Parameters:

f (ndarray) – Function of t, 1D real array
dt (float) – t differential

Returns:

Derivative array

Return type:

ndarray

pulsesuite.libpulsesuite.helpers.dfdt_1D_dpc(f: numpy.ndarray, dt: float) → numpy.ndarray¶

Returns the first derivative of the array f(:) with respect to t for all points using a five-point stencil method.

Parameters:

f (ndarray) – Function of t, 1D complex array
dt (float) – t differential

Returns:

Derivative array

Return type:

ndarray

pulsesuite.libpulsesuite.helpers.isnan_dp(X: float | numpy.ndarray) → bool | numpy.ndarray¶

A double precision isnan.

Wraps numpy’s isnan for double precision.

Parameters:: X (float or ndarray) – Value(s) to check, double precision
Returns:: True if X is NaN, False otherwise
Return type:: bool or ndarray

pulsesuite.libpulsesuite.helpers.isnan_sp(X: float | numpy.ndarray) → bool | numpy.ndarray¶

A single precision isnan.

Wraps numpy’s isnan for single precision.

Parameters:: X (float or ndarray) – Value(s) to check, single precision
Returns:: True if X is NaN, False otherwise
Return type:: bool or ndarray