visuals module

visuals module#

Contains geometric shapes and field plotting utilities for visualization.

shapes submodule#

Contains a few helper methods representing colloidal shapes in matplotlib. Includes a class to represent superelliptical shapes. Includes methods to plot them on matplotlib axes using real spatial metrics.

class visuals.shapes.SuperEllipse(ax: float = 1.0, ay: float = 1.0, n: float = 2.0)#

Bases: object

A class to contain helpful methods for characterizing the superellipses used in this module. Superellipses follow the equation:

\[\bigg|\frac{x}{a_x}\bigg|^n + \bigg|\frac{y}{a_y}\bigg|^n = 1\]
Parameters:

  • ax (scalar, optional) – one of the radii of the superellipse, defaults to 1.0

  • ay (scalar, optional) – the other radius of the superellipse, defaults to 1.0

  • n (scalar, optional) – the ‘superellipse parameter’ defines how sharp the corners are. \(n\to\infty\) produces rectangles, \(n=2\) gives ellipses, \(n\to1\) produces rhombuses, defaults to 2.0

Variables:

  • ax – one of the radii of the superellipse, defaults to 1.0

  • ay – the other radius of the superellipse, defaults to 1.0

  • n – the ‘superellipse parameter’ defines how sharp the corners are. \(n\to\infty\) produces rectangles, \(n=2\) gives ellipses, \(n\to1\) produces rhombuses, defaults to 2.0:

property aspect: float#
Returns:

the aspect ratio of the superellipse

Return type:

scalar

property area: float#
Returns:

the area of the superellipse

Return type:

scalar

surface(thetas: ndarray) → ndarray#

returns points along the perimeter of the superellipse associated with polar angles

Parameters:

thetas (ndarray) – an array of polar angles

Returns:

the x- and y-positions of points along the perimeter of the superellipse

Return type:

ndarray

visuals.shapes.flat_patches(pts, orient, shape=<visuals.shapes.SuperEllipse object>, n_resolve=101)#

Generates a list of matplotlib Patches which render SuperEllipse shapes in 2D at specified positions and orientations.

Parameters:

  • pts (ndarray) – an \([N, 2+]\) array of points where each shape should be centered. Only the x- and y-coordinates are used.

  • orient (ndarray) – an \([N, 4]\) array of quaternions specifying the orientation of each shape

  • shape (SuperEllipse, optional) – the shape to be drawn at each point, defaults to a circle of diameter 1.0

  • n_resolve (int, optional) – the number of points to use to resolve the perimeter of each shape, defaults to 101

Returns:

a list of the specified shapes at the specified points and orientations

Return type:

list[Patch]

visuals.shapes.projected_patches(pts, grads, shape=<visuals.shapes.SuperEllipse object>, n_resolve=101, view_dir=array([0, 0, 1]), view_dist=100.0, view_ref='z', parallax=False, centered=False)#

Generates a list of matplotlib Patches which render SuperEllipse shapes in 3D projected onto an embedded 2D surface at specified positions and orientations.

WIP: still needs testing for acircular shapes on surfaces

Parameters:

  • pts (ndarray) – an \([N, 3]\) array of points of each shape in real space

  • grads – an \([N, 3]\) array of vectors specifying the surface gradient (normal vector) at each point

  • shape (SuperEllipse, optional) – the shape to be drawn at each point, defaults to a sphere of radius 0.5

  • n_resolve (int, optional) – the number of points to use to resolve the perimeter of each shape, defaults to 251

  • view_dir (ndarray, optional) – a \([3,]\) vector specifying the viewing direction, defaults to looking down the z-axis

  • view_dist (float, optional) – the distance from the viewer to the origin, defaults to 100.0

  • view_ref (str, optional) – a string specifying which axis should be treated as ‘up’ in the viewing frame, defaults to ‘z’

  • parallax (bool, optional) – if True, particles further away appear smaller. If False, particles closer are scaled to take up a smaller portion of the proected surface, defaults to False

  • centered (bool, optional) – if True, recenters all particles to have median position (0,0) in the projected plane, defaults to False

Returns:

a list of matplotlib patches correctly rotated into place.

Return type:

list[Patch]

visuals.shapes.plot_principal_axes(com: ndarray, gyr: ndarray, ax=None, view_dir=array([0, 0, 1]), **plt_kwargs)#

