ferrodispcalc.vis package

Submodules

ferrodispcalc.vis.grid module

ferrodispcalc.vis.grid.grid_data(atoms: Atoms, data: ndarray, element: list[str], target_size: tuple[int, int, int] | None = None, tol: float = 1.0, axis: tuple[tuple, tuple, tuple] = ((1, 0, 0), (0, 1, 0), (0, 0, 1)), return_coord: bool = False) → ndarray | tuple[ndarray, ndarray]

ferrodispcalc.vis.line_plot module

ferrodispcalc.vis.line_plot.line_profile(data: ndarray, ax: Axes = None, along: str = 'x', savepath: str = None, field_prefix: str = None, call_back: callable = None)

ferrodispcalc.vis.plane_plot module

ferrodispcalc.vis.plane_plot.plane_profile(data: ndarray, save_dir: str | Path = 'plane_plots', relative: bool = True, select: Dict[str, List[int]] | None = None, hot: bool = True, fig_size: str | Tuple[float, float] = 'auto') → None

Plot 2D cross-sections of 3D vector data.

Parameters:

data: np.ndarray

The 4D vector data in (nx, ny, nz, 3) format.

save_dir: str | Path

The directory to save the plots.

relative: bool

Whether to plot the vector in the relative scale (default True).

select: dict, optional

The selected layers to plot. Keys should be ‘x’, ‘y’, ‘z’ (for YZ, XZ, XY planes respectively). e.g., {‘z’: [0, 1], ‘y’: [0]} If None, all layers are plotted.

hot: bool

Whether to plot the angle in the hot colormap (default True).

fig_size: str | tuple

The figure size: ‘auto’, ‘default’, or a (width, height) tuple.

ferrodispcalc.vis.plane_plot.plane_profile_multi(data: ndarray, select: List[str | int | slice | List[int]], save_name: str | Path = 'plane_plots.gif', relative: bool = True, hot: bool = True, fig_size: str | Tuple[float, float] = 'auto', fps: int = 10)

Plot 2D cross-sections of 5D vector data (nframe, nx, ny, nz, 3) and save as a GIF using matplotlib.animation. (使用 matplotlib.animation 绘制 5D 矢量数据的 2D 横截面并另存为 GIF)

Parameters:

data: np.ndarray

The 5D vector data in (nframe, nx, ny, nz, 3) format.

select: list

Defines the plot. Format: [plane_name, layer_index, frame_spec] e.g., [‘xz’, 0, slice(0, None, 2)] -> XZ plane, y_index=0, every 2nd frame.

save_name: str | Path

The output filename (e.g., ‘animation.gif’).

relative: bool

Whether to plot the vector in the relative scale.

hot: bool

Whether to plot the angle in the hot colormap.

fig_size: str | tuple

The figure size: ‘auto’, ‘default’, or a (width, height) tuple.

fps: int

Frames per second for the output GIF.

ferrodispcalc.vis.space_plot module

ferrodispcalc.vis.space_plot.space_animation(data: np.ndarray, coord: np.ndarray | None = None, *, color_by: str = 'dz', cmap: str = 'coolwarm', factor: float = 25.0, projection: str = 'ortho', clim: tuple[float, float] | None=None, select: dict | None = None, cell: np.ndarray | None = None, title: str = '3D Vector Field Animation', show_bounding_box: bool = True, show_axes: bool = True, show_slider: bool = True, show_frame_text: bool = True, plotter: pv.Plotter | None = None, stride: int | Sequence[int] = 1, frame_indices: Sequence[int] | slice | None = None, frame_step: int = 1, fps: float = 20.0, autoplay: bool = True, loop: bool = True, dtype: type | str | np.dtype = <class 'numpy.float32'>) → pv.Plotter

Play a 3-D vector-field animation in a PyVista window.

Two time-dependent input modes are supported:

• Grid mode - data has shape (nframe, nx, ny, nz, 3). Coordinates are generated automatically from grid indices and coord is ignored.

• Point mode - data has shape (nframe, npoint, 3) and coord has shape (npoint, 3).

