coloring module

Contents

coloring module#

Builds methods from calc into a framework of classes and subclasses which process particle data (in the form of gsd frames) into lists of colors based on reaction coordiantes.

base submodule#

Base color scheming module for visualizing particle simulation data. Provides basic color definitions, color mixing functions, and a base class for defining coloring schemes based on particle state.

coloring.base.mcolor(col)#
coloring.base.color_gradient(c1=array([1., 1., 1., 1.]), c2=array([1., 0., 0., 1.]))#

Create a color gradient mapping function between two colors.

Parameters:

  • c1 (np.ndarray, optional) – The starting color, defaults to white

  • c2 (np.ndarray, optional) – The ending color, defaults to red

Returns:

a function that maps a scalar field in [0,1] to colors between c1 and c2

Return type:

function

coloring.base.color_blender(c00=array([1., 1., 1., 1.]), c01=array([1., 0., 0., 1.]), c10=array([0., 0., 1., 1.]), c11=array([1., 0., 1., 1.]))#

Create a color blending function based on two scalar fields.

Parameters:

  • c00 (np.ndarray, optional) – Color at (0,0), defaults to white

  • c01 (np.ndarray, optional) – Color at (0,1), defaults to red

  • c10 (np.ndarray, optional) – Color at (1,0), defaults to blue

  • c11 (np.ndarray, optional) – Color at (1,1), defaults to purple

Returns:

a function that maps two scalar fields in [0,1]x[0,1] to colors blended between the four corner colors

Return type:

function

class coloring.base.ColorBase(shape: SuperEllipse = None, dark: bool = True)#

Bases: object

Base class for particle coloring schemes.

Provides basic infrastructure for coloring particles based on their state. Supports both dark and light background themes (grey and white particles respectively).

StateColor has a snap attribute that caches the last GSD frame used for coloring, to avoid redundant computations.

StateColor subclasses should implement the calc_state(), local_colors() and state_string() methods to provide specific coloring logic and state descriptions.

Parameters:

  • shape (SuperEllipse) – Particle geometry used for calculations, defaults to a sphere of diameter 1.0

  • dark (bool, optional) – Whether to use a dark background theme, defaults to True

Variables:

ci – Canonical scalar field (length N) that will be mapped to colors. Subclasses should set this in calc_state().

property snap: Frame#

Get the current GSD frame used for coloring.

property num_pts: int#

Get the number of particles in the current frame.

property shape: SuperEllipse#

Get the shape used for coloring.

Returns:

The particle geometry used by this style

Return type:

SuperEllipse

calc_state()#

Calculate the state of the color mapping. Subclasses will overwrite by storing reaction coordinates.

local_colors(snap: Frame = None)#

Generate colors for each particle based on local properties. Will not recalculate if the frame matches the cached one.

Parameters:

snap (gsd.hoomd.Frame) – GSD frame containing particle data

Returns:

Array of RGBA colors for each particle

Return type:

ndarray

state_string(snap: Frame = None)#

Generate descriptive string about the system state. Will not recalculate if the frame matches the cached one.

Parameters:

snap (gsd.hoomd.Frame) – GSD frame containing particle data

Returns:

Descriptive string about the system state

Return type:

str

extxyz(snap: Frame = None) → str#

Generate an string representation of the current frame to be written to an Ovito-compatible extended xtz (.extxyz) file. Each consists of a standardized header and a list of particle properties per line:

Code-block::

none N Lattice=”a1 a2 a3 b1 b2 b3 c1 c2 c3” Origin=”ox oy oz” pbc=”F F F” Time=step Properties=type:I:1:pos:R:3:orientation:R:4:shape_asphericity:R:3:color:R:3 Comment=”state description” type x y z ox oy oz ow ax ay az r g b …

Parameters:

snap (gsd.hoomd.Frame) – GSD frame containing particle data

Returns:

string representation of the frame in .extxyz format

Return type:

string

class coloring.base.ColorBlender(c_func: callable, mainstyle: ColorBase, otherstyle: ColorBase)#

Bases: ColorBase

