pulsesuite.PSTD3D.typespace¶

Spatial grid structure for quantum wire simulations.

This module provides the spatial grid structure (ss type) and associated functions for reading, writing, and accessing spatial grid parameters. Supports 1D, 2D, and 3D grids with configurable pixel sizes and dielectric constants.

Author: Rahul R. Sah

Attributes¶

`JIT_AVAILABLE`
`pi`
`twopi`
`LOGVERBOSE`

Classes¶

`ss`	Spatial grid structure.

Functions¶

`GetFileParam`(file_handle)	Read a parameter from a file handle.
`GetLogLevel`()	Get the current logging level.
`readspaceparams_sub`(file_handle, space)	Read the space parameters (ss) from a file handle.
`ReadSpaceParams`(filename, space)	Read the space parameters (ss) from a file.
`WriteSpaceParams_sub`(file_handle, space)	Write space parameters (ss) to a file handle.
`writespaceparams`(filename, space)	Write space parameters (ss) to a file.
`dumpspace`(params[, level])	Dump space parameters to stdout.
`GetNx`(space)	Get the number of points in the x direction.
`GetNy`(space)	Get the number of points in the y direction.
`GetNz`(space)	Get the number of points in the z direction.
`GetDx`(space)	Get the step size for the x dimension.
`GetDy`(space)	Get the step size for the y dimension.
`GetDz`(space)	Get the step size for the z dimension.
`GetEpsr`(space)	Get the relative background dielectric constant.
`SetNx`(space, N)	Set the number of points in the x dimension.
`SetNy`(space, N)	Set the number of points in the y dimension.
`SetNz`(space, N)	Set the number of points in the z dimension.
`SetDx`(space, dl)	Set the step size for the x dimension.
`SetDy`(space, dl)	Set the step size for the y dimension.
`SetDz`(space, dl)	Set the step size for the z dimension.
`GetXWidth`(space)	Get the width of the x window.
`GetYWidth`(space)	Get the width of the y window.
`GetZWidth`(space)	Get the width of the z window.
`GetSpaceArray`(N, L)	Generate a real-space position array.
`GetKArray`(Nk, L)	Generate k-space array for Fourier transforms.
`GetXArray`(space)	Get an array of x positions.
`GetYArray`(space)	Get an array of y positions.
`GetZArray`(space)	Get an array of z positions.
`GetKxArray`(space)	Get an array of kx values (conjugate coordinate system).
`GetKyArray`(space)	Get an array of ky values (conjugate coordinate system).
`GetKzArray`(space)	Get an array of kz values (conjugate coordinate system).
`GetDQx`(space)	Get the differential for the conjugate coordinate system in x.
`GetDQy`(space)	Get the differential for the conjugate coordinate system in y.
`GetDQz`(space)	Get the differential for the conjugate coordinate system in z.
`GetDVol`(space)	Get the volume element.
`GetDQVol`(space)	Get the volume element for the conjugate coordinate system.
`writefield`(fnout, e, space, binmode, single[, fnspace])	Write the space structure and field to a file.
`readspace_only`(fnin, space, binmode, single[, fnspace])	Read the space structure from a field file.
`writefield_to_unit`(file_handle, e, binmode)	Write field array to a file handle.
`unformatted_write_space`(file_handle, space)	Write space structure in binary format.
`unformatted_read_space`(file_handle, space)	Read space structure from binary format.
`initialize_field`(e)	Initialize field array to zero.
`unformatted_write_e`(file_handle, e)	Write field array in binary format.
`unformatted_read_e`(file_handle, e)	Read field array from binary format.
`readfield_from_unit`(file_handle, e, binmode)	Read field array from a file handle.
`readfield`(fnin, e, space, binmode, single[, fnspace])	Read the space structure and field from a file.

Module Contents¶

pulsesuite.PSTD3D.typespace.JIT_AVAILABLE = True¶

pulsesuite.PSTD3D.typespace.pi¶

pulsesuite.PSTD3D.typespace.twopi¶

pulsesuite.PSTD3D.typespace.LOGVERBOSE = 2¶

pulsesuite.PSTD3D.typespace.GetFileParam(file_handle)¶