The scene is created once and updated in-place as frames advance. A slider widget is shown by default for direct frame selection. Keyboard shortcuts are available when more than one frame is selected: space toggles playback, and the left/right arrow keys step backward/forward by one displayed frame.

Parameters:

• data (np.ndarray) – Vector animation data. Expected shape is (nframe, nx, ny, nz, 3) for grid mode or (nframe, npoint, 3) for point mode.

• coord (np.ndarray or None) – Cartesian coordinates (npoint, 3). Required for point mode, ignored for grid mode.

• color_by (str) – Coloring strategy: 'magnitude', 'dx', 'dy', 'dz', 'all' (RGB from components), or 'gradient' (grid mode only).

• cmap (str) – Matplotlib colormap name (ignored when color_by=’all’).

• factor (float) – Arrow scale factor passed to pv.PolyData.glyph.

• projection (str) – 'ortho' for parallel projection, 'persp' for perspective.

• clim (tuple or None) – Colorbar range (vmin, vmax). None updates the scalar range from the current frame.

• select (dict or None) – Region filter in fractional coordinates. Keys are 'x', 'y', 'z'; values are [lo, hi] or None (no filter). In grid mode fractions are computed from grid indices; in point mode cell is required.

• cell (np.ndarray or None) – (3, 3) lattice matrix (rows = lattice vectors). Only needed when select is used in point mode.

• title (str) – Window title.

• show_bounding_box (bool) – Draw a wireframe box around the full point cloud.

• show_axes (bool) – Show orientation axes widget.

• show_slider (bool) – Show a frame slider at the bottom of the window.

• show_frame_text (bool) – Show the current frame index in the upper-left corner.

• plotter (pv.Plotter or None) – Reuse an existing plotter. A new one is created when None.

• stride (int or sequence of int) – Spatial down-sampling. In grid mode, an int applies to all axes and a 3-item sequence applies to x, y and z. In point mode, only an int stride is accepted.

• frame_indices (sequence of int, slice, or None) – Frames to expose in the animation. None selects all frames after applying frame_step.

• frame_step (int) – Temporal down-sampling step used when frame_indices is None; also applied to a slice selection when greater than one.

• fps (float) – Playback rate in displayed frames per second.

• autoplay (bool) – Start playback immediately when the window opens.

• loop (bool) – Restart from the first displayed frame after the last one.

• dtype (type, str, or np.dtype) – Floating dtype used for the per-frame vector arrays passed to PyVista.

Returns:

The plotter instance. When plotter is None, the window is shown before returning.

Return type:

pv.Plotter

ferrodispcalc.vis.space_plot.space_profile(data: np.ndarray, coord: np.ndarray | None = None, *, color_by: str = 'dz', cmap: str = 'coolwarm', factor: float = 25.0, projection: str = 'ortho', clim: tuple[float, float] | None = None, select: dict | None = None, cell: np.ndarray | None = None, title: str = '3D Vector Field', show_bounding_box: bool = True, show_axes: bool = True, plotter: pv.Plotter | None = None) → pv.Plotter

Plot a 3D vector field using PyVista.

Two input modes are supported:

• Grid mode – data has shape (nx, ny, nz, 3). Coordinates are generated automatically from grid indices and coord is ignored.

• Point mode – data has shape (npoint, 3) and coord (also (npoint, 3)) must be provided.

Parameters:

• data (np.ndarray) – Vector data. (nx, ny, nz, 3) for grid mode or (npoint, 3) for point mode.

• coord (np.ndarray or None) – Cartesian coordinates (npoint, 3). Required for point mode, ignored for grid mode.

• color_by (str) – Coloring strategy: 'magnitude', 'dx', 'dy', 'dz', 'all' (RGB from components), or 'gradient' (grid mode only).

• cmap (str) – Matplotlib colormap name (ignored when color_by=’all’).

• factor (float) – Arrow scale factor passed to pv.PolyData.glyph.

• projection (str) – 'ortho' for parallel projection, 'persp' for perspective.

• clim (tuple or None) – Colorbar range (vmin, vmax). None for automatic.

