field module

class wakis.field.Field(Nx, Ny, Nz, dtype=float, use_ones=False, use_gpu=False)[source]

Bases: object

Class to handle 3D vector fields stored in a flattened 1D array. Uses lexicographic numbering:

n = 1 + (i-1) + (j-1)*Nx + (k-1)*Nx*Ny len(n) = Nx*Ny*Nz

Parameters

  • Nx (int) – Number of grid points in the x direction.

  • Ny (int) – Number of grid points in the y direction.

  • Nz (int) – Number of grid points in the z direction.

  • dtype (type, optional) – Data type of the field array. Default is float.

  • use_ones (bool, optional) – If True, initialize the field array with ones. Otherwise, zeros. Default is False.

  • use_gpu (bool, optional) – If True, use CuPy for GPU arrays. Default is False.

Nx, Ny, Nz

Grid dimensions.

Type

int

N

Total number of grid points (Nx * Ny * Nz).

Type

int

dtype

Data type of the field array.

Type

type

on_gpu

Whether the field is stored on GPU.

Type

bool

xp

Numpy or cupy module, depending on use_gpu.

Type

module

array

Flattened 1D field array of shape (N*3,).

Type

ndarray

compute_ijk(n)[source]

Compute (i, j, k) indices from a lexico-graphic index.

Parameters

n (int) – Lexico-graphic index.

Returns

i, j, k – 3D indices corresponding to the lexico-graphic index.

Return type

int

copy()[source]

Return a deep copy of the Field object.

Returns

Deep copy of the field.

Return type

Field

property field_x

Return the x-component of the field as a 1D array.

property field_y

Return the y-component of the field as a 1D array.

property field_z

Return the z-component of the field as a 1D array.

from_gpu()[source]

Move the field array from GPU (CuPy) to CPU (NumPy).

Return type

None

from_matrix(mat, key)[source]

Set the specified component from a 3D matrix.

Parameters

  • mat (ndarray) – 3D array of shape (Nx, Ny, Nz).

  • key (int or str) – Component to set: 0 or β€˜x’, 1 or β€˜y’, 2 or β€˜z’.

fromarray(array)[source]

Set the field array from a flattened array.

Parameters

array (ndarray) – Flattened field array of shape (N*3,).

get_abs(as_matrix=True)[source]

Compute the magnitude of the field.

Parameters

as_matrix (bool, optional) – If True, return as a 3D matrix. If False, return as a 1D array.

Returns

abs_field – Magnitude of the field.

Return type

ndarray

inspect(plane='YZ', cmap='bwr', dpi=100, figsize=[8, 6], x=None, y=None, z=None, off_screen=False, handles=False, **kwargs)[source]

Visualize 2D slices of the field components using matplotlib.

Parameters

  • plane ({'XY', 'XZ', 'YZ'}, optional) – Plane to visualize. Default is β€˜YZ’.

  • cmap (str, optional) – Colormap for the plot. Default is β€˜bwr’.

  • dpi (int, optional) – Figure DPI. Default is 100.

  • figsize (list, optional) – Figure size. Default is [8, 6].

  • x (int, slice, or None, optional) – Custom slice indices. If all are not None, use as custom slice.

  • y (int, slice, or None, optional) – Custom slice indices. If all are not None, use as custom slice.

  • z (int, slice, or None, optional) – Custom slice indices. If all are not None, use as custom slice.

  • off_screen (bool, optional) – If True, display the plot off-screen. Default is False.

  • handles (bool, optional) – If True, return (fig, axs) instead of showing. Default is False.

  • **kwargs – Additional keyword arguments for imshow.

Returns

  • fig, axs (tuple, optional) – Returned if handles=True.

  • None – Otherwise.

inspect3D(field='all', backend='pyista', grid=None, xmax=None, ymax=None, zmax=None, bounding_box=True, show_grid=True, cmap='viridis', dpi=100, off_screen=False, handles=False)[source]

Visualize 3D field data on the structured grid using either Matplotlib (voxel rendering) or PyVista (interactive clipping and slicing).

This method provides two complementary visualization backends: - Matplotlib: static voxel plots of the field components (x, y, z)

or all combined, useful for quick inspection, but memory intensive.

  • PyVista: interactive 3D visualization with sliders to dynamically clip the volume along X, Y, and Z, and optional wireframe slices.

Parameters

  • field ({'x', 'y', 'z', 'all'}, optional) – Which field component(s) to visualize. Default is β€˜all’.

  • backend ({'matplotlib', 'pyvista'}, optional) – Visualization backend to use. Default is β€˜pyvista’.

  • grid (object, optional) – Structured grid object to use for visualization. If None, a grid is constructed from the solver’s internal dimensions.

  • xmax (int or float, optional) – Maximum extents in each direction for visualization. Defaults to the full grid dimensions if not specified.

  • ymax (int or float, optional) – Maximum extents in each direction for visualization. Defaults to the full grid dimensions if not specified.

  • zmax (int or float, optional) – Maximum extents in each direction for visualization. Defaults to the full grid dimensions if not specified.

  • bounding_box (bool, optional) – If True, draw a wireframe bounding box of the simulation domain (only used in PyVista backend). Default is True.

  • show_grid (bool, optional) – If True, show wireframe slice planes of the grid during interactive visualization (PyVista backend). Default is True.

  • cmap (str, optional) – Colormap to apply to the scalar field. Default is β€˜viridis’.

  • dpi (int, optional) – Resolution of Matplotlib figures (only for Matplotlib backend). Default is 100.

  • show (bool, optional) – Whether to display the figure/plot immediately. If False in PyVista, exports to field.html instead. Default is True.

  • handles (bool, optional) – If True, return figure/axes (Matplotlib) or the Plotter object (PyVista) for further customization instead of showing directly. Default is False.

Returns

  • fig, axs (tuple, optional) – Returned when backend=’matplotlib’ and handles=True.

  • pl (pyvista.Plotter, optional) – Returned when backend=’pyvista’ and handles=True.

Notes

  • The PyVista backend provides interactive sliders to clip the volume along each axis independently and inspect internal structures of the 3D field.

  • The Matplotlib backend provides a quick static voxel rendering but is limited in interactivity and scalability.

to_gpu()[source]

Move the field array to GPU (CuPy).

Return type

None

to_matrix(key)[source]

Return the specified component as a 3D matrix.

Parameters

key (int or str) – Component to return: 0 or β€˜x’, 1 or β€˜y’, 2 or β€˜z’.

Returns

mat – 3D array of shape (Nx, Ny, Nz) for the selected component.

Return type

ndarray

toarray()[source]

Return the flattened field array.

Returns

array – Flattened field array of shape (N*3,).

Return type

ndarray