Read a parameter from a file handle.

Reads a single numeric parameter from the file. Assumes the file format has one parameter per line, possibly with comments after the value.

Parameters:: file_handle (file) – Open file handle to read from
Returns:: Parameter value read from file
Return type:: float

Notes

This is a helper function for reading parameter files. It reads a line, extracts the first numeric value, and returns it.

This function is not defined in typespace.f90 but is used by readspaceparams_sub. It is likely defined in the fileio module in Fortran. This Python implementation provides equivalent functionality.

pulsesuite.PSTD3D.typespace.GetLogLevel()¶

Get the current logging level.

Returns the current logging verbosity level. Higher values mean more verbose.

Returns:: Current logging level (default: 0)
Return type:: int

Notes

This is a stub implementation. In a full system, this would interface with a logging module to get the actual log level.

This function is not defined in typespace.f90 but is used by dumpspace. It is likely defined in the logger module in Fortran. This Python implementation provides a default minimal logging level.

class pulsesuite.PSTD3D.typespace.ss¶

Spatial grid structure.

The spatial grid structure contains all parameters needed to define a 1D, 2D, or 3D spatial grid for simulations.

Dims¶

Dimensionality of grid (1=1D, 2=2D, 3=3D)

Type:: int

Nx¶

X-window number of pixels

Type:: int

Ny¶

Y-window number of pixels [Ny=1 for 1D]

Type:: int

Nz¶

Z-window number of pixels [Nz=1 for 1D and 2D]

Type:: int

dx¶

Size of x-pixel (m)

Type:: float

dy¶

Size of y-pixel (m), [dy=1.0 for 1D]

Type:: float

dz¶

Size of z-pixel (m), [dz=1.0 for 1D and 2D]

Type:: float

epsr¶

Background dielectric constant

Type:: float

Dims: int¶

Nx: int¶

Ny: int¶

Nz: int¶

dx: float¶

dy: float¶

dz: float¶

epsr: float¶

pulsesuite.PSTD3D.typespace.readspaceparams_sub(file_handle, space)¶

Read the space parameters (ss) from a file handle.

Reads all space parameters from an open file handle and populates the space structure.

Parameters:

file_handle (file) – Open file handle to read from
space (ss) – Space structure to populate (modified in-place)

Returns:

space structure is modified in-place

Return type:

None

Notes

The file format expects 8 parameters in order: 1. Dims (integer) 2. Nx (integer) 3. Ny (integer) 4. Nz (integer) 5. dx (float) 6. dy (float) 7. dz (float) 8. epsr (float)

pulsesuite.PSTD3D.typespace.ReadSpaceParams(filename, space)¶

Read the space parameters (ss) from a file.

Opens the specified file, reads the space parameters, and populates the space structure. Also dumps the parameters to stdout if logging level is sufficient.

Parameters:

filename (str) – The filename to read from
space (ss) – Space structure to populate (modified in-place)

Returns:

space structure is modified in-place

Return type:

None

Notes

The file is opened, read, and closed automatically. After reading, dumpspace is called to log the parameters.

pulsesuite.PSTD3D.typespace.WriteSpaceParams_sub(file_handle, space)¶

Write space parameters (ss) to a file handle.

Writes all space parameters to an open file handle with descriptive comments for each parameter.

Parameters:

file_handle (file) – Open file handle to write to
space (ss) – Space structure to write

Return type:

None

Notes

The format matches the Fortran output format: - Integers are written with format I25 (right-aligned, 25 characters) - Floats are written with format E25.15E3 (scientific notation, 25 chars) - Each line has a comment describing the parameter

Note: The Fortran source has typos in lines 94-96 (says “With” instead of “Width” and all three say “X pixel” instead of X/Y/Z). This Python implementation corrects those typos.

pulsesuite.PSTD3D.typespace.writespaceparams(filename, space)¶

Write space parameters (ss) to a file.

Opens the specified file, writes all space parameters with descriptive comments, and closes the file.

Parameters:

filename (str) – The filename to write to
space (ss) – Space structure to write

Return type:

None

Notes

The file is opened in write mode, written to, and closed automatically.

pulsesuite.PSTD3D.typespace.dumpspace(params, level=None)¶