• select (dict or None) – Region filter in fractional coordinates. Keys are 'x', 'y', 'z'; values are [lo, hi] or None (no filter). In grid mode fractions are computed from grid indices; in point mode cell is required.

• cell (np.ndarray or None) – (3, 3) lattice matrix (rows = lattice vectors). Only needed when select is used in point mode.

• title (str) – Window title.

• show_bounding_box (bool) – Draw a wireframe box around the full point cloud.

• show_axes (bool) – Show orientation axes widget.

• plotter (pv.Plotter or None) – Reuse an existing plotter. A new one is created when None.

Returns:

The plotter instance (already shown).

Return type:

pv.Plotter

Module contents

ferrodispcalc.vis.grid_data(atoms: Atoms, data: ndarray, element: list[str], target_size: tuple[int, int, int] | None = None, tol: float = 1.0, axis: tuple[tuple, tuple, tuple] = ((1, 0, 0), (0, 1, 0), (0, 0, 1)), return_coord: bool = False) → ndarray | tuple[ndarray, ndarray]

ferrodispcalc.vis.line_profile(data: ndarray, ax: Axes = None, along: str = 'x', savepath: str = None, field_prefix: str = None, call_back: callable = None)

ferrodispcalc.vis.plane_profile(data: ndarray, save_dir: str | Path = 'plane_plots', relative: bool = True, select: Dict[str, List[int]] | None = None, hot: bool = True, fig_size: str | Tuple[float, float] = 'auto') → None

Plot 2D cross-sections of 3D vector data.

Parameters:

data: np.ndarray

The 4D vector data in (nx, ny, nz, 3) format.

save_dir: str | Path

The directory to save the plots.

relative: bool

Whether to plot the vector in the relative scale (default True).

select: dict, optional

The selected layers to plot. Keys should be ‘x’, ‘y’, ‘z’ (for YZ, XZ, XY planes respectively). e.g., {‘z’: [0, 1], ‘y’: [0]} If None, all layers are plotted.

hot: bool

Whether to plot the angle in the hot colormap (default True).

fig_size: str | tuple

The figure size: ‘auto’, ‘default’, or a (width, height) tuple.

ferrodispcalc.vis.space_animation(data: np.ndarray, coord: np.ndarray | None = None, *, color_by: str = 'dz', cmap: str = 'coolwarm', factor: float = 25.0, projection: str = 'ortho', clim: tuple[float, float] | None=None, select: dict | None = None, cell: np.ndarray | None = None, title: str = '3D Vector Field Animation', show_bounding_box: bool = True, show_axes: bool = True, show_slider: bool = True, show_frame_text: bool = True, plotter: pv.Plotter | None = None, stride: int | Sequence[int] = 1, frame_indices: Sequence[int] | slice | None = None, frame_step: int = 1, fps: float = 20.0, autoplay: bool = True, loop: bool = True, dtype: type | str | np.dtype = <class 'numpy.float32'>) → pv.Plotter

Play a 3-D vector-field animation in a PyVista window.

Two time-dependent input modes are supported:

• Grid mode - data has shape (nframe, nx, ny, nz, 3). Coordinates are generated automatically from grid indices and coord is ignored.

• Point mode - data has shape (nframe, npoint, 3) and coord has shape (npoint, 3).

The scene is created once and updated in-place as frames advance. A slider widget is shown by default for direct frame selection. Keyboard shortcuts are available when more than one frame is selected: space toggles playback, and the left/right arrow keys step backward/forward by one displayed frame.

Parameters:

• data (np.ndarray) – Vector animation data. Expected shape is (nframe, nx, ny, nz, 3) for grid mode or (nframe, npoint, 3) for point mode.

• coord (np.ndarray or None) – Cartesian coordinates (npoint, 3). Required for point mode, ignored for grid mode.

• color_by (str) – Coloring strategy: 'magnitude', 'dx', 'dy', 'dz', 'all' (RGB from components), or 'gradient' (grid mode only).

• cmap (str) – Matplotlib colormap name (ignored when color_by=’all’).

• factor (float) – Arrow scale factor passed to pv.PolyData.glyph.