Plot the principal axes of the gyration tensor using quiver on the provided matplotlib Axes.

Parameters:

  • com (ndarray) – A \([3,]\) center of mass position a in 3D.

  • gyr (ndarray) – The \([3,3]\) gyration tensor in 3D.

  • ax (matplotlib.axes.Axes, optional) – Axis to draw the contours on. If None, a new figure and axis will be created.

  • view_dir (ndarray, optional) – a \([3,]\) vector specifying the viewing direction in 3D, defaults to looking down the z-axis

  • plt_kwargs (dict) – Additional keyword arguments forwarded to matplotlib.axes.Axes.plot() (color, scale, etc)

Returns:

The Axes object after plotting

Return type:

matplotlib.pyplot.Axes

fields submodule#

Contains a few methods to represent external electric fields in matplotlib. Includes a class to represent electrode geometries.

class visuals.fields.Field(n: int = 2, dg: float = 30)#

Bases: object

A class to contain helpful methods for representing fields generated by electrode geometries. The class represents fields as a superposition of nearly harmonic traps. The energy associated with the \(i\) th one of these traps can be written like:

\[U_{{tr,i}} = \frac{{1}}{{2}}k_{{tr,i}}\tan^2\big(r/d_g\big)\approx\frac{{1}}{{2}}k_{{tr,i}}\big(r/d_g\big)^2\]
\[U_{{rot,i}} = \frac{{1}}{{2}}k_{{rot,i}}\sin^2\big(m\Delta\theta\big)\]

Where \(k_{{tr,i}}\) and \(k_{{rot,i}}\) correspond to the \(i\) th translational and rotational energy scales (in kT units), \(d_g\) is the distance between the virtual electrodes (in simulation units), and \(m\) is a symmetry factor corresponding to the particles within the electrode (a rectangle has \(m=1\), a square has \(m=2\), and a disc has \(m=\infty\)). The unitless distance \(r\) and the angle \(\Delta\theta\) are defined relative to an angle \(\theta_i\) which defines the axis along which the harmonic trap drives particle translation, and along which the trap aligns particle orientations:

\[r \equiv \vec{{r_p}}\cdot\hat{{d}}/d_g= \frac{{1}}{{d_g}}\big(x_p\cos\theta_i + y_p\sin\theta_i\big)\]
\[\Delta\theta \equiv \theta_p - \theta_i\]

Where \(x_p\), \(y_p\), \(\theta_p\) are the position and orientation of a particle within the field.

A generic field configuraiton can be represented as a superposition of these harmonic traps:

\[U_{{tr}} = \sum_i U_{{tr,i}} \qquad U_{{rot}} = \sum_i U_{{rot,i}}\]
Parameters:

  • n (int, optional) – number of fields to superimpose, defaults to 2

  • dg (float, optional) – gap between all sets of virtual electrodes (in simulation units), defaults to 30

Variables:

  • k_trans – sets the translational field strengths in kT units constraining particles along each multipole axis, defaults to None

  • k_rot – sets the rotational field strengths in kT units aligning particles along each multipole axis, defaults to None

  • direct – sets the direction (in radians) of each multipole axis, defaults to None, defaults to None

property num_fields: int#
Returns:

number of fields to superimpose

Return type:

int

property electrode_gap: float#
Returns:

gap between all sets of virtual electrodes

Return type:

float

U_trans(xs: ndarray, ys: ndarray, k_trans: list | ndarray = None, direct: list | ndarray = None) → ndarray#

Computes the potential energy of a set of x- and y-positions according to the electrode’s current configuration.

Parameters:

  • xs (np.ndarray) – a set of x-positions (in simulation length units) to calculate energies at

  • ys (np.ndarray) – a set of y-positions (in simulation length units) to calculate energies at

  • k_trans (list | np.ndarray, optional) – sets the translational field strengths in kT units constraining particles along each multipole axis, defaults to None

  • direct (list | np.ndarray, optional) – sets the direction (in radians) of each multipole axis, defaults to None

Returns:

a set of potential energies at each x- and y-position

Return type:

np.ndarray

U_rot(angles: ndarray, k_rot: list | ndarray = None, direct: list | ndarray = None, m: int = 1) → ndarray#

