sarracen.SarracenDataFrame.render

SarracenDataFrame.render(target: str, x: str | None = None, y: str | None = None, z: str | None = None, xsec: float | None = None, kernel: BaseKernel | None = None, x_pixels: int | None = None, y_pixels: int | None = None, xlim: Tuple[float, float] | None = None, ylim: Tuple[float, float] | None = None, cmap: str | Colormap = 'gist_heat', cbar: bool = True, cbar_kws: dict = {}, cbar_ax: Axes | None = None, ax: Axes | None = None, exact: bool = False, backend: str | None = None, integral_samples: int = 1000, rotation: ndarray | list | Rotation | None = None, rot_origin: ndarray | list | str | None = None, log_scale: bool = False, symlog_scale: bool = False, dens_weight: bool | None = None, normalize: bool = False, hmin: bool = False, **kwargs: Any) → Axes

Render a scalar SPH target variable to a grid plot.

Parameters:

  • data (SarracenDataFrame) – Particle data, in a SarracenDataFrame.

  • target (str) – Column label of the target variable.

  • x (str, optional) – Column labels of the x, y & z directional axes. Defaults to the columns detected in data.

  • y (str, optional) – Column labels of the x, y & z directional axes. Defaults to the columns detected in data.

  • z (str, optional) – Column labels of the x, y & z directional axes. Defaults to the columns detected in data.

  • xsec (float, optional.) – For a 3D dataset, the z value to take a cross-section at. If none, column interpolation is performed.

  • kernel (BaseKernel, optional) – Kernel to use for smoothing the target data. Defaults to the kernel specified in data.

  • x_pixels (int, optional) – Number of pixels present in the final image.

  • y_pixels (int, optional) – Number of pixels present in the final image.

  • xlim (tuple of float, optional) – The starting and ending corners of the final 2D image.

  • ylim (tuple of float, optional) – The starting and ending corners of the final 2D image.

  • vmin (float, optional) – Lower and upper limits of the range of values for the colour bar.

  • vmax (float, optional) – Lower and upper limits of the range of values for the colour bar.

  • cmap (str or Colormap, optional) – The color map to use when plotting a 2D image.

  • cbar (bool, optional) – True if a colorbar should be drawn.

  • cbar_kws (dict, optional) – Keyword arguments to pass to matplotlib.figure.Figure.colorbar().

  • cbar_ax (Axes, optional) – Axes to draw the colorbar in, if not provided then space will be taken from the main Axes.

  • ax (Axes, optional) – The main axes in which to draw the rendered image.

  • exact (bool, optional) – Whether to use exact interpolation of the data. For cross-sections this is ignored. Defaults to False.

  • backend (['cpu', 'gpu'], optional) – The computation backend to use when interpolating this data. Defaults to ‘gpu’ if CUDA is enabled, otherwise ‘cpu’ is used. A manually specified backend in data will override the default.

  • integral_samples (int, optional) – If using column interpolation, the number of sample points to take when approximating the 2D column kernel.

  • rotation (array_like or SciPy Rotation, optional) – The rotation to apply to the data before interpolation. If defined as an array, the order of rotations is [z, y, x] in degrees. Only applies to 3D datasets.

  • rot_origin (array_like or ['com', 'midpoint'], optional) – Point of rotation of the data. Only applies to 3D datasets. If array_like, then the [x, y, z] coordinates specify the point around which the data is rotated. If ‘com’, then data is rotated around the centre of mass. If ‘midpoint’, then data is rotated around the midpoint, that is, min + max / 2. Defaults to the midpoint.

  • log_scale (bool, optional) – Whether to use a logarithmic scale for color coding.

  • symlog_scale (bool, optional) – Whether to use a symmetrical logarithmic scale for color coding (i.e., allows positive and negative values). Optionally add “linthresh” and “linscale” to kwargs to set the linear region and the scaling of linear values, respectively (defaults to 1e-9 and 1, respectively). Only works if log_scale == True.

  • dens_weight (bool, optional) – If True, will plot the target multiplied by the density. Defaults to True for column-integrated views and False for everything else.

  • normalize (bool, optional) – If True, will normalize the interpolation. Defaults to True.

  • hmin (bool, optional) – If True, a minimum smoothing length of 0.5 * pixel size will be imposed. This ensures each particle contributes to at least one grid cell / pixel. Defaults to False (this may change in a future verison).

  • corotation (list, optional) – Moves particles to the co-rotating frame of two location. corotation contains two lists which correspond to the two x, y, z coordinates.

  • kwargs (other keyword arguments) – Keyword arguments to pass to ax.imshow.

Returns:

The resulting matplotlib axes, which contain the 2d rendered image.

Return type:

Axes

Raises:

  • ValueError – If x_pixels or y_pixels are less than or equal to zero, or if the specified x and y minimum and maximums result in an invalid region.

  • KeyError – If target, x, y, mass, density, or smoothing length columns do not exist in data.

Notes

The standard render will interpolate the target quantity, \(A\), from the particles to a pixel grid using the following equation:

\[A_{pixel} = \sum_b \frac{m_b}{\rho_b} A_b W_{ab}(h_b)\]

where \(m\) is the mass, \(\rho\) is the density, and \(W\) is the smoothing kernel with smoothing length, \(h\).

Normalized interpolation divides the above summation by an interpolation of a constant scalar field equal to 1:

\[A_{pixel} = \frac{\sum_b \frac{m_b}{\rho_b} A_b W_{ab}(h_b)} {\sum_b \frac{m_b}{\rho_b} W_{ab}(h_b)}\]

In theory, the denominator will be equal to 1 and dividing by 1 has no impact. In practice, the particle arrangement and the smoothing kernel affects the quality of interpolation. Normalizing by this approximation of 1 helps to account for this.

For when to use normalized interpolation, the advice given by Splash is recommended: in general use it for smoother renderings, but avoid when there are free surfaces, as it can cause them to be over-exaggerated.

Density-weighted interpolation will interpolate the quantity \(\rho A\), that is, the target \(A\) multiplied by the density, \(\rho\). If normalize=True, then density-weighted interpolation will be normalized by the density.

Column-integrated views of 3D data (i.e., xsec=None) will calculate the following:

\[A_{pixel} = \sum_b \frac{m_b}{\rho_b} A_b \int W_{ab}(h_b) dz ,\]

which uses the integral of the kernel along the chosen line of sight.

Exact rendering calculates the volume integral of the kernel through each pixel using the method of Petkova et al (2018) [1]. It only works for the cubic spline kernel.

References