Utils

Here are some useful utility functions. There are SPH kernel functions, mathematical functions, utility functions relating to Snap objects, string functions, and visualization functions.

Kernels

SPH kernels.

plonk.utils.kernels.kernel_cubic(q)

Cubic kernel function.

The form of this function includes the “C_norm” factor. I.e. C_norm * f(q).

Parameters

q – The particle separation in units of smoothing length, i.e. r/h.

Returns

C_norm * f(q) for the cubic kernel.

Return type

float

plonk.utils.kernels.kernel_gradient_cubic(q)

Cubic kernel gradient function.

The form of this function includes the “C_norm” factor. I.e. C_norm * f’(q).

Parameters

q – The particle separation in units of smoothing length, i.e. r/h.

Returns

C_norm * f’(q) for the cubic kernel.

Return type

float

plonk.utils.kernels.kernel_gradient_quintic(q)

Quintic kernel gradient function.

The form of this function includes the “C_norm” factor. I.e. C_norm * f’(q).

Parameters

q – The particle separation in units of smoothing length, i.e. r/h.

Returns

C_norm * f’(q) for the quintic kernel.

Return type

float

plonk.utils.kernels.kernel_gradient_wendland_c4(q)

Wendland C4 kernel gradient function.

The form of this function includes the “C_norm” factor. I.e. C_norm * f’(q).

Parameters

q – The particle separation in units of smoothing length, i.e. r/h.

Returns

C_norm * f’(q) for the Wendland C4 kernel.

Return type

float

plonk.utils.kernels.kernel_quintic(q)

Quintic kernel function.

The form of this function includes the “C_norm” factor. I.e. C_norm * f(q).

Parameters

q – The particle separation in units of smoothing length, i.e. r/h.

Returns

C_norm * f(q) for the quintic kernel.

Return type

float

plonk.utils.kernels.kernel_wendland_c4(q)

Wendland C4 kernel function.

The form of this function includes the “C_norm” factor. I.e. C_norm * f(q).

Parameters

q – The particle separation in units of smoothing length, i.e. r/h.

Returns

C_norm * f(q) for the Wendland C4 kernel.

Return type

float

Math

Utils for math.

plonk.utils.math.average(x, weights, **kwargs)

Average.

Parameters

  • x – The array (N,) to take the norm of. Can be ndarray or pint Quantity.

  • weights – The weights for averaging.

  • **kwargs – Keyword arguments to pass to np.average.

Returns

The average of x.

Return type

ndarray

plonk.utils.math.cross(x, y, **kwargs)

Cross product.

Parameters

  • x – The two arrays (N, 3) to take the cross product of. Can be ndarray or pint Quantity.

  • y – The two arrays (N, 3) to take the cross product of. Can be ndarray or pint Quantity.

  • **kwargs – Keyword arguments to pass to np.cross.

Returns

The cross product of x and y.

Return type

ndarray

plonk.utils.math.distance_from_plane(x, y, z, normal, height=0)

Calculate distance from a plane.

Parameters

  • x (numpy.ndarray) – The x-positions.

  • y (numpy.ndarray) – The y-positions.

  • z (numpy.ndarray) – The z-positions.

  • normal (numpy.ndarray) – The normal vector describing the plane (x, y, z).

  • height (float) – The height of the plane above the origin.

Returns

Return type

The distance from the plane of each point.

plonk.utils.math.norm(x, **kwargs)

Norm of a vector.

Parameters

  • x – The arrays (N, 3) to take the norm of. Can be ndarray or pint Quantity.

  • **kwargs – Keyword arguments to pass to np.linalg.norm.

Returns

The norm of x.

Return type

ndarray

Snap

Utils for snaps.

plonk.utils.snap.add_aliases(snap, filename=None)

Add array aliases to a Snap.

Parameters

  • snap (SnapLike) – The Snap object.

  • config (optional) – The path to a Plonk config.toml file. If None, use the default file.

  • filename (Union[str, Path]) –

plonk.utils.snap.dust_array_names(name, num_dust_species, add_gas=False)

List dust array names.

Parameters

  • name (str) – The base array name, e.g. “dust_density” or “stopping_time”.

  • num_dust_species (int) – The number of dust species.

  • add_gas (bool) – If True add the gas version of the dust name.

Returns

A list of array names with appropriate suffixes.

Return type

List

Examples

Get the dust density strings.

>>> dust_name_list('dust_density', 5)
['dust_density_001',
 'dust_density_002',
 'dust_density_003',
 'dust_density_004',
 'dust_density_005']