Blend two coloring styles using a two-argument color blending function.

This helper composes two ColorBase instances and a blending callable that accepts two scalar fields (the ci arrays of the two styles) and returns an array of RGBA colors. The blender delegates state computation to both styles and then applies c_func() to their computed scalar fields.

Parameters:

  • c_func (callable) – Callable accepting two scalar fields (x, y) and returning RGBA colors.

  • mainstyle (ColorBase) – Primary coloring style whose scalar field will be used as the first blend axis.

  • otherstyle (ColorBase) – Secondary coloring style whose scalar field will be used as the second blend axis.

Variables:

  • s1 – The primary ColorBase instance (same as mainstyle).

  • s2 – The secondary ColorBase instance (same as otherstyle).

  • c_func – The blending callable used to combine s1.ci and s2.ci into colors.

calc_state()#

Compute and cache the state for both constituent styles.

This delegates to the two composed ColorBase instances and ensures their ci fields are up-to-date. The blender does not itself store additional state beyond the two styles.

Returns:

None

local_colors(snap: Frame = None)#

Return blended RGBA colors for the provided (or cached) frame.

If snap is provided the underlying styles will be updated with that frame before blending. The function c_func() is expected to accept two scalar fields (s1.ci, s2.ci) and return an (N,4) RGBA array.

Parameters:

snap (gsd.hoomd.Frame, optional) – optional GSD frame to compute colors for

Returns:

(N,4) array of RGBA colors produced by blending

Return type:

ndarray

state_string(snap: Frame = None)#

Return a combined descriptive string from both styles.

If snap is provided the underlying styles will be updated with that frame before the strings are requested. The returned string is the primary style’s state_string followed by the secondary’s, separated by a newline.

Parameters:

snap (gsd.hoomd.Frame, optional) – optional GSD frame to compute state strings for

Returns:

Combined human-readable state description

Return type:

str

morphcolor submodule#

Color schemes for morphology-based reaction coordinate visualizations.

class coloring.morphcolor.ColorEta0(shape: SuperEllipse = None, dark: bool = True, jac='x')#

Bases: ColorBase

Color all particles by the central area fraction.

This style computes a single scalar value for the central area fraction (\(\eta_0\)) via central_eta and applies a single-parameter color gradient to every particle.

Parameters:

  • shape (SuperEllipse) – particle geometry

  • dark (bool, optional) – use dark theme if True

  • jac (str, optional) – Jacobian mode passed to central_eta

Variables:

  • eta0 – The central area fraction computed from particle positions and box.

  • ci – Length-N numpy array containing eta0 repeated for every particle; used by ColorBase.local_colors.

calc_state()#

Caclulate the central area fraction using central_eta.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(\eta_0 = 0.00\)”.

Return type:

str

class coloring.morphcolor.ColorRg(shape: SuperEllipse = None, calc_tensor=True, Rg_norm=1.0, dark: bool = True)#

Bases: ColorBase

Color all particles by the ensemble radius of gyration.

This style computes a single scalar value for the ensemble radius of gyration (\(R_g\)) via gyration_radius and applies a single-parameter color gradient to every particle.

Alternatively, and more expensively, users can pass calc_tensor=True to involve the full gyration tensor via gyration_tensor eigenvalues in the calculation.

Particles are colored according to the global radius of gyration, normalized by a user-defined factor rg_norm: ci = 2 - rg/rg_norm.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • calc_tensor (bool, optional) – if True, use the gyration tensor eigenvalues to compute \(R_g\)

  • Rg_norm (scalar) – Normalization factor for \(R_g\) to compute color index, defaults to 1.0

  • dark (bool, optional) – use dark theme if True

Variables:

  • rg – The radius of gyration computed from particle positions.

  • gyr – (if calc_tensor=True): The gyration tensor computed from particle positions.

  • ci – Length-N numpy array containing rg repeated for every particle; used by ColorBase.local_colors.

calc_state()#

Caclulate the radius of gyration using either radius_of_gyration, or by taking the eigenvalues of gyration_tensor.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(R_g/2a = 0.00\)”.