• projection (str) – 'ortho' for parallel projection, 'persp' for perspective.

• clim (tuple or None) – Colorbar range (vmin, vmax). None updates the scalar range from the current frame.

• select (dict or None) – Region filter in fractional coordinates. Keys are 'x', 'y', 'z'; values are [lo, hi] or None (no filter). In grid mode fractions are computed from grid indices; in point mode cell is required.

• cell (np.ndarray or None) – (3, 3) lattice matrix (rows = lattice vectors). Only needed when select is used in point mode.

• title (str) – Window title.

• show_bounding_box (bool) – Draw a wireframe box around the full point cloud.

• show_axes (bool) – Show orientation axes widget.

• show_slider (bool) – Show a frame slider at the bottom of the window.

• show_frame_text (bool) – Show the current frame index in the upper-left corner.

• plotter (pv.Plotter or None) – Reuse an existing plotter. A new one is created when None.

• stride (int or sequence of int) – Spatial down-sampling. In grid mode, an int applies to all axes and a 3-item sequence applies to x, y and z. In point mode, only an int stride is accepted.

• frame_indices (sequence of int, slice, or None) – Frames to expose in the animation. None selects all frames after applying frame_step.

• frame_step (int) – Temporal down-sampling step used when frame_indices is None; also applied to a slice selection when greater than one.

• fps (float) – Playback rate in displayed frames per second.

• autoplay (bool) – Start playback immediately when the window opens.

• loop (bool) – Restart from the first displayed frame after the last one.

• dtype (type, str, or np.dtype) – Floating dtype used for the per-frame vector arrays passed to PyVista.

Returns:

The plotter instance. When plotter is None, the window is shown before returning.

Return type:

pv.Plotter

ferrodispcalc.vis.space_profile(data: np.ndarray, coord: np.ndarray | None = None, *, color_by: str = 'dz', cmap: str = 'coolwarm', factor: float = 25.0, projection: str = 'ortho', clim: tuple[float, float] | None = None, select: dict | None = None, cell: np.ndarray | None = None, title: str = '3D Vector Field', show_bounding_box: bool = True, show_axes: bool = True, plotter: pv.Plotter | None = None) → pv.Plotter

Plot a 3D vector field using PyVista.

Two input modes are supported:

• Grid mode – data has shape (nx, ny, nz, 3). Coordinates are generated automatically from grid indices and coord is ignored.

• Point mode – data has shape (npoint, 3) and coord (also (npoint, 3)) must be provided.

Parameters:

• data (np.ndarray) – Vector data. (nx, ny, nz, 3) for grid mode or (npoint, 3) for point mode.

• coord (np.ndarray or None) – Cartesian coordinates (npoint, 3). Required for point mode, ignored for grid mode.

• color_by (str) – Coloring strategy: 'magnitude', 'dx', 'dy', 'dz', 'all' (RGB from components), or 'gradient' (grid mode only).

• cmap (str) – Matplotlib colormap name (ignored when color_by=’all’).

• factor (float) – Arrow scale factor passed to pv.PolyData.glyph.

• projection (str) – 'ortho' for parallel projection, 'persp' for perspective.

• clim (tuple or None) – Colorbar range (vmin, vmax). None for automatic.

• select (dict or None) – Region filter in fractional coordinates. Keys are 'x', 'y', 'z'; values are [lo, hi] or None (no filter). In grid mode fractions are computed from grid indices; in point mode cell is required.

• cell (np.ndarray or None) – (3, 3) lattice matrix (rows = lattice vectors). Only needed when select is used in point mode.

• title (str) – Window title.

• show_bounding_box (bool) – Draw a wireframe box around the full point cloud.

• show_axes (bool) – Show orientation axes widget.

• plotter (pv.Plotter or None) – Reuse an existing plotter. A new one is created when None.

Returns:

The plotter instance (already shown).

Return type:

pv.Plotter

ferrodispcalc.vis.use_science_style(enable: bool = True) → None

Enable or disable the SciencePlots style globally.

Parameters:

enable (bool) – True to activate ['science', 'no-latex'], False to revert to matplotlib defaults.