Dump space parameters to stdout.

Writes space parameters to stdout (file handle 0) if the logging level is sufficient. Used for debugging and verbose output.

Parameters:

params (ss) – Space structure to dump
level (int, optional) – Minimum logging level required to dump. If not provided, uses LOGVERBOSE as the default threshold.

Return type:

None

Notes

If level is provided, dumps only if GetLogLevel() >= level. Otherwise, dumps only if GetLogLevel() >= LOGVERBOSE.

pulsesuite.PSTD3D.typespace.GetNx(space)¶

Get the number of points in the x direction.

Returns the number of spatial grid points in the x-direction.

Parameters:: space (ss) – Space structure
Returns:: Number of points in the x direction
Return type:: int

pulsesuite.PSTD3D.typespace.GetNy(space)¶

Get the number of points in the y direction.

Returns the number of spatial grid points in the y-direction.

Parameters:: space (ss) – Space structure
Returns:: Number of points in the y direction
Return type:: int

pulsesuite.PSTD3D.typespace.GetNz(space)¶

Get the number of points in the z direction.

Returns the number of spatial grid points in the z-direction.

Parameters:: space (ss) – Space structure
Returns:: Number of points in the z direction
Return type:: int

pulsesuite.PSTD3D.typespace.GetDx(space)¶

Get the step size for the x dimension.

Returns the x-pixel size. If Nx == 1 (collapsed dimension), returns 1.0 instead of the actual dx value.

Parameters:: space (ss) – Space structure
Returns:: Step size for x dimension (m), or 1.0 if Nx == 1
Return type:: float

pulsesuite.PSTD3D.typespace.GetDy(space)¶

Get the step size for the y dimension.

Returns the y-pixel size. If Ny == 1 (collapsed dimension), returns 1.0 instead of the actual dy value.

Parameters:: space (ss) – Space structure
Returns:: Step size for y dimension (m), or 1.0 if Ny == 1
Return type:: float

pulsesuite.PSTD3D.typespace.GetDz(space)¶

Get the step size for the z dimension.

Returns the z-pixel size. If Nz == 1 (collapsed dimension), returns 1.0 instead of the actual dz value.

Parameters:: space (ss) – Space structure
Returns:: Step size for z dimension (m), or 1.0 if Nz == 1
Return type:: float

pulsesuite.PSTD3D.typespace.GetEpsr(space)¶

Get the relative background dielectric constant.

Returns the dielectric constant. If Nz == 1 (1D or 2D case), returns 1.0 instead of the actual epsr value.

Parameters:: space (ss) – Space structure
Returns:: Relative background dielectric constant, or 1.0 if Nz == 1
Return type:: float

pulsesuite.PSTD3D.typespace.SetNx(space, N)¶

Set the number of points in the x dimension.

Sets the number of spatial grid points in the x-direction.

Parameters:

space (ss) – Space structure (modified in-place)
N (int) – Number of points in x direction

Returns:

space structure is modified in-place

Return type:

None

pulsesuite.PSTD3D.typespace.SetNy(space, N)¶

Set the number of points in the y dimension.

Sets the number of spatial grid points in the y-direction.

Parameters:

space (ss) – Space structure (modified in-place)
N (int) – Number of points in y direction

Returns:

space structure is modified in-place

Return type:

None

pulsesuite.PSTD3D.typespace.SetNz(space, N)¶

Set the number of points in the z dimension.

Sets the number of spatial grid points in the z-direction.

Parameters:

space (ss) – Space structure (modified in-place)
N (int) – Number of points in z direction

Returns:

space structure is modified in-place

Return type:

None

pulsesuite.PSTD3D.typespace.SetDx(space, dl)¶

Set the step size for the x dimension.

Sets the x-pixel size.

Parameters:

space (ss) – Space structure (modified in-place)
dl (float) – Step size for x dimension (m)

Returns:

space structure is modified in-place

Return type:

None

pulsesuite.PSTD3D.typespace.SetDy(space, dl)¶

Set the step size for the y dimension.

Sets the y-pixel size.

Parameters:

space (ss) – Space structure (modified in-place)
dl (float) – Step size for y dimension (m)