Return type:

str

class coloring.morphcolor.ColorCirc(shape: SuperEllipse = None, dark: bool = True)#

Bases: ColorRg

Color all particles by their ensemble ‘circiularity’.

This style computes a single scalar value for the ensemble circularity \(c\) via circularity and applies a single-parameter color gradient to every particle.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • dark (bool, optional) – use dark theme if True

Variables:

  • circ – The circularity computed from particle positions.

  • ci – Length-N numpy array containing circ repeated for every particle; used by ColorBase.local_colors.

calc_state()#

Calculate the ensemble circularity using circularity.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(c = 0.00\)”.

Return type:

str

class coloring.morphcolor.ColorEpsPhase(shape: SuperEllipse = None, shift=0.5, dark: bool = True)#

Bases: ColorRg

Color all particles by the complex phase of their ensemble ‘ellipticity’.

This style computes a single complex value for the ensemble ellipticity \(\varepsilon\) via ellipticity and applies a HSV color wheel to the complex phase single-parameter color gradient to every particle.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • dark (bool, optional) – use dark theme if True

Variables:

  • eps – The ellipticity computed from particle positions.

  • ci – Length-N numpy array containing eps repeated for every particle; used by ColorBase.local_colors.

calc_state()#

Calculate the ensemble ellipticity using ellipticity.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(\varepsilon = 0.00\exp[0.00i\pi]\)”.

Return type:

str

paticcolor submodule#

Color schemes for nematic and tetratic orientational order.

Provides simple coloring classes that map p-atic magnitude, phase, defects and global summaries into RGB colors. Classes support dark/light themes.

class coloring.paticcolor.ColorS2(shape: SuperEllipse = None, dark: bool = True)#

Bases: ColorBase

Color particles by local nematic magnitude.

Uses local_patic to compute a local nematic order parameter (\(S_2\)) around each particle and maps its magnitude through a white->red (or grey->red) gradient.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • dark (bool, optional) – use dark theme if True

Variables:

  • ori – Complex director field (exp(i*theta)) computed from orientations

  • nem_g – Global nematic order (complex scalar) computed by global_patic.

  • nem_l – Local nematic order per particle (complex array) computed by local_patic.

  • nei – Neighborhood boolean matrix used to compute local order.

  • ci – Real-valued scalar field (abs(nem_l)) used by ColorBase.local_colors.

calc_state()#

Calculate global and local nematic order parameters.

This computes particle orientations, the global nematic order via global_patic and the local nematic order via local_patic. It also determines neighbors using neighbors so callers can inspect nei.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(\langle S_2\rangle = 0.00\)”.

Return type:

str

class coloring.paticcolor.ColorS2Phase(shape: SuperEllipse = None, dark: bool = True, shift: float = 0.0)#

Bases: ColorS2

Color particles by the phase angle of the local nematic director using a rainbow wheel.

This style converts the complex local nematic order into a phase in [0,1] (optionally shifted) and maps it to an HSV rainbow via the color mapper.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • dark (bool) – use dark theme if True

  • shift (float) – Phase offset (0-1) in color mapping

Variables:

ci – Phase per particle in [0,1] used by ColorBase.local_colors.

calc_state()#

Compute parent state then cache the per-particle phase.

Relies on local_patic populated by the parent implementation; converts complex local order to a normalized phase.

class coloring.paticcolor.ColorS2G(shape: SuperEllipse = None, dark: bool = True)#

Bases: ColorS2

Color all particles uniformly by global nematic order.

This style computes the global nematic magnitude (\(S_{2,g}\)) and exposes a uniform scalar ci so all particles receive the same color.

Parameters:

  • shape (SuperEllipse) – particle geometry

  • dark (bool, optional) – use dark theme if True

Variables:

  • nem_g – Global nematic order (complex scalar)

  • ci – Length-N array filled with abs(nem_g) used by ColorBase.local_colors.

calc_state()#

Compute parent state then expose the uniform scalar based on the global magnitude.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(S_{2,g} = 0.00\)”.

