quatica.visualization
quatica.visualization
Visualizer
plot_angular_accel(t_path, q_path, *, label='', ax=None)
staticmethod
Plot a simple discrete angular acceleration magnitude estimate.
If omega_k is estimated at midpoints, this plots
(|\Delta\omega/\Delta t|) on the corresponding grid.
plot_angular_speed(t_path, q_path, *, label='', ax=None)
staticmethod
Plot (|\omega(t)|) from a sampled quaternion trajectory.
Uses quatica.qtraj.estimate_omega for the discrete log-map estimate.
plot_convergence_comparison(data_dict, title='Convergence Comparison', xlabel='Iteration', ylabel='Residual', logscale=True, save_path=None)
staticmethod
Plot convergence comparison for multiple algorithms/variants.
plot_covariances(covariances, title='Covariance Deviation', subtitle='')
staticmethod
Plot covariance deviation ||AX - I|| or ||XA - I|| over iterations.
Visualizes how well the computed pseudoinverse satisfies the covariance conditions during Newton-Schulz iterations.
Parameters:
covariances : list[float] List of covariance deviation values over iterations title : str, optional Main plot title (default: "Covariance Deviation") subtitle : str, optional Additional subtitle text (default: "")
Notes:
Uses logarithmic scale to track convergence. The covariance deviation measures how close XA (or AX) is to the identity matrix.
plot_quaternion_trajectories_on_s2(paths, *, keyframes=None, v0=(1.0, 0.0, 0.0), sphere_alpha=0.08, title='Trajectory of rotated unit vector on $S^2$', figsize=(8.5, 6.5), save_path=None, dpi=300, show=True)
staticmethod
Plot one or more quaternion trajectories as curves on S^2.
Parameters
paths:
Mapping {label: q_path} where each q_path is a sequence of unit quaternions.
keyframes:
Optional keyframe quaternions to show as markers (rotating the same v0).
v0:
Reference vector used for the S^2 embedding.
sphere_alpha:
Transparency of the unit sphere surface.
title:
Plot title.
figsize:
Figure size.
save_path:
If provided, save the figure to this path.
dpi:
Save DPI.
show:
Whether to display the figure.
plot_residuals(residuals, title='Residual Norms', subtitle='')
staticmethod
Plot Moore-Penrose residual norms over iterations.
Creates a logarithmic plot showing the convergence behavior of different residual types during pseudoinverse computation.
Parameters:
residuals : dict[str, list[float]] Dictionary mapping residual names to their values over iterations title : str, optional Main plot title (default: "Residual Norms") subtitle : str, optional Additional subtitle text (default: "")
Notes:
Uses semilogy scale to better visualize exponential convergence patterns typical in iterative pseudoinverse algorithms.
quaternion_path_on_s2(q_path, v0=(1.0, 0.0, 0.0))
staticmethod
Map a quaternion trajectory to a curve on the unit sphere S^2.
We rotate a fixed unit vector v0 by each quaternion in q_path; the
rotated vector lives on the unit sphere (S2\subset\mathbb{R}3).
Parameters
q_path: Sequence of unit quaternions. v0: Reference 3D vector to rotate (default: e1).
Returns
np.ndarray:
Array of shape (len(q_path), 3) with unit-norm vectors.
set_axes_equal_3d(ax)
staticmethod
Set equal scaling on a 3D axis.
Matplotlib's 3D axes do not enforce equal aspect ratio by default, which can make spheres look like ellipsoids. This helper adjusts limits so x/y/z ranges match.
visualize_matrix(A, component=0, cmap='viridis', title='Matrix Component Heatmap', subtitle='')
staticmethod
Heatmap of a chosen quaternion component (0=w, 1=x, 2=y, 3=z).
Displays a specific quaternion component as a 2D heatmap to visualize the structure and patterns within the matrix.
Parameters:
A : np.ndarray or SparseQuaternionMatrix Input quaternion matrix component : int, optional Quaternion component to visualize: 0=w, 1=x, 2=y, 3=z (default: 0) cmap : str, optional Matplotlib colormap name (default: 'viridis') title : str, optional Main plot title (default: "Matrix Component Heatmap") subtitle : str, optional Additional subtitle text (default: "")
Notes:
Automatically handles both dense and sparse quaternion matrices by converting sparse matrices to dense format for visualization.
visualize_matrix_abs(A, cmap='viridis', title='Matrix Absolute Value', subtitle='')
staticmethod
Heatmap of quaternion matrix absolute values |q| = sqrt(w² + x² + y² + z²).
Displays the magnitude of each quaternion entry as a 2D heatmap, providing insight into the overall structure and numerical behavior.
Parameters:
A : np.ndarray or SparseQuaternionMatrix Input quaternion matrix cmap : str, optional Matplotlib colormap name (default: 'viridis') title : str, optional Main plot title (default: "Matrix Absolute Value") subtitle : str, optional Additional subtitle text (default: "")
Notes:
The absolute value (magnitude) is computed as the quaternion norm, which is invariant under quaternion rotations and provides a scalar measure of quaternion "size".
visualize_schur_structure(T, title='Schur Form Structure', subtitle='', threshold=1e-12)
staticmethod
Visualize the structure of a Schur form matrix T and compute structure metrics.
Returns:
| Type | Description |
|---|---|
Tuple[float, float]
|
Tuple of (below_diagonal_max, subdiagonal_max) for quantitative analysis |
visualize_tensor_slice(T, mode=0, slice_idx=0, cmap='viridis', title='Tensor Slice', show_abs=True)
staticmethod
Visualize a 2D slice of a quaternion tensor T(I×J×K).