Computes potential energy of a set of particle orientations according to the field’s current configuration.

Parameters:

  • angles (np.ndarray) – a set of orientations (in radians) to compute potential energies at

  • k_rot (list | np.ndarray, optional) – sets the rotational field strengths in kT units aligning particles along each multipole axis, defaults to None

  • direct (list | np.ndarray, optional) – sets the direction (in radians) of each multipole axis, defaults to None, defaults to None

  • m (int, optional) – symmetry factor of the particles, defaults to 1

Returns:

a set of potential energies at each orientation

Return type:

np.ndarray

update_from_gsd(frame: Frame)#

Reads field parameters from a GSD frame log and updates the current Field instance.

Parameters:

frame (gsd.hoomd.Frame) – A GSD frame containing field parameters in its log.

classmethod create_from_gsd(frame: Frame)#

Reads field parameters from a GSD frame log and returns a Field instance.

Parameters:

frame (gsd.hoomd.Frame) – A GSD frame containing field parameters in its log.

Returns:

A Field instance initialized with parameters from the frame log.

Return type:

Field

visuals.fields.contour_PEL(ax=None, field: Field = <visuals.fields.Field object>, levels=None, width=None, height=None, **contour_kwargs)#

Places a contour plot of the translational potential energy landscape contained in a Field instance on the provided Axis.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axis to draw the contours on. If None, a new figure and axis will be created.

  • field (Field, optional) – An Field instance which contains the current field conditions (strength, shape). Defaults to a quadrupolar field set to ~2.5 volts (~k=150kT).

  • levels (array-like, optional) – Contour levels to draw. If None, levels are automatically determined from the potential.

  • width (float, optional) – The width of each frame, so as to correcly draw contour lines over the whole simulation box. defaults to dg

  • height (float, optional) – The height of each frame, so as to correcly draw contour lines over the whole simulation box. defaults to dg

  • contour_kwargs (dict) – Additional keyword arguments forwarded to matplotlib.axes.Axes.contour() (colors, linewidths, etc)

Returns:

The ContourSet object created by Axes.contour().

Return type:

matplotlib.contour.ContourSet

visuals.fields.spectral_PEL(ax=None, field: Field = <visuals.fields.Field object>, width=None, height=None, **pcolormesh_kwargs)#

“Places a colorm-mapped plot of the translational potential energy landscape contained in an Field instance on the provided Axis. Regions outside the virtual electrode gap or outside the normalization range are mapped to none. coloring defaults to the Spectral colormap on a 200kT scale, but these are configurable via pcolormesh_kwargs.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axis to draw the contours on. If None, a new figure and axis will be created.

  • field (Field, optional) – A Field instance which contains the current field conditions (strength, shape). Defaults to a quadrupolar field set to ~2.5 volts (~k=150kT).

  • width (float, optional) – The width of each frame, so as to correcly draw contour lines over the whole simulation box. defaults to dg

  • height (float, optional) – The height of each frame, so as to correcly draw contour lines over the whole simulation box. defaults to dg

  • pcolormesh_kwargs (dict) – Additional keyword arguments forwarded to matplotlib.axes.Axes.pcolormesh() (cmap, norm, etc)

Returns:

The QuadMesh returned by Axes.pcolormesh().

Return type:

matplotlib.collections.QuadMesh

visuals.fields.PEL_arrows(ax=None, field: Field = <visuals.fields.Field object>, pts=None, **quiver_kwargs)#

Draw the force at a point is computed from the translational harmonic traps in Field as F = -\nabla U and draws a quiver on the provided Axis.

Parameters:

  • ax (matplotlib.axes.Axes, optional) – Axis to draw the contours on. If None, a new figure and axis will be created.

  • field (Field, optional) – A Field instance which contains the current field conditions (strength, shape). Defaults to a quadrupolar field set to ~2.5 volts (~k=150kT).

  • pts (ndarray, optional) – An [N x 2] array of points (in simulation length units) at which to evaluate and draw force vectors. If None, a default set of points is generated automatically.

  • quiver_kwargs (dict) – Additional keyword arguments forwarded to matplotlib.axes.Axes.quiver() (color, scale, etc)

Returns:

The Quiver object returned by Axes.quiver().

Return type:

matplotlib.quiver.Quiver