Return type:

str

class coloring.paticcolor.ColorT4(shape: SuperEllipse = None, dark: bool = True)#

Bases: ColorBase

Color particles by local tetratic magnitude (\(T_4\)) using an orange gradient.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • dark (bool, optional) – use dark theme if True

Variables:

  • ori – Complex director field (exp(i*theta)) computed from orientations

  • tet_g – Global tetratic order (complex scalar)

  • tet_l – Local tetratic order per particle (complex array)

  • nei – Neighborhood boolean matrix used to compute local order.

  • ci – Real-valued scalar field (abs(tet_l)) used by ColorBase.local_colors.

calc_state()#

Compute tetratic global and local order.

Uses global_patic and local_patic (with p=4) to compute the tetratic order parameters and neighbor structure.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(\langle T_4\rangle = 0.00\)”.

Return type:

str

class coloring.paticcolor.ColorT4G(shape: SuperEllipse = None, dark: bool = True)#

Bases: ColorT4

Color all particles uniformly by global tetratic order (\(T_{4,g}\)).

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to a sphere of diameter 1.0

  • dark (bool, optional) – use dark theme if True

Variables:

  • tet_g – Global tetratic order (complex scalar)

  • ci – Length-N array filled with abs(tet_g) used by ColorBase.local_colors.

calc_state()#

Compute parent state then expose the uniform scalar based on the global tetratic magnitude.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(T_{4,g} = 0.00\)”.

Return type:

str

bondcolor submodule#

Color schemes for order-parameter visualizations.

Provides coloring classes that map local and global bond-order, connectivity and defect measures into RGB colors. Classes support dark/light themes and projected geometries.

class coloring.bondcolor.ColorBondOrder(order: int = 6, shape: SuperEllipse = None, surface_normal: callable = None, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, calc_3d: bool = False, dark: bool = True)#

Bases: ColorBase

Color particles by local n-fold bond-orientational order. .

This class computes per-particle bond-orientational order \(\psi_{n,j}\) (complex numbers). In 2d, It supports flat, projected and anisotropic (stretched) calculations and sets a canonical scalar ci to the magnitude the local bond-order paramter \(|\psi_{n,j}|\)).

Alternatively, users can specify this class to calculate per-particle 3d Steinhardt bond order \(q_{lm,j}\) (complex arrays). In this case the canonica scalar ci is set to the rotationally invariant local bond-order parameter: \(q_{l,j} = \sqrt{\frac{4\pi}{2l+1}\sum_m|q_{lm,j}|^2}\).

The ci field is then mapped to white->red / grey->red color gradients.

Parameters:

  • order (int, optional) – Bond-order symmetry, defaults to 6 (though 4 is also common)

  • shape (SuperEllipse, optional) – Particle geometry, defaults to a sphere with diameter 1.0

  • surface_normal (callable, optional) – Surface normal function for optional projected calculations, defaults to None

  • nei_cutoff (scalar, optional) – Dimensionless neighbor cutoff distance (in units of particle diameter), defaults to DEFAULT_CUTOFF (halfway between first coodination shells in 2D)

  • periodic (bool, optional) – whether to apply periodic boundary conditions during neighbor search, default to False

  • calc_3d (bool, optional) – whether to compute full 3d Steinhardt bond order, default to False

  • dark (bool, optional) – whether to use the dark theme, default to True

Variables:

  • bond_order – Bond-order calculation method used internally

  • nei – Neighbor boolean array/matrix used for local averages

  • rel_rot – (if applicable) Relative rotation factors for projected calculations

  • qlm – (if applicable) Per-particle, per-m spherical harmonic bond-order components

  • psi – (if applicable) Per-particle complex bond-order values

  • ci – Real-valued scalar field (i.e. abs(psi)) used by ColorBase.local_colors().

property surface_normal: callable#
Returns:

Surface normal function for projected calculations.

Return type:

callable | None

calc_state()#

Compute bond-order and neighbor structures and store to self.

