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
- 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
- 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
- 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
- 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
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
- 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
- plonk.utils.snap.vector_array_names(name, add_mag=False)¶
List vector array names.
- Parameters
- 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.
- plonk.utils.strings.time_string(snap, unit, unit_str=None, float_format='.0f')¶
Generate time stamp string.
- Parameters
- Return type
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
- 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
- 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
- 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