Get the dust density strings with gas.

>>> dust_name_list(name='dust_density', num_dust_species=5, add_gas=True)
['gas_density',
 'dust_density_001',
 'dust_density_002',
 'dust_density_003',
 'dust_density_004',
 'dust_density_005']
plonk.utils.snap.gravitational_constant_in_code_units(snap)

Gravitational constant in code units.

Parameters

snap (SnapLike) – The Snap object.

Returns

The gravitational constant in code units.

Return type

float

plonk.utils.snap.vector_array_names(name, add_mag=False)

List vector array names.

Parameters

  • name (str) – The base array name, e.g. “angular_momentum”.

  • add_mag (bool) – If True add the magnitude of the array.

Returns

A list of array names with appropriate suffixes.

Return type

List

Examples

Get the angular momentum strings.

>>> vector_name_list('angular_momentum')
['angular_momentum_x',
 'angular_momentum_y',
 'angular_momentum_z']

Get the angular momentum strings with magnitude.

>>> vector_name_list(name='angular_momentum', add_mag=True)
['angular_momentum_x',
 'angular_momentum_y',
 'angular_momentum_z',
 'angular_momentum_mag']

Strings

Utils for strings.

plonk.utils.strings.is_documented_by(original)

Wrap function to add docstring.

plonk.utils.strings.pretty_array_name(s)

Prettify an array name string.

Parameters

s (str) – The string.

Returns

Return type

str

plonk.utils.strings.time_string(snap, unit, unit_str=None, float_format='.0f')

Generate time stamp string.

Parameters

  • snap – The Snap object.

  • unit (str) – The time unit as a string to pass to Pint. E.g. ‘year’.

  • unit_str (Optional[str]) – The unit string to print. If None, use the value from ‘unit’. Default is None.

  • float_format (str) – The format for the time float value. Default is ‘.0f’.

Return type

str

Examples

Generate a list of strings of snapshot time, like [‘0 yr’, ‘10 yr’, …].

>>> text = [time_string(snap, 'year', 'yr') for snap in snaps]

Or, in terms of an orbital time, like ‘10 orbits’.

>>> plonk.units.define('binary_orbit = 100 years')
>>> time_string(snap, 'binary_orbit', 'orbits')

Visualize

Utils for visualize.

plonk.utils.visualize.cartesian_to_polar(interpolated_data_cartesian, extent_cartesian)

Convert interpolated Cartesian pixel grid to polar coordinates.

Parameters

  • interpolated_data_cartesian (numpy.ndarray) – The interpolated data on a Cartesian grid.

  • extent_cartesian (Tuple[float, float, float, float]) – The extent in Cartesian space as (xmin, xmax, ymin, ymax). It must be square.

Returns

  • interpolated_data_polar – The interpolated data on a polar grid (R, phi).

  • extent_polar – The extent on a polar grid (0, Rmax, 0, 2π).

Return type

Tuple[numpy.ndarray, Tuple[float, float, float, float]]

plonk.utils.visualize.get_extent_from_percentile(snap, x, y, percentile=99, x_center_on=None, y_center_on=None, edge_factor=None)

Get extent from percentile.

Parameters

  • snap (SnapLike) – The Snap object.

  • x (str) – The “x” coordinate.

  • y (str) – The “y” coordinate.

  • percentile (optional) – The percentile used in the calculation. Default is 99.

  • x_center_on (optional) – Center on some x-value. Default is None.

  • y_center_on (optional) – Center on some y-value. Default is None.

  • edge_factor (optional) – Add extra spacing to extent. E.g. to add extra 5%, set this value to 0.05. Default is None.

Returns

The extent of the box as (xmin, xmax, ymin, ymax).

Return type

tuple

plonk.utils.visualize.plot_smoothing_length(snap, indices, fac=1.0, units=None, x='x', y='y', ax=None, **kwargs)

Plot smoothing length around particle.

Also works for plotting the accretion radius on a sink particle.

Parameters

  • snap (SnapLike) – The Snap object.

  • indices (List[int]) – The particle indices.

  • fac (float) – Set the circle to be a multiple “fac” of the smoothing length.

  • units (Union[str, Quantity]) – The distance units.

  • ax (Any) – The matplotlib Axes to plot on.

  • x (str) – The “x” coordinate.

  • y (str) – The “y” coordinate.

  • **kwargs – Keyword arguments to pass to matplotlib PatchCollection.

Returns

A list of matplotlib circles.

Return type

circles

previous

Interpolation