Implementation notes:

  • For spherical/disc particles this uses flat_bond_order. In this case the class variables rel_rot and qlm are set to None.

  • For projected geometries it uses projected_bond_order and computes a tangent connection via tangent_connection. In this case the class variable qlm is set to None.

  • For anisotropic particles it uses the stretched variants (stretched_neighbors and stretched_bond_order). In this case the class variables rel_rot and qlm are set to None.

  • In 3d, this uses steinhardt_bond_order. In this case the class variables rel_rot and psi are set to None.

  • If periodic is True, applies periodic boundary conditions during neighbor search using expand_around_pbc. IMPORTANT: this means that the instance variables have size N’ instead of size N. ci fields automatically adjust for this, but other instance variables (like psi) may need to be indexed accordingly.

In 2d the scalar field ci is set to the per-particle magnitude abs(self.psi). Whereas in 3d it’s set to the rotationally invariant local bond-order parameter: \(q_l\). In either istances the base mapping (ColorBase.local_colors) can be applied unchanged.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string i.e. “\(\langle|\psi_n|\rangle=0.00\) “ / “\(\langle q_n \rangle=0.00\)”.

Return type:

str

class coloring.bondcolor.ColorPsiG(order: int = 6, shape: SuperEllipse = None, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, dark: bool = True)#

Bases: ColorBondOrder

Color all particles by the global 2d bond-order magnitude: \(|\langle\psi_n\rangle|\).

Parameters:

  • order (int, optional) – Bond-order symmetry, defaults to 6 (though 4 is also common)

  • shape (SuperEllipse, optional) – Particle geometry, defaults to a sphere with diameter 1.0

  • nei_cutoff (scalar, optional) – Dimensionless neighbor cutoff distance (in units of particle diameter), defaults to DEFAULT_CUTOFF (halfway between first coodination shells in 2D)

  • periodic (bool, optional) – whether to apply periodic boundary conditions during neighbor search, default to False

  • dark (bool, optional) – whether to use the dark theme

Variables:

  • psi_g – Global average bond-order magnitude

  • ci – Length-N array filled with psi_g used by ColorBase.local_colors.

calc_state()#

Calculate both global and local bond-order parameters and expose a uniform scalar field (ci).

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string i.e. “\(|\langle\psi_n\rangle|=0.00\)”.

Return type:

str

class coloring.bondcolor.ColorPsiPhase(order: int = 6, shape: SuperEllipse = None, surface_normal: callable = None, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, shift: float = 0.6, dark: bool = True)#

Bases: ColorBondOrder

Color particles by phase (angle) of bond-order using a rainbow map.

Converts the complex local \(\psi_n\) value into a phase and maps that phase to hue using an HSV/rainbow map. The shift parameter rotates the hue wheel for better visual separation in some datasets.

Parameters:

  • order (int, optional) – Bond-order symmetry, defaults to 6 (though 4 is also common)

  • shape (SuperEllipse, optional) – Particle geometry, defaults to a sphere with diameter 1.0

  • surface_normal (callable, optional) – Surface normal function for optional projected calculations, defaults to None

  • nei_cutoff (scalar, optional) – Dimensionless neighbor cutoff distance (in units of particle diameter), defaults to DEFAULT_CUTOFF (halfway between first coodination shells in 2D)

  • periodic (bool, optional) – whether to apply periodic boundary conditions during neighbor search, default to False

  • shift (float) – Phase offset in color mapping (0-1 scale)

  • dark (bool, optional) – whether to use the dark theme

Variables:

ci – Per-particle normalized phase in [0,1] used by ColorBase.local_colors.

calc_state()#

Compute parent state then cache the per-particle phase into ci.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string i.e. “\(|\langle\psi_n\rangle|=0.00\)”.

Return type:

str

class coloring.bondcolor.ColorQG(order: int = 6, shape: SuperEllipse = None, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, q_norm: float = 0.57, dark: bool = True)#

Bases: ColorBondOrder

Color all particles by the global 3d rotationally invariant steinhardt bond-order magnitude: \(Q_{l} = \sqrt{\frac{4\pi}{2l+1}\sum_m|\langle q_{lm,j}\rangle|^2}\).