Returns:

space structure is modified in-place

Return type:

None

pulsesuite.PSTD3D.typespace.SetDz(space, dl)¶

Set the step size for the z dimension.

Sets the z-pixel size.

Parameters:

space (ss) – Space structure (modified in-place)
dl (float) – Step size for z dimension (m)

Returns:

space structure is modified in-place

Return type:

None

pulsesuite.PSTD3D.typespace.GetXWidth(space)¶

Get the width of the x window.

Returns the total width of the spatial window in the x-direction: width = dx * (Nx - 1)

Parameters:: space (ss) – Space structure
Returns:: Width of x window (m)
Return type:: float

pulsesuite.PSTD3D.typespace.GetYWidth(space)¶

Get the width of the y window.

Returns the total width of the spatial window in the y-direction: width = dy * (Ny - 1)

Parameters:: space (ss) – Space structure
Returns:: Width of y window (m)
Return type:: float

pulsesuite.PSTD3D.typespace.GetZWidth(space)¶

Get the width of the z window.

Returns the total width of the spatial window in the z-direction: width = dz * (Nz - 1)

Parameters:: space (ss) – Space structure
Returns:: Width of z window (m)
Return type:: float

pulsesuite.PSTD3D.typespace.GetSpaceArray(N, L)¶

Generate a real-space position array.

Creates an array of N positions evenly spaced across a window of width L, centered at zero. The positions range from -L/2 to L/2.

Parameters:

N (int) – Number of points
L (float) – Total width of the window (m)

Returns:

Array of position values (m), 1D array of length N

Return type:

ndarray

Notes

The array is centered at zero, so positions range from -L/2 to L/2. For N=1, returns array with single value 0.0.

This function is not defined in typespace.f90 but is used by GetXArray, GetYArray, and GetZArray. It is likely defined in the helpers module in Fortran. The implementation matches usage patterns in other Fortran files (e.g., GetSpaceArray(Ny, (Ny-1) * dyy) in pstd.f90).

pulsesuite.PSTD3D.typespace.GetKArray(Nk, L)¶

Generate k-space array for Fourier transforms.

Creates an array of Nk k-values (momentum values) for use with FFT. The array is centered at zero and spaced by dk = twopi/L.

Parameters:

Nk (int) – Number of k-space points
L (float) – Length of the spatial domain (m)

Returns:

Array of k values (1/m), 1D array of length Nk

Return type:

ndarray

Notes

The k-values are centered at zero, suitable for FFT operations. For Nk=1, returns array with single value 0.0.

This function is not defined in typespace.f90 but is used by GetKxArray, GetKyArray, and GetKzArray. It is likely defined in the helpers module in Fortran. The implementation matches usage patterns in other Fortran files.

pulsesuite.PSTD3D.typespace.GetXArray(space)¶

Get an array of x positions.

Returns an array of x-coordinate positions for the spatial grid. If Nx == 1, returns array with single value 0.0.

Parameters:: space (ss) – Space structure
Returns:: Array of x positions (m), 1D array of length space.Nx
Return type:: ndarray

pulsesuite.PSTD3D.typespace.GetYArray(space)¶

Get an array of y positions.

Returns an array of y-coordinate positions for the spatial grid. If Ny == 1, returns array with single value 0.0.

Parameters:: space (ss) – Space structure
Returns:: Array of y positions (m), 1D array of length space.Ny
Return type:: ndarray

pulsesuite.PSTD3D.typespace.GetZArray(space)¶

Get an array of z positions.

Returns an array of z-coordinate positions for the spatial grid. If Nz == 1, returns array with single value 0.0.

Parameters:: space (ss) – Space structure
Returns:: Array of z positions (m), 1D array of length space.Nz
Return type:: ndarray

pulsesuite.PSTD3D.typespace.GetKxArray(space)¶

Get an array of kx values (conjugate coordinate system).

Returns an array of kx (momentum) values for the conjugate coordinate system, suitable for FFT operations. If Nx == 1, returns array with single value 0.0.

Parameters:: space (ss) – Space structure
Returns:: Array of kx values (1/m), 1D array of length space.Nx
Return type:: ndarray

pulsesuite.PSTD3D.typespace.GetKyArray(space)¶

Get an array of ky values (conjugate coordinate system).

Returns an array of ky (momentum) values for the conjugate coordinate system, suitable for FFT operations. If Ny == 1, returns array with single value 0.0.

Parameters:: space (ss) – Space structure
Returns:: Array of ky values (1/m), 1D array of length space.Ny
Return type:: ndarray

pulsesuite.PSTD3D.typespace.GetKzArray(space)¶

Get an array of kz values (conjugate coordinate system).

Returns an array of kz (momentum) values for the conjugate coordinate system, suitable for FFT operations. If Nz == 1, returns array with single value 0.0.

Parameters:: space (ss) – Space structure
Returns:: Array of kz values (1/m), 1D array of length space.Nz
Return type:: ndarray

pulsesuite.PSTD3D.typespace.GetDQx(space)¶

Get the differential for the conjugate coordinate system in x.

Returns the k-space step size in the x-direction: dqx = twopi / GetXWidth(space)

Parameters:: space (ss) – Space structure
Returns:: k-space step size in x direction (1/m)
Return type:: float

Notes

Matches Fortran implementation which uses twopi constant. Returns 0.0 if width is zero (Fortran would divide by zero).

pulsesuite.PSTD3D.typespace.GetDQy(space)¶

Get the differential for the conjugate coordinate system in y.

Returns the k-space step size in the y-direction: dqy = twopi / GetYWidth(space)

Parameters:: space (ss) – Space structure
Returns:: k-space step size in y direction (1/m)
Return type:: float

Notes

Matches Fortran implementation which uses twopi constant. Returns 0.0 if width is zero (Fortran would divide by zero).

pulsesuite.PSTD3D.typespace.GetDQz(space)¶

Get the differential for the conjugate coordinate system in z.

Returns the k-space step size in the z-direction: dqz = twopi / GetZWidth(space)

Parameters:: space (ss) – Space structure
Returns:: k-space step size in z direction (1/m)
Return type:: float

Notes

Matches Fortran implementation which uses twopi constant. Returns 0.0 if width is zero (Fortran would divide by zero).

pulsesuite.PSTD3D.typespace.GetDVol(space)¶

Get the volume element.

Returns the volume element (dx * dy * dz) for the spatial grid.

Parameters:: space (ss) – Space structure
Returns:: Volume element (m^3)
Return type:: float

pulsesuite.PSTD3D.typespace.GetDQVol(space)¶

Get the volume element for the conjugate coordinate system.

Returns the k-space volume element (dqx * dqy * dqz).

Parameters:: space (ss) – Space structure
Returns:: k-space volume element ((1/m)^3)
Return type:: float

pulsesuite.PSTD3D.typespace.writefield(fnout, e, space, binmode, single, fnspace=None)¶

Write the space structure and field to a file.

Writes the space structure (ss) and the complex field array to a single file. Can write in binary or text format, and can include space parameters in the same file or a separate file.

Parameters:

fnout (str) – Filename to write to, or “stdout” or “-” for stdout
e (ndarray) – Complex field array, 3D array of shape (Nx, Ny, Nz)
space (ss) – Space structure
binmode (bool) – If True, write in binary format; if False, write in text format
single (bool) – If True, include space parameters in the same file
fnspace (str, optional) – If single is False, write space parameters to this separate file

Return type:

None

Notes

For binary mode, uses unformatted_write_space and unformatted_write_e. For text mode, uses WriteSpaceParams_sub and formatted field output.

pulsesuite.PSTD3D.typespace.readspace_only(fnin, space, binmode, single, fnspace=None)¶

Read the space structure from a field file.

Reads the space structure (ss) from a field file. Can read from binary or text format, and can read space parameters from the same file or a separate file.

Parameters:

fnin (str) – Filename to read from, or “stdin” or “-” for stdin
space (ss) – Space structure to populate (modified in-place)
binmode (bool) – If True, read from binary format; if False, read from text format
single (bool) – If True, read space parameters from the same file
fnspace (str, optional) – If single is False, read space parameters from this separate file

Returns:

space structure is modified in-place

Return type:

None

Notes

For binary mode, uses unformatted_read_space. For text mode, uses readspaceparams_sub.

pulsesuite.PSTD3D.typespace.writefield_to_unit(file_handle, e, binmode)¶

Write field array to a file handle.

Writes the complex field array to an open file handle in either binary or text format.

Parameters:

file_handle (file) – Open file handle to write to
e (ndarray) – Complex field array, 3D array
binmode (bool) – If True, write in binary format; if False, write in text format

Return type:

None

Notes

For binary mode, uses numpy’s save or pickle. For text mode, writes real and imaginary parts separately.

pulsesuite.PSTD3D.typespace.unformatted_write_space(file_handle, space)¶

Write space structure in binary format.

Writes the space structure to a file handle in binary (unformatted) format.

Parameters:

file_handle (file) – Open binary file handle to write to
space (ss) – Space structure to write

Return type:

None

Notes

Uses numpy’s save to write the dataclass fields in binary format.

pulsesuite.PSTD3D.typespace.unformatted_read_space(file_handle, space)¶

Read space structure from binary format.

Reads the space structure from a file handle in binary (unformatted) format.

Parameters:

file_handle (file) – Open binary file handle to read from
space (ss) – Space structure to populate (modified in-place)

Returns:

space structure is modified in-place

Return type:

None

Notes

Uses numpy’s load to read the dataclass fields from binary format.

pulsesuite.PSTD3D.typespace.initialize_field(e)¶

Initialize field array to zero.

Sets all elements of the complex field array to zero.

Parameters:: e (ndarray) – Complex field array, 3D array (modified in-place)
Returns:: e array is modified in-place
Return type:: None

Notes

In Fortran, this uses OpenMP parallelization when available. In Python, we use NumPy’s efficient zero assignment.

pulsesuite.PSTD3D.typespace.unformatted_write_e(file_handle, e)¶

Write field array in binary format.

Writes the complex field array to a file handle in binary (unformatted) format.

Parameters:

file_handle (file) – Open binary file handle to write to
e (ndarray) – Complex field array, 3D array

Return type:

None

Notes

Uses numpy’s save to write the array in binary format.

pulsesuite.PSTD3D.typespace.unformatted_read_e(file_handle, e)¶

Read field array from binary format.

Reads the complex field array from a file handle in binary (unformatted) format.

Parameters:

file_handle (file) – Open binary file handle to read from
e (ndarray) – Complex field array to populate (modified in-place), 3D array

Returns:

e array is modified in-place

Return type:

None

Notes

Uses numpy’s load to read the array from binary format. The array must already be allocated with the correct shape.

pulsesuite.PSTD3D.typespace.readfield_from_unit(file_handle, e, binmode)¶

Read field array from a file handle.

Reads the complex field array from an open file handle in either binary or text format.

Parameters:

file_handle (file) – Open file handle to read from
e (ndarray) – Complex field array to populate (modified in-place), 3D array
binmode (bool) – If True, read from binary format; if False, read from text format

Returns:

e array is modified in-place

Return type:

None

Notes

For binary mode, uses unformatted_read_e. For text mode, reads real and imaginary parts line by line.

pulsesuite.PSTD3D.typespace.readfield(fnin, e, space, binmode, single, fnspace=None)¶

Read the space structure and field from a file.

Reads the space structure (ss) and the complex field array from a file. Can read from binary or text format, and can read space parameters from the same file or a separate file. The field array is automatically allocated or resized to match the space dimensions.

Parameters:

fnin (str) – Filename to read from, or “stdin” or “-” for stdin
e (ndarray or None) – Complex field array. If None or wrong shape, will be allocated/resized. Modified in-place if provided, or a new array is returned.
space (ss) – Space structure to populate (modified in-place)
binmode (bool) – If True, read from binary format; if False, read from text format
single (bool) – If True, read space parameters from the same file
fnspace (str, optional) – If single is False, read space parameters from this separate file

Returns:

Complex field array. If e was None, returns a new array. If e was provided, returns the same array (modified in-place).

Return type:

ndarray

Notes

The field array is automatically allocated or resized to match GetNx(space), GetNy(space), GetNz(space). After reading space parameters, the field is initialized to zero before reading the actual field data.