Parameters:

  • order (int, optional) – Bond-order symmetry, defaults to 6 (though 4 is also common)

  • shape (SuperEllipse, optional) – Particle geometry, defaults to a sphere with diameter 1.0

  • nei_cutoff (scalar, optional) – Dimensionless neighbor cutoff distance (in units of particle diameter), defaults to DEFAULT_CUTOFF (halfway between first coodination shells in 2D)

  • periodic (bool, optional) – whether to apply periodic boundary conditions during neighbor search, default to False

  • q_norm (float, optional) – Normalization factor to scale bond-order magnitude for coloring, defaults to 0.57

  • dark (bool, optional) – whether to use the dark theme

Variables:

  • q_g – Global average bond-order magnitude

  • ci – Length-N array filled with q_g/q_norm used by ColorBase.local_colors.

calc_state()#

Calculate both global and local bond-order parameters and expose a uniform scalar field (ci).

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string i.e. “\(Q_l=0.00\)”.

Return type:

str

class coloring.bondcolor.ColorConn(order: int = 6, shape: SuperEllipse = <visuals.shapes.SuperEllipse object>, surface_normal: callable = None, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, calc_3d: bool = False, norm: float = None, crystallinity_threshold: float = None, dark: bool = True)#

Bases: ColorBondOrder

Color particles by local crystal connectivity (i.e. C6) for flat, stretched, projected, and 3D systems.

Uses crystal_connectivity applied to the previously computed psi / qlm and neighbor structure. The resulting connectivity is exposed as ci for the base color mapping (white->blue / grey->blue).

Parameters:

  • order (int, optional) – Bond-order symmetry

  • shape (SuperEllipse, optional) – Particle geometry, defaults to a sphere with diameter 1.0

  • surface_normal (callable, optional) – Surface normal function for optional projected calculations, defaults to None

  • nei_cutoff (scalar, optional) – Dimensionless neighbor cutoff distance (in units of particle diameter), defaults to DEFAULT_CUTOFF (halfway between first coodination shells in 2D)

  • periodic (bool, optional) – whether to apply periodic boundary conditions during neighbor search, default to False

  • calc_3d (bool, optional) – whether to compute full 3d Steinhardt bond order for connectivity, default to False

  • norm (float, optional) – Normalization factor for connectivity calculation, defaults to order in 2d and 2*order in 3d

  • crystallinity_threshold (float, optional) – Threshold for considering a particle “crystalline” in connectivity calculation, defaults to 0.32 in 2d and 0.5 in 3d

  • dark (bool, optional) – whether to use the dark theme

Variables:

  • connectivity – Connectivity calculation method used internally

  • con – Per-particle connectivity values

  • ci – Per-particle scalar connectivity used by ColorBase.local_colors().

calc_state()#

Compute connectivity on top of bond-order and store to self.

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(\langle C_n\rangle=0.00\)”.

Return type:

str

class coloring.bondcolor.ColorConnG(shape: SuperEllipse = <visuals.shapes.SuperEllipse object>, surface_normal: callable = None, order: int = 6, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, calc_3d: bool = False, norm: float = None, crystallinity_threshold: float = None, dark: bool = True)#

Bases: ColorConn

Color all particles by global connectivity, which is just the average local connectivity

See:

ColorBondOrder, ColorConn

calc_state()#

Calculate the average crystal connectivity and set as uniform field (ci).

defectcolor submodule#

Color schemes for highlighting various kinds of defects

class coloring.defectcolor.ColorS2Defects(shape: SuperEllipse = <visuals.shapes.SuperEllipse object>, dark: bool = True, bgColor: ColorBase = None)#

Bases: ColorS2

Color nematic defects cyan.

Highlights particles that disagree with their local nematic director and paints them cyan while delegating non-defect coloring to an optional background ColorBase instance.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to sphere with diameter 1.0

  • dark (bool, optional) – dark theme flag

  • bgColor (ColorBase | None, optional) – optional ColorBase instance providing background colors

Variables:

defects – Boolean mask of defective particles.

calc_state()#

Calls the parent ColorS2.calc_state to compute local nematic quantities, then marks particles as defects when their local orientation misaligns with the local director.

local_colors(snap: Frame = None)#

Return RGBA colors mapping the background colorbase with defects in cyan.

Returns:

(N,4) RGBA array

Return type:

ndarray

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(N_{S2}=00%\)”.

Return type:

str

class coloring.defectcolor.ColorC6Defects(shape: SuperEllipse = <visuals.shapes.SuperEllipse object>, surface_normal: callable = None, nei_cutoff: float = np.float64(1.3660254037844386), periodic: bool = False, norm: float = 6, crystallinity_threshold: float = 0.32, dark: bool = True, bgColor: ColorBase = None)#

Bases: ColorConn

Color sixfold defects \((C_{6} < 1)\) to highlight defects.

This class wraps a connectivity-based color style and overrides the per-particle colors to mark defective sites in red while allowing a configurable background color base.

Parameters:

  • shape (SuperEllipse) – particle geometry, defaults to sphere with diameter 1.0

  • surface_normal (callable | None) – optional surface normal for projected calculations

  • nei_cutoff (float | None, optional) – dimensionless neighbor cutoff distance, defaults to halfway between first and second neighbor shells

  • periodic (bool, optional) – whether to use periodic boundary conditions, defaults to False

  • norm (float | None, optional) – normalization factor for connectivity calculation, defaults to 6

  • crystallinity_threshold (float, optional) – threshold below which particle bonds are marked as defective, defaults to 0.32

  • dark (bool, optional) – dark theme flag

  • bgColor (ColorBase | None, optional) – optional ColorBase instance providing background colors

Variables:

  • defects – Boolean mask of defective particles.

  • con – Per-particle connectivity values inherited from ColorByConn

calc_state()#

Runs the parent’s connectivity calculation then marks particles as defective when connectivity falls below a heuristic threshold.

local_colors(snap: Frame = None)#

Return per-particle RGBA colors highlighting defective particles in red.

Mapping: for dark backgrounds this uses a white->red gradient; for light backgrounds a grey->red gradient.

Returns:

(N,4) RGBA array

Return type:

ndarray

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(\langle1-C_n\rangle=0.00\)”.

Return type:

str

class coloring.defectcolor.ColorC4Defects(shape: SuperEllipse = <visuals.shapes.SuperEllipse object>, surface_normal: callable = None, nei_cutoff: float = 2.6, periodic: bool = False, norm: float = 4, crystallinity_threshold: float = 0.5, dark: bool = True, bgColor: ColorBase = None)#

Bases: ColorConn

Color fourfold defects \((C_{4} < 1)\) to highlight defects.

This variant recalculates connectivity with a tetratic (p=4) normalization and a tightened crystallinity threshold to detect fourfold defect sites.

Parameters:

  • shape (SuperEllipse) – particle geometry

  • surface_normal (callable | None) – optional surface normal for projected calculations

  • nei_cutoff (float | None, optional) – dimensionless neighbor cutoff distance, defaults to 2.6

  • periodic (bool, optional) – periodic boundary conditions flag

  • norm (float | None, optional) – normalization order for connectivity calculation, defaults to 4

  • crystallinity_threshold (float, optional) – threshold below which particle bonds are marked as defective, defaults to 0.5

  • dark (bool, optional) – dark theme flag

  • bgColor (ColorBase | None, optional) – optional ColorBase instance providing background colors

Variables:

defects – Boolean mask of defective particles.

calc_state()#

Recomputes connectivity using crystal_connectivity with norm=4 and a tightened crystallinity threshold before marking defective sites.

local_colors(snap: Frame = None)#

Return per-particle RGBA colors highlighting defective particles in gold.

Returns:

(N,4) RGBA array

Return type:

ndarray

state_string(snap: Frame = None)#
Returns:

LaTeX-formatted summary string. i.e. “\(N_{C4}=00%\)”.

Return type